软航版式文档服务（RHC Office） SDK

@rhc-office/sdk 是软航版式文档服务的 Web 端阅读器集成 SDK。它负责在第三方应用中加载阅读器、挂载阅读器 Web Component，并把本地或网络文档打开、网络文件保存回传、多文档阅读、页面控制、UI 配置、批注、打印、保存导出、PDF 表单填充和数字签章等能力封装成统一的工具接口，便于业务系统把阅读器嵌入到自己的门户、业务审批、档案管理、合同管理或在线预览流程中。

功能特性

• 阅读器嵌入：在指定 DOM 容器中加载阅读器部署产物，创建 <rhc-office-editor>，并支持配置阅读模式、批注模式、签章模式、语言、主题和菜单显示状态。
• 多格式文档打开：支持 PDF、OFD、Office、图片和文本类型，可通过远程 URL、Base64、ArrayBuffer 或本地文件入口打开文档。
• 网络文件集成：支持通过 fileUrl 打开业务系统中的远程文件，并通过 uploadUrl、HTTP headers、表单字段和文件字段名配置保存回传流程，适合对接对象存储、网盘、档案系统或业务后端。
• 多文档阅读视图：支持阅读器侧多文档打开和标签页式浏览，宿主应用可以按业务场景控制单文档或多文档工作流。
• 保存与导出：支持保存、另存为和导出，导出格式包含 PDF、PNG、JPEG、JPG、TIFF，并可配置页码范围、图片缩放倍率和 JPEG 质量。
• 页面与视图控制：支持跳页、上一页、下一页、缩放、适宽、适高、顺时针/逆时针旋转、单页/双页视图、横向/纵向滚动、书本视图和页面混合背景色。
• UI 配置：支持显示或隐藏 Ribbon 菜单、标题栏和工具区，切换紧凑模式、全屏模式、刷新视图，并可设置阅读器水印。
• 检索能力：支持清空检索结果、查找下一个和查找上一个，便于在宿主应用中接入统一搜索入口。
• 批注能力：支持进入/退出批注视图、文本批注、手写批注、图章批注、模板签标记、批注导入导出、批注列表查询、画笔样式配置、撤销、重做、清空以及保存批注。
• 打印与预览：提供阅读器侧打印和预览入口，可接入阅读器的高保真打印流程；OFD/PDF 场景可由阅读器生成适合系统打印的 PDF 输出，满足矢量化或版式保真打印需求。
• PDF 表单填充：支持打开表单填充模式、设置字段值、控制字段只读状态、提交、清空，并导出表单键值数据。
• 数字签章：支持签章参数配置、签章服务登录、USB Key 认证、外部印章服务、签章回调、签章列表读取、签章验签、签章信息展示和吊销检查等业务流程。
• 模板签与骑缝签：支持创建常规印模、单侧骑缝印模、对称骑缝印模和校核印模，支持列举、删除印模，并可按模板印模执行签章。
• 安全和扩展能力：支持安全 Provider 配置、签章/验签 Provider 管理，以及 PDF417 条码生成等扩展场景。
• 事件和状态：支持监听阅读器就绪、卸载、文档打开、保存、关闭、页码变化等事件，便于宿主应用同步业务状态。
• 数字签名环境配置：支持在挂载阅读器前注入签章默认参数和签章服务配置，便于不同业务系统统一签章环境。

安装

npm install @rhc-office/sdk

基础用法

页面上准备一个挂载容器：

<div id="reader-host" style="width: 100%; height: 100vh"></div>

在应用代码中创建 SDK 实例并挂载阅读器：

import { createNewDocumentSdk } from '@rhc-office/sdk';

const sdk = createNewDocumentSdk();

sdk.addReaderReadyCallback(() => {
  sdk.getDocumentTool().openPDFDocument({
    timestamp: Date.now(),
    fileId: 'sample-pdf',
    fileType: 'application/pdf',
    fileName: 'sample.pdf',
    fileUrl: 'https://example.com/sample.pdf',
  });
});

sdk.embedReader('reader-host', 'https://viewer.example.com/', {
  viewMode: 'View',
  ribbonMenu: true,
  ribbonTitle: true,
});

embedReader(container, appUrl, configuration) 会从 appUrl 加载 editors.bootstrap.js，并在容器内创建 <rhc-office-editor>。

appUrl 通常指向阅读器部署地址。示例中的域名都是占位值，集成时请替换为你自己的阅读器部署地址。

Script 引入

如果宿主页面不使用前端构建工具，可以直接引入预编译的浏览器版本：

<script src="https://unpkg.com/@rhc-office/sdk/dist/browser/document-viewer.js"></script>
<script>
  const sdk = document.newDocumentSDK();

  sdk.addReaderReadyCallback(function () {
    sdk.getDocumentTool().openPDFDocument({
      timestamp: Date.now(),
      fileId: 'sample-pdf',
      fileType: 'application/pdf',
      fileName: 'sample.pdf',
      fileUrl: 'https://example.com/sample.pdf',
    });
  });

  sdk.embedReader('reader-host', 'https://viewer.example.com/', {
    viewMode: 'View',
    ribbonMenu: true,
    ribbonTitle: true,
  });
</script>

浏览器版本会把关键 SDK 入口直接暴露到 document 上：

• document.newDocumentSDK(options?)：创建新的 DocumentSDK 实例。
• document.DocumentSDK：访问 DocumentSDK 构造函数。
• document.createNewDocumentSdk(options?)：模块化 API 中同名工厂方法的浏览器全局入口。
• document.WatermarkDisplay、document.DIGITAL_SIGN_DEFAULTS：访问常用枚举和默认配置。
• document.getDigitalSignEnvironment()、document.patchDigitalSignEnvironment() 等：访问数字签名环境配置方法。
• document.RHCOfficeSDK：保留完整 namespace，便于统一枚举所有浏览器全局 SDK 入口。

如果从 npm 包中自行托管该文件，预编译产物路径为 node_modules/@rhc-office/sdk/dist/browser/document-viewer.js。SDK 构建也会同步一份到本仓库文档站点的 packages/docs/public/sdk/document-viewer.js。

打开文档

DocumentTool 支持 PDF、OFD、Office、图片和文本入口。常用字段如下：

const documentTool = sdk.getDocumentTool();

documentTool.openOFDDocument({
  timestamp: Date.now(),
  fileId: 'contract-ofd',
  fileType: 'application/ofd',
  fileName: 'contract.ofd',
  fileUrl: 'https://example.com/contract.ofd',
  readOnly: false,
  viewMode: 'annotation',
});

也可以传入 fileBase64 或 fileContent，具体字段见 IFileOpenOptions。

保存和导出

await sdk.getDocumentTool().saveAs({
  filename: 'pages',
  format: 'png',
  pages: [1, 3],
  rasterScale: 2,
});

saveAs 返回：

type IFileSaveResult = {
  success: boolean;
  action: 'save-as' | 'export';
  format?: 'pdf' | 'png' | 'jpeg' | 'jpg' | 'tiff';
  filename?: string;
  error?: string;
};

常用工具

const pageTool = sdk.getPageTool();
pageTool.gotoPage(3);
pageTool.fitPageWidth();
pageTool.setPageScale(125);
pageTool.rotateCW();

const uiTool = sdk.getUITool();
uiTool.hideRibbonTitleBar();
uiTool.setCompactMode(true);
uiTool.setWatermark({
  text: 'CONFIDENTIAL',
  display: 'default',
});

const annotationTool = sdk.getAnnotationTool();
annotationTool.openAnnotationView();
annotationTool.selectAnnotationTool('pen');
annotationTool.setAnnotationPenColor('#d93025');
annotationTool.setAnnotationPenWidth(2);

const networkingTool = sdk.getNetworkingTool();
networkingTool.setHttpHeaders([
  sdk.createKVField('Authorization', 'Bearer token'),
]);

const formFiller = sdk.getPdfFormFiller();
formFiller.open();
formFiller.setFormFieldValue('customerName', 'RHC Office');
formFiller.commit();

事件和状态

sdk.addReaderReadyCallback(() => {
  console.log('reader ready');
});

sdk.addReaderUnloadCallback(() => {
  console.log('reader unloaded');
});

sdk.setReaderEventListener((event, payload) => {
  console.log(event, payload);
});

sdk.getDocumentTool().addDocumentSavedCallback((response) => {
  console.log('document saved', response);
});

sdk.getPageTool().addPageChangeCallback((pageIndex, pageCount) => {
  console.log(pageIndex, pageCount);
});

数字签名环境配置

SDK 内置数字签名环境配置的读写接口，便于宿主应用在挂载阅读器前统一注入默认参数：

import { patchDigitalSignEnvironment } from '@rhc-office/sdk';

patchDigitalSignEnvironment({
  defaults: {
    deviceType: 'client',
    rsaMode: 'auto',
    signatureType: 'REGULAR_ESM',
  },
  signServer: {
    authSource: 'Password',
    defaultServer: 'https://sign.example.com',
  },
});

集成注意事项

• SDK 以 ESM 形式发布，可在 Vanilla JavaScript/TypeScript、React、Angular、Vue、Lit、Svelte 等前端应用中使用，也可配合 Vite、Webpack、Rollup、Next.js 等现代构建工具集成。
• 阅读器容器必须有稳定的宽高，否则嵌入后可能无法正确完成首屏布局。
• 调用 removeReader() 可以卸载当前阅读器实例，并释放 SDK 内部保存的 reader 状态。
• 如果文档、图片、Worker 或 WASM 资源跨域加载，需要在资源服务端正确配置 CORS 和 MIME 类型。
• 不要把访问令牌、签章密码、用户凭据等敏感信息硬编码到前端源码中。