mi-float-robot 1.0.0

package/README.md

@@ -0,0 +1,149 @@
+# mi-float-robot
+
+跨框架浮窗智能问答机器人 Web Component。零运行时依赖，任何前端技术栈（Vue2 / Vue3 / React / 纯 HTML）均可使用。
+
+特性：
+
+- 悬浮机器人图标，可拖拽、拖到垃圾桶隐藏
+- 点击弹出 iframe 抽屉，抽屉可拖拽移动、边缘缩放、最小化
+- 位置/尺寸记忆（localStorage）
+- 通过适配器注入开关与样式配置，无内网接口耦合
+- Shadow DOM 样式隔离，不污染宿主页面
+
+## 安装
+
+```bash
+npm i mi-float-robot
+```
+
+## 快速开始
+
+### 方式一：ESM 引入
+
+```js
+import 'mi-float-robot'
+
+// 可选：全局配置
+import { configure } from 'mi-float-robot'
+configure({
+  chatUrl: 'https://your-host/chat?isPure=true',
+  avatar: 'https://your-host/avatar.png'
+})
+```
+
+```html
+<x-float-robot></x-float-robot>
+```
+
+### 方式二：通过 HTML 属性配置（无需 JS）
+
+```html
+<script src="https://unpkg.com/mi-float-robot"></script>
+<x-float-robot
+  chat-url="https://your-host/chat?isPure=true"
+  avatar="https://your-host/avatar.png"
+></x-float-robot>
+```
+
+## 配置
+
+配置优先级：`<x-float-robot>` 属性 > `configure()` > 适配器返回。
+
+### HTML 属性
+
+| 属性 | 说明 |
+| --- | --- |
+| `chat-url` | 聊天页 iframe 地址 |
+| `avatar` | 头像完整 URL（缺省用内置默认头像） |
+| `switch-url` | 开关接口地址（未提供 adapter 时生效） |
+| `config-url` | 配置接口地址（未提供 adapter 时生效） |
+
+### configure(options)
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `chatUrl` | string | 聊天页 iframe 地址 |
+| `avatar` | string | 头像完整 URL |
+| `adapter` | FloatRobotAdapter | 自定义适配器实例 |
+| `switchUrl` | string | 开关接口地址 |
+| `configUrl` | string | 配置接口地址 |
+| `fetch` | Function | 自定义 fetch 函数 |
+
+## 适配器
+
+机器人「是否显示」和「头像/样式」由适配器提供，方便对接你自己的后端接口。
+
+```js
+import { configure, FloatRobotAdapter } from 'mi-float-robot'
+
+class MyAdapter extends FloatRobotAdapter {
+  async getSwitch() {
+    // 返回是否显示机器人
+    return true
+  }
+  async getConfig() {
+    // 返回 null 表示不显示
+    return {
+      showRobot: true,
+      avatar: 'https://your-host/avatar.png',
+      style: {
+        scale: 1,
+        width: 80,
+        height: 100,
+        opacity: 1,
+        border: 'none',
+        shadowLevel: 'light', // none | light | medium | strong
+        borderRadius: 0,
+        borderRadiusUnit: 'px'
+      }
+    }
+  }
+}
+
+configure({ chatUrl: 'https://your-host/chat', adapter: new MyAdapter() })
+```
+
+若不想写适配器，提供一个简单 JSON 接口即可（默认 `FetchFloatRobotAdapter` 用 GET 请求）：
+
+```js
+configure({
+  chatUrl: 'https://your-host/chat',
+  switchUrl: 'https://your-host/api/robot/switch', // 返回 boolean 或 { showRobot: true }
+  configUrl: 'https://your-host/api/robot/config'  // 返回上方 getConfig 的结构
+})
+```
+
+## 在 Vue 中使用
+
+```vue
+<template>
+  <x-float-robot chat-url="https://your-host/chat?isPure=true"></x-float-robot>
+</template>
+
+<script>
+import 'mi-float-robot'
+</script>
+```
+
+## 本地开发
+
+```bash
+npm i
+npm run dev
+```
+
+## 构建
+
+```bash
+npm run build
+# 产出 dist/mi-float-robot.js (ESM) 与 dist/mi-float-robot.umd.cjs (UMD)
+```
+
+## 发布
+
+```bash
+npm login
+npm publish
+```
+
+> 发布到 npm 公共源前，请确认没有把内网地址、密钥、公司 Logo 等敏感信息硬编码进代码。