PingChuan
119 lines
3.7 KiB
Markdown
119 lines
3.7 KiB
Markdown
# Collabora 功能模块说明
|
||
|
||
本目录包含按功能拆分的 Collabora UNO 命令封装模块。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
lib/
|
||
├── README.md # 本说明文档
|
||
├── index.ts # 统一导出所有功能模块
|
||
├── search.ts # 搜索功能
|
||
├── replace.ts # 替换功能
|
||
├── highlight.ts # 高亮功能
|
||
├── navigation.ts # 导航/跳转功能
|
||
├── zoom.ts # 缩放功能
|
||
├── document.ts # 文档操作
|
||
├── pageInfo.ts # 页数信息获取
|
||
└── gotoPage.ts # 自定义页面跳转（不使用 UNO 命令）
|
||
```
|
||
|
||
## 功能模块
|
||
|
||
### 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)` - 滚动到文档开头（带焦点请求）
|
||
|
||
### 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` 接口 - 页数信息类型定义
|
||
|
||
### 8. gotoPage.ts - 自定义页面跳转（不使用 UNO 命令）
|
||
- `customGotoPage(iframeWindow, pageNumber)` - 跳转到指定页面（使用自定义 PostMessage 协议）
|
||
- `GotoPageResponse` 接口 - 页面跳转响应信息类型定义
|
||
|
||
## 使用方式
|
||
|
||
### 方式 1: 从统一入口导入（推荐）
|
||
|
||
```typescript
|
||
import {
|
||
unoSearchText,
|
||
unoReplaceText,
|
||
unoHighlightText,
|
||
unoScrollToTop,
|
||
unoSave,
|
||
customGotoPage,
|
||
requestPageInfo,
|
||
} from '~/components/collabora/lib';
|
||
```
|
||
|
||
### 方式 2: 从具体模块导入
|
||
|
||
```typescript
|
||
import { unoSearchText } from '~/components/collabora/lib/search';
|
||
import { unoScrollToTop } from '~/components/collabora/lib/navigation';
|
||
import { customGotoPage } from '~/components/collabora/lib/gotoPage';
|
||
import { requestPageInfo } from '~/components/collabora/lib/pageInfo';
|
||
```
|
||
|
||
## 核心工具函数
|
||
|
||
核心的命令发送和状态监听函数位于 `../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';
|
||
```
|