feat：完成Collabora初步集成（返回顶部、文档页数获取）

2025-11-25 10:56:47 +08:00
parent 31614374a7
commit 272c3e8dce
14 changed files with 583 additions and 208 deletions
@@ -0,0 +1,111 @@
+# Collabora 功能模块说明
+
+本目录包含按功能拆分的 Collabora UNO 命令封装模块。
+
+## 文件结构
+
+```
+lib/
+├── README.md           # 本说明文档
+├── index.ts            # 统一导出所有功能模块
+├── search.ts           # 搜索功能
+├── replace.ts          # 替换功能
+├── highlight.ts        # 高亮功能
+├── navigation.ts       # 导航/跳转功能
+├── zoom.ts             # 缩放功能
+└── document.ts         # 文档操作
+```
+
+## 功能模块
+
+### 1. search.ts - 搜索功能
+- `unoSearchText(iframeWindow, text)` - 搜索文本
+
+### 2. replace.ts - 替换功能
+- `unoReplaceText(iframeWindow, searchText, replaceText)` - 替换文本
+
+### 3. highlight.ts - 高亮功能
+- `unoHighlightText(iframeWindow, text, color)` - 高亮文本
+- `unoRemoveHighlight(iframeWindow, text)` - 移除高亮
+- `unoEscape(iframeWindow)` - 取消（Escape）
+
+### 4. navigation.ts - 导航/跳转功能
+- `unoScrollToTop(iframeWindow)` - 滚动到文档开头（带焦点请求）
+- `unoGotoPage(iframeWindow, pageNumber)` - 跳转到指定页面
+- `unoFirstPage(iframeWindow)` - 跳转到第一页
+- `unoLastPage(iframeWindow)` - 跳转到最后一页
+
+### 5. zoom.ts - 缩放功能
+- `unoZoomPlus(iframeWindow)` - 放大文档
+- `unoZoomMinus(iframeWindow)` - 缩小文档
+- `unoSetZoom(iframeWindow, percentage)` - 设置缩放比例
+
+### 6. document.ts - 文档操作
+- `unoSave(iframeWindow)` - 保存文档
+
+### 7. pageInfo.ts - 页数信息获取
+- `listenPageNumberChanged(iframeWindow, callback)` - 监听文档页数变化事件
+- `requestPageInfo(iframeWindow)` - 请求页数信息（返回 Promise）
+- `getPageInfoFromCollabora()` - 从 Collabora 内部直接获取页数（仅 iframe 内部可用）
+- `PageInfo` 接口 - 页数信息类型定义
+
+## 使用方式
+
+### 方式 1: 从统一入口导入（推荐）
+
+```typescript
+import {
+  unoSearchText,
+  unoReplaceText,
+  unoHighlightText,
+  unoScrollToTop,
+  unoSave,
+} from '~/components/collabora/lib';
+```
+
+### 方式 2: 从具体模块导入
+
+```typescript
+import { unoSearchText } from '~/components/collabora/lib/search';
+import { unoScrollToTop } from '~/components/collabora/lib/navigation';
+```
+
+## 核心工具函数
+
+核心的命令发送和状态监听函数位于 `../Uno.ts`:
+
+- `sendUnoCommand(iframeWindow, command, args)` - 发送 UNO 命令
+- `unoGetState(iframeWindow)` - 获取文档状态（用于检测命令队列完成）
+
+## 设计原则
+
+1. **单一职责**: 每个文件只负责一个功能领域
+2. **清晰命名**: 文件名直接反映功能（search, replace, highlight 等）
+3. **统一接口**: 所有函数第一个参数都是 `iframeWindow: Window`
+4. **依赖注入**: 通过 import `sendUnoCommand` 而不是重复实现
+5. **便于维护**: 功能独立，修改某个模块不影响其他模块
+
+## 扩展指南
+
+如果需要添加新功能模块:
+
+1. 在 `lib/` 下创建新文件，如 `lib/print.ts`
+2. 实现功能函数，import `sendUnoCommand` from `../Uno`
+3. 在 `lib/index.ts` 中添加导出
+4. 在本 README 中补充说明
+
+示例:
+
+```typescript
+// lib/print.ts
+import { sendUnoCommand } from '../Uno';
+
+export function unoPrint(iframeWindow: Window): void {
+    sendUnoCommand(iframeWindow, '.uno:Print', {});
+}
+```
+
+```typescript
+// lib/index.ts
+export { unoPrint } from './print';
+```