ai-word-editor 0.0.38 → 0.0.40

package/README.md

@@ -1,53 +1,26 @@
-# ai-word-editor（作为组件包使用）
+# ai-word-editor（Vue3 富文本编辑器组件包）
 
-本仓库已改造为 **Vue3 组件包**：你可以把它当成另一个 Vue3 + Vite 项目的依赖来 `import` 使用。
+基于 Vue3 + Vite 的编辑器组件包，提供：
 
-## 0. 安装
+- 编辑器组件：在业务项目中直接使用
+- Word 导出：将 HTML 导出为 `.docx`（可选批注数据）
 
-在你的 Vue3 项目中安装本包（内部会自动依赖所需库）：
+## 环境要求
 
-```bash
-npm install ai-word-editor
-```
+- Node.js：建议 18+
+- Vue：3.x
 
-## 1. 打包
-
-在本仓库执行：
+## 安装
 
 ```bash
-npm run build:lib
-```
-
-产物输出到 `dist/`，类型声明输出到 `dist/types/`。
-
-## 2. 在宿主项目安装（两种方式任选）
-
-### 方式 A：本地 file 依赖（最快，适合本机联调）
-
-宿主项目 `package.json`：
-
-```json
-{
-  "dependencies": {
-    "ai-word-editor": "file:../umo-edior"
-  }
-}
-```
-
-然后在宿主项目执行：
-
-```bash
-npm i
+npm install ai-word-editor
+# 或 pnpm add ai-word-editor
+# 或 yarn add ai-word-editor
 ```
 
-### 方式 B：发布到私有 npm（适合多人/多环境复用）
-
-- 把 `package.json` 的 `"private": true` 改为 `false`，并设置合适的 `name/version` 后发布到你的 npm 仓库。
-- 宿主项目正常 `npm i ai-word-editor` 安装即可。
+## 快速开始（推荐：插件方式）
 
-## 3. 宿主项目使用
-
-在宿主项目 `main.ts`：
+### 1）在 `main.ts` 注册
 
 ```ts
 import { createApp } from 'vue'
@@ -58,7 +31,7 @@ import 'ai-word-editor/style.css'
 createApp(App).use(UmoEditorAppPlugin, {}).mount('#app')
 ```
 
-在任意页面/组件中：
+### 2）在页面中使用
 
 ```vue
 <template>
@@ -66,15 +39,23 @@ createApp(App).use(UmoEditorAppPlugin, {}).mount('#app')
 </template>
 ```
 
-你也可以按需直接导入组件：
+## 重要：`cdn-url` 静态资源（必须配置）
+
+`@umoteam/editor` 运行时需要加载 `@umoteam/editor-external` 的静态资源。
+线上环境不要依赖 `'/node_modules/@umoteam/editor-external'` 这类路径（通常不可用）。
+
+推荐做法：
+
+- 将 `node_modules/@umoteam/editor-external` 复制/同步到宿主项目 `public/umo-editor-external/`
+- 然后组件传入：`cdn-url="/umo-editor-external"`
+
+## 按需使用（只导入组件）
 
 ```ts
 import { UmoEditorApp } from 'ai-word-editor'
 ```
 
-## 4. 单独使用 Word 导出工具
-
-如果你只想复用导出 `.docx` 的能力，可以单独按需引入工具函数，而不使用整个编辑器组件：
+## Word 导出（仅使用导出能力）
 
 ### `exportToDocx`（带批注）
 
@@ -86,12 +67,10 @@ await exportToDocx(html, comments, '文件名')
 
 - `html`：编辑器生成的 HTML 字符串（例如 Tiptap 的 `editor.getHTML()`）
 - `comments`：批注数组，形如 `[{ id, note, author, createdAt, resolved }]`
-- `'文件名'`：导出的文件名（不含 `.docx` 扩展名，默认为 `'文档'`）
+- `'文件名'`：导出的文件名（不含 `.docx`），默认为 `'文档'`
 
 ### `exportHtmlToDocx`（纯 HTML，无批注）
 
-如果不需要处理批注数据，可以使用更简洁的通用方法：
-
 ```ts
 import { exportHtmlToDocx } from 'ai-word-editor/word-docx-export'
 
@@ -99,16 +78,30 @@ await exportHtmlToDocx(html, '文件名')
 ```
 
 - `html`：编辑器生成的 HTML 字符串
-- `'文件名'`：导出的文件名（不含 `.docx` 扩展名，默认为 `'文档'`）
+- `'文件名'`：导出的文件名（不含 `.docx`），默认为 `'文档'`
 
-需要在宿主项目中安装 `file-saver`、`jszip` 作为依赖。
+依赖说明：
 
-## 5. 重要：`cdnUrl` 静态资源
+- 宿主项目需安装 `file-saver`、`jszip`
 
-`@umoteam/editor` 需要加载 `@umoteam/editor-external` 的静态资源。**不要依赖** `'/node_modules/@umoteam/editor-external'` 这种路径（线上通常不可用）。
+## FAQ
 
-推荐做法：
+- 页面空白/资源 404：优先检查 `cdn-url` 是否指向已同步到 `public` 的资源目录。
+- 导出失败：确认宿主项目已安装 `file-saver`、`jszip`，并检查运行环境是否允许下载文件。
 
-- 在宿主项目把 `node_modules/@umoteam/editor-external` 复制/同步到宿主的 `public/umo-editor-external/`
-- 然后组件传入：`cdn-url="/umo-editor-external"`
+## 联系方式
+
+- 微信：扫码添加（备注：ai-word-editor）
+
+![微信二维码](assets/wechat.jpg)
+
+## 本仓库打包与发布（维护者）
+
+在本仓库执行：
+
+```bash
+npm run build:lib
+```
+
+产物输出到 `dist/`，类型声明输出到 `dist/types/`。