@bireturn/word-editor 1.0.3 → 1.0.4

package/README.md

@@ -1,298 +1,298 @@
-# @bireturn/word-editor
-
-类 Word 的 Web 富文本编辑器，目前只实现了只读渲染功能，基于 Vue 3 + Vite + TypeScript。参考 [canvas-editor](https://github.com/Hufe921/canvas-editor) 的数据结构与命令系统设计，但使用 **DOM 渲染**代替 Canvas，并通过虚拟滚动支撑大文档。
-
-## 安装
-
-```bash
-npm install @bireturn/word-editor
-```
-
-> 需宿主项目提供 `vue ^3.4`（已声明为 `peerDependency`，避免重复打包与多实例）。
-
-## 使用
-
-数据由使用方通过 `props` 传入，组件本身不发请求：
-
-```vue
-<script setup>
-import { EditorContainer } from '@bireturn/word-editor'
-import '@bireturn/word-editor/style.css'   // 必须引入样式
-import { ref, onMounted } from 'vue'
-
-const docData = ref([])   // IElement[]，来源由使用方决定
-const loading = ref(false)
-
-onMounted(async () => {
-  loading.value = true
-  docData.value = await fetchDoc()   // 使用方自己的数据源
-  loading.value = false
-})
-</script>
-
-<template>
-  <EditorContainer :data="docData" :loading="loading" />
-</template>
-```
-
-也可通过 `app.use()` 全局注册：
-
-```ts
-import WordEditor from '@bireturn/word-editor'
-import '@bireturn/word-editor/style.css'
-
-app.use(WordEditor)   // 注册全局组件 <EditorContainer />
-```
-
-### Props
-
-| 名称 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `data` | `IElement[]` | `[]` | 文档结构数据，渲染所需的行内元素列表 |
-| `loading` | `boolean` | `false` | 外部数据加载态，为 `true` 时显示加载占位 |
-
-## 特性
-
-- 数据驱动渲染：文档数据模型是唯一数据源，DOM 仅作视图
-- 命令系统（Command Pattern）：所有写操作经 `editor.exec()` 分发，统一支持撤销/重做
-- 虚拟滚动：以段落为最小单元，配合自研 `VirtualTable` 支撑大文档
-- A4 分页排版：按页面内容高度自动分页，支持页眉/页脚、连续图片与表格跨页拆分
-- 富内容：文本、图片、超链接、表格、控件（文本/输入/单选）、上下标、复选框等
-- 插件机制：通过 `editor.use()` 注入自定义命令与能力
-
-## 技术栈
-
-| 类别 | 选型 |
-| --- | --- |
-| 框架 | Vue 3（Composition API） |
-| 构建 | Vite 5 + TypeScript 5 |
-| 状态 | Pinia |
-| 图标 | lucide-vue-next |
-| 工具 | @vueuse/core、lodash-es |
-| 虚拟滚动 | vue-virtual-scroller + 自研 VirtualTable |
-| Mock | vite-plugin-mock-dev-server |
-
-## 快速开始
-
-```bash
-npm install          # 安装依赖
-npm run dev          # 启动开发服务器（默认 http://localhost:5173）
-```
-
-开发态接口由 `mock/` 提供，可完全离线运行，无需后端。
-
-## 常用命令
-
-```bash
-npm run dev          # 启动开发服务器
-npm run build        # 构建可部署的应用产物
-npm run build:lib    # 构建组件库产物（lib/，含 ESM/UMD + 类型声明）
-npm run preview      # 本地预览构建产物
-npm run lint         # ESLint 检查并自动修复
-npm run type-check   # 仅做 TypeScript 类型检查
-```
-
-## 构建与本地联调
-
-本项目可同时作为**独立应用**与**组件库**使用。`vite.config.ts` 按 `mode` 区分两种产物：默认模式构建应用，`--mode lib`（即 `npm run build:lib`）构建组件库。
-
-### 构建产物
-
-```bash
-npm run build:lib
-```
-
-产物输出到 `lib/`：
-
-| 文件 | 说明 |
-| --- | --- |
-| `word-editor.es.js` | ESM 格式,供打包工具按需引入 |
-| `word-editor.umd.js` | UMD 格式,供浏览器/旧环境直接引用 |
-| `word-editor.css` | 组件样式,需由使用方手动引入 |
-| `index.d.ts` | TypeScript 类型声明 |
-
-`vue` 被声明为 `peerDependencies` 并在构建时外置,由使用方提供,避免重复打包与多实例问题。
-
-### 本地联调（不发布到 npm）
-
-构建后,在**消费方项目**通过本地路径安装,推荐 `file:` 方式：
-
-```jsonc
-// 消费方 package.json
-{
-  "dependencies": {
-    "@bireturn/word-editor": "file:../word-editor"   // 改成实际路径
-  }
-}
-```
-
-```bash
-npm install
-```
-
-改动本库后,重跑 `npm run build:lib` 并重启消费方 dev server 即可生效。也可用 `npm pack` 生成 `.tgz` 后安装(更贴近真实发布),或 `npm link`(改库实时联动)。
-
-> ⚠️ 若用 `file:` / `npm link` 出现 Vue 响应式失效或 inject 报错,通常是加载了两份 Vue。在消费方 `vite.config.ts` 加 `resolve.dedupe: ['vue']` 与 `optimizeDeps.include: ['@bireturn/word-editor']` 去重即可。
-
-### 发布到 npm
-
-```bash
-npm run build:lib        # 先构建产物到 lib/
-npm publish --access public   # scoped 包首次发布需加 --access public
-```
-
-> 仅 `lib/` 会随包发布（由 `package.json` 的 `files` 字段约定）。
-
-## Mock 数据
-
-开发态接口基于 [vite-plugin-mock-dev-server](https://github.com/pengzhanbo/vite-plugin-mock-dev-server) 实现，配置见 [`mock/api.mock.ts`](mock/api.mock.ts)，数据文件存放于 [`mock/json/`](mock/json/)，可完全离线运行、无需后端。
-
-### 接口约定
-
-前端通过 [`src/api/file.ts`](src/api/file.ts) 的 `getStructInfo()` 请求 `/api/info`，期望返回文档结构数组 `IElement[]`（即 `DocumentModel` 渲染所需的行内元素列表）。
-
-`mock/api.mock.ts` 中有两类挂载方式：
-
-- **约定式**（`apiList`）：`/api/xxx` 自动读取 `mock/json/xxx.json`，默认延迟 300ms
-- **自定义式**（`customApis`）：显式指定 url 与数据文件，可单独设置延迟。当前 `/api/info` 即在此挂载
-
-### 切换测试数据
-
-修改 `customApis` 中 `/api/info` 读取的 json 文件即可切换渲染数据，例如：
-
-```ts
-const customApis = [
-  {
-    url: '/api/info',
-    delay: 1000,
-    body: () =>
-      JSON.parse(
-        fs.readFileSync(path.resolve(root, `./mock/json/info.json`), 'utf8')
-      )
-  }
-]
-```
-
-### 数据文件清单
-
-所有文件均为顶层 `IElement[]` 数组，元素以 `type` 区分（`text` / `table` / `image` / `hyperlink` / `control` / `list` 等）。
-
-| 文件 | 体积 | 元素数 | 主要内容 | 用途 |
-| --- | --- | --- | --- | --- |
-| `info.json` | ~1.6 MB | 81 | 文本、9 个表格、控件、超链接 | 常规文档，功能演示基线 |
-| `pagetable.json` | ~388 KB | 1 | 单个跨页大表格（77 行） | 表格分页与行渲染调试 |
-| `page1000.json` | ~32 MB | 84 | 84 个表格 | 大量表格的分页/性能压测 |
-| `page69.json` | ~85 MB | 2323 | 文本、198 表格、列表、控件 | 超大文档虚拟滚动压测 |
-| `page69i.json` | ~85 MB | 2344 | 在 `page69` 基础上增加 18 张图片 | 含图片的超大文档压测 |
-
-> 说明：`page69*` / `page1000` 体积较大，仅用于性能与边界场景验证，日常开发建议使用 `info.json` 或 `pagetable.json`。
-
-### 元素数据结构
-
-各 `type` 的字段含义见 [`docs/0.JSON数据类型说明.md`](docs/0.JSON数据类型说明.md) 与 [`docs/1.页面样式属性说明.md`](docs/1.页面样式属性说明.md)。
-
-## 核心设计原则
-
-1. **数据模型是唯一数据源**，DOM 只是视图，不存储状态
-2. **contenteditable 仅用于输入捕获**，不用于渲染（透明 overlay 模式）
-3. **所有写操作必须通过 `editor.exec()`**，不能直接修改 `docModel`
-4. **大文档通过虚拟滚动**实现，段落是虚拟列表的最小单元
-
-## 目录结构
-
-```
-src/
-├── core/                       # 纯 TypeScript，与 Vue 无关
-│   ├── editor/Editor.ts        # 编辑器主类，所有子系统的聚合入口
-│   ├── model/DocumentModel.ts  # 文档数据模型，所有原子修改方法在此
-│   ├── command/                # 命令系统
-│   │   ├── CommandManager.ts   # exec() 分发，注册/执行命令
-│   │   └── commands/           # InsertText / Delete / Format / InsertParagraph 等
-│   ├── selection/SelectionManager.ts  # 模型坐标系的光标/选区
-│   ├── history/HistoryManager.ts      # undo/redo 栈
-│   └── input/InputHandler.ts   # DOM 事件 → exec() 转换层
-├── composables/
-│   ├── useEditor.ts            # provide/inject Editor 实例
-│   └── useDocumentData.ts      # 从 docModel 提取响应式数据
-├── components/
-│   ├── Editor/                 # 编辑器根组件（含分页、表格、页眉页脚渲染）
-│   └── VirtualTable/           # 自研虚拟表格组件
-├── api/                        # 接口请求封装
-└── types/                      # 全局类型（document/selection/command/plugin）
-
-mock/                           # vite mock，离线可用的接口数据
-docs/                           # 功能说明与问题分析文档
-```
-
-## 架构
-
-### 数据流
-
-```
-用户输入（键盘/鼠标）
-  → InputHandler（DOM 事件拦截）
-  → editor.exec(commandName, payload)
-  → CommandManager（查找命令工厂）
-  → ICommand.execute()（修改 DocumentModel）
-  → Vue 响应式自动触发重渲染
-  → 组件根据最新 docModel 渲染 DOM
-```
-
-### 数据模型
-
-```
-DocumentModel
-  └── sections[]          # 节（分页/分栏单位）
-        └── paragraphs[]  # 段落（块级，虚拟滚动的最小单元）
-              └── children: IElement[]  # 行内元素（文本/图片/超链接/表格等）
-```
-
-### 坐标系
-
-所有位置用 `ModelPoint` 表示：
-
-```ts
-{ sectionIndex, paragraphIndex, elementIndex, offset }
-```
-
-DOM 元素通过 `data-si / data-pi / data-ei` 属性反向映射回模型坐标（见 `SelectionManager.domToModelPoint`）。
-
-## 扩展
-
-### 注册命令
-
-在 `CommandManager._registerBuiltinCommands()` 中注册，或通过插件注入：
-
-```ts
-editor.commands.register('myCommand', (payload) => new MyCommand(...))
-```
-
-命令须实现 `ICommand`（`execute` + `undo`），可选实现 `canMergeWith` / `merge` 以支持连续输入合并。
-
-### 插件
-
-```ts
-editor.use({
-  name: 'my-plugin',
-  install(editor) {
-    editor.commands.register('customCommand', ...)
-  }
-})
-```
-
-### 新增元素类型
-
-需同时更新：
-
-- `src/types/document.ts`（类型定义）
-- `src/components/Editor/index.vue`（渲染逻辑）
-
-## 关键约束
-
-- 禁止在渲染组件中直接修改 `docModel`
-- 禁止在 `InputHandler` 中直接修改 `docModel`（必须通过 `exec`）
-- `DocumentModel` 的原子方法（`insertText` / `deleteAt` 等）只能由 Command 调用
-
-## 文档
-
-更多功能说明与问题分析见 [`docs/`](docs/) 目录。
+# @bireturn/word-editor
+
+类 Word 的 Web 富文本编辑器，目前只实现了只读渲染功能，基于 Vue 3 + Vite + TypeScript。参考 [canvas-editor](https://github.com/Hufe921/canvas-editor) 的数据结构与命令系统设计，但使用 **DOM 渲染**代替 Canvas，并通过虚拟滚动支撑大文档。
+
+## 安装
+
+```bash
+npm install @bireturn/word-editor
+```
+
+> 需宿主项目提供 `vue ^3.4`（已声明为 `peerDependency`，避免重复打包与多实例）。
+
+## 使用
+
+数据由使用方通过 `props` 传入，组件本身不发请求：
+
+```vue
+<script setup>
+import { EditorContainer } from '@bireturn/word-editor'
+import '@bireturn/word-editor/style.css'   // 必须引入样式
+import { ref, onMounted } from 'vue'
+
+const docData = ref([])   // IElement[]，来源由使用方决定
+const loading = ref(false)
+
+onMounted(async () => {
+  loading.value = true
+  docData.value = await fetchDoc()   // 使用方自己的数据源
+  loading.value = false
+})
+</script>
+
+<template>
+  <EditorContainer :data="docData" :loading="loading" />
+</template>
+```
+
+也可通过 `app.use()` 全局注册：
+
+```ts
+import WordEditor from '@bireturn/word-editor'
+import '@bireturn/word-editor/style.css'
+
+app.use(WordEditor)   // 注册全局组件 <EditorContainer />
+```
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `IElement[]` | `[]` | 文档结构数据，渲染所需的行内元素列表 |
+| `loading` | `boolean` | `false` | 外部数据加载态，为 `true` 时显示加载占位 |
+
+## 特性
+
+- 数据驱动渲染：文档数据模型是唯一数据源，DOM 仅作视图
+- 命令系统（Command Pattern）：所有写操作经 `editor.exec()` 分发，统一支持撤销/重做
+- 虚拟滚动：以段落为最小单元，配合自研 `VirtualTable` 支撑大文档
+- A4 分页排版：按页面内容高度自动分页，支持页眉/页脚、连续图片与表格跨页拆分
+- 富内容：文本、图片、超链接、表格、控件（文本/输入/单选）、上下标、复选框等
+- 插件机制：通过 `editor.use()` 注入自定义命令与能力
+
+## 技术栈
+
+| 类别 | 选型 |
+| --- | --- |
+| 框架 | Vue 3（Composition API） |
+| 构建 | Vite 5 + TypeScript 5 |
+| 状态 | Pinia |
+| 图标 | lucide-vue-next |
+| 工具 | @vueuse/core、lodash-es |
+| 虚拟滚动 | vue-virtual-scroller + 自研 VirtualTable |
+| Mock | vite-plugin-mock-dev-server |
+
+## 快速开始
+
+```bash
+npm install          # 安装依赖
+npm run dev          # 启动开发服务器（默认 http://localhost:5173）
+```
+
+开发态接口由 `mock/` 提供，可完全离线运行，无需后端。
+
+## 常用命令
+
+```bash
+npm run dev          # 启动开发服务器
+npm run build        # 构建可部署的应用产物
+npm run build:lib    # 构建组件库产物（lib/，含 ESM/UMD + 类型声明）
+npm run preview      # 本地预览构建产物
+npm run lint         # ESLint 检查并自动修复
+npm run type-check   # 仅做 TypeScript 类型检查
+```
+
+## 构建与本地联调
+
+本项目可同时作为**独立应用**与**组件库**使用。`vite.config.ts` 按 `mode` 区分两种产物：默认模式构建应用，`--mode lib`（即 `npm run build:lib`）构建组件库。
+
+### 构建产物
+
+```bash
+npm run build:lib
+```
+
+产物输出到 `lib/`：
+
+| 文件 | 说明 |
+| --- | --- |
+| `word-editor.es.js` | ESM 格式,供打包工具按需引入 |
+| `word-editor.umd.js` | UMD 格式,供浏览器/旧环境直接引用 |
+| `word-editor.css` | 组件样式,需由使用方手动引入 |
+| `index.d.ts` | TypeScript 类型声明 |
+
+`vue` 被声明为 `peerDependencies` 并在构建时外置,由使用方提供,避免重复打包与多实例问题。
+
+### 本地联调（不发布到 npm）
+
+构建后,在**消费方项目**通过本地路径安装,推荐 `file:` 方式：
+
+```jsonc
+// 消费方 package.json
+{
+  "dependencies": {
+    "@bireturn/word-editor": "file:../word-editor"   // 改成实际路径
+  }
+}
+```
+
+```bash
+npm install
+```
+
+改动本库后,重跑 `npm run build:lib` 并重启消费方 dev server 即可生效。也可用 `npm pack` 生成 `.tgz` 后安装(更贴近真实发布),或 `npm link`(改库实时联动)。
+
+> ⚠️ 若用 `file:` / `npm link` 出现 Vue 响应式失效或 inject 报错,通常是加载了两份 Vue。在消费方 `vite.config.ts` 加 `resolve.dedupe: ['vue']` 与 `optimizeDeps.include: ['@bireturn/word-editor']` 去重即可。
+
+### 发布到 npm
+
+```bash
+npm run build:lib        # 先构建产物到 lib/
+npm publish --access public   # scoped 包首次发布需加 --access public
+```
+
+> 仅 `lib/` 会随包发布（由 `package.json` 的 `files` 字段约定）。
+
+## Mock 数据
+
+开发态接口基于 [vite-plugin-mock-dev-server](https://github.com/pengzhanbo/vite-plugin-mock-dev-server) 实现，配置见 [`mock/api.mock.ts`](mock/api.mock.ts)，数据文件存放于 [`mock/json/`](mock/json/)，可完全离线运行、无需后端。
+
+### 接口约定
+
+前端通过 [`src/api/file.ts`](src/api/file.ts) 的 `getStructInfo()` 请求 `/api/info`，期望返回文档结构数组 `IElement[]`（即 `DocumentModel` 渲染所需的行内元素列表）。
+
+`mock/api.mock.ts` 中有两类挂载方式：
+
+- **约定式**（`apiList`）：`/api/xxx` 自动读取 `mock/json/xxx.json`，默认延迟 300ms
+- **自定义式**（`customApis`）：显式指定 url 与数据文件，可单独设置延迟。当前 `/api/info` 即在此挂载
+
+### 切换测试数据
+
+修改 `customApis` 中 `/api/info` 读取的 json 文件即可切换渲染数据，例如：
+
+```ts
+const customApis = [
+  {
+    url: '/api/info',
+    delay: 1000,
+    body: () =>
+      JSON.parse(
+        fs.readFileSync(path.resolve(root, `./mock/json/info.json`), 'utf8')
+      )
+  }
+]
+```
+
+### 数据文件清单
+
+所有文件均为顶层 `IElement[]` 数组，元素以 `type` 区分（`text` / `table` / `image` / `hyperlink` / `control` / `list` 等）。
+
+| 文件 | 体积 | 元素数 | 主要内容 | 用途 |
+| --- | --- | --- | --- | --- |
+| `info.json` | ~1.6 MB | 81 | 文本、9 个表格、控件、超链接 | 常规文档，功能演示基线 |
+| `pagetable.json` | ~388 KB | 1 | 单个跨页大表格（77 行） | 表格分页与行渲染调试 |
+| `page1000.json` | ~32 MB | 84 | 84 个表格 | 大量表格的分页/性能压测 |
+| `page69.json` | ~85 MB | 2323 | 文本、198 表格、列表、控件 | 超大文档虚拟滚动压测 |
+| `page69i.json` | ~85 MB | 2344 | 在 `page69` 基础上增加 18 张图片 | 含图片的超大文档压测 |
+
+> 说明：`page69*` / `page1000` 体积较大，仅用于性能与边界场景验证，日常开发建议使用 `info.json` 或 `pagetable.json`。
+
+### 元素数据结构
+
+各 `type` 的字段含义见 [`docs/0.JSON数据类型说明.md`](docs/0.JSON数据类型说明.md) 与 [`docs/1.页面样式属性说明.md`](docs/1.页面样式属性说明.md)。
+
+## 核心设计原则
+
+1. **数据模型是唯一数据源**，DOM 只是视图，不存储状态
+2. **contenteditable 仅用于输入捕获**，不用于渲染（透明 overlay 模式）
+3. **所有写操作必须通过 `editor.exec()`**，不能直接修改 `docModel`
+4. **大文档通过虚拟滚动**实现，段落是虚拟列表的最小单元
+
+## 目录结构
+
+```
+src/
+├── core/                       # 纯 TypeScript，与 Vue 无关
+│   ├── editor/Editor.ts        # 编辑器主类，所有子系统的聚合入口
+│   ├── model/DocumentModel.ts  # 文档数据模型，所有原子修改方法在此
+│   ├── command/                # 命令系统
+│   │   ├── CommandManager.ts   # exec() 分发，注册/执行命令
+│   │   └── commands/           # InsertText / Delete / Format / InsertParagraph 等
+│   ├── selection/SelectionManager.ts  # 模型坐标系的光标/选区
+│   ├── history/HistoryManager.ts      # undo/redo 栈
+│   └── input/InputHandler.ts   # DOM 事件 → exec() 转换层
+├── composables/
+│   ├── useEditor.ts            # provide/inject Editor 实例
+│   └── useDocumentData.ts      # 从 docModel 提取响应式数据
+├── components/
+│   ├── Editor/                 # 编辑器根组件（含分页、表格、页眉页脚渲染）
+│   └── VirtualTable/           # 自研虚拟表格组件
+├── api/                        # 接口请求封装
+└── types/                      # 全局类型（document/selection/command/plugin）
+
+mock/                           # vite mock，离线可用的接口数据
+docs/                           # 功能说明与问题分析文档
+```
+
+## 架构
+
+### 数据流
+
+```
+用户输入（键盘/鼠标）
+  → InputHandler（DOM 事件拦截）
+  → editor.exec(commandName, payload)
+  → CommandManager（查找命令工厂）
+  → ICommand.execute()（修改 DocumentModel）
+  → Vue 响应式自动触发重渲染
+  → 组件根据最新 docModel 渲染 DOM
+```
+
+### 数据模型
+
+```
+DocumentModel
+  └── sections[]          # 节（分页/分栏单位）
+        └── paragraphs[]  # 段落（块级，虚拟滚动的最小单元）
+              └── children: IElement[]  # 行内元素（文本/图片/超链接/表格等）
+```
+
+### 坐标系
+
+所有位置用 `ModelPoint` 表示：
+
+```ts
+{ sectionIndex, paragraphIndex, elementIndex, offset }
+```
+
+DOM 元素通过 `data-si / data-pi / data-ei` 属性反向映射回模型坐标（见 `SelectionManager.domToModelPoint`）。
+
+## 扩展
+
+### 注册命令
+
+在 `CommandManager._registerBuiltinCommands()` 中注册，或通过插件注入：
+
+```ts
+editor.commands.register('myCommand', (payload) => new MyCommand(...))
+```
+
+命令须实现 `ICommand`（`execute` + `undo`），可选实现 `canMergeWith` / `merge` 以支持连续输入合并。
+
+### 插件
+
+```ts
+editor.use({
+  name: 'my-plugin',
+  install(editor) {
+    editor.commands.register('customCommand', ...)
+  }
+})
+```
+
+### 新增元素类型
+
+需同时更新：
+
+- `src/types/document.ts`（类型定义）
+- `src/components/Editor/index.vue`（渲染逻辑）
+
+## 关键约束
+
+- 禁止在渲染组件中直接修改 `docModel`
+- 禁止在 `InputHandler` 中直接修改 `docModel`（必须通过 `exec`）
+- `DocumentModel` 的原子方法（`insertText` / `deleteAt` 等）只能由 Command 调用
+
+## 文档
+
+更多功能说明与问题分析见 [`docs/`](docs/) 目录。