leaudit-platform-frontend/app/components/collabora/lib/README.md

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: 从统一入口导入（推荐）

import {
  unoSearchText,
  unoReplaceText,
  unoHighlightText,
  unoScrollToTop,
  unoSave,
} from '~/components/collabora/lib';

方式 2: 从具体模块导入

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 中补充说明

示例:

// lib/print.ts
import { sendUnoCommand } from '../Uno';

export function unoPrint(iframeWindow: Window): void {
    sendUnoCommand(iframeWindow, '.uno:Print', {});
}

// lib/index.ts
export { unoPrint } from './print';