# 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';
```