开发者需知道的 ONLYOFFICE API 9.4更新内容

ONLYOFFICE 版本9.4带来了主要的 API 改进，适用于集成、自定义插件和电子表格自动化。本文重点介绍了在 ONLYOFFICE 文档 API、插件和宏 API 以及 Office JavaScript API 中的关键更新，并解释了这些更新对开发者的意义。

ONLYOFFICE 文档 API 9.4

克罗地亚语支持

克罗地亚语（hr）已被添加到支持的接口语言列表中。如果您正在为讲克罗地亚语的用户构建本地化应用程序，可以在语言配置中直接使用它，而无需任何变通方法。

onStartFilling 事件中的角色和用户数据

onStartFilling 事件现在包含了一个 roles 参数，携带了角色和用户信息。让构建基于角色的表单填写体验更轻松，例如，能够将用户路由到他们负责的字段，或根据填写表单的人员和角色触发条件逻辑。

function onStartFilling(event) {
  const roles = event.data;
  console.log("角色:", roles);
}

const config = {
  // ...
  events: {
    onStartFilling,
  },
};
const docEditor = new DocsAPI.DocEditor("placeholder", config);

destroyEditor 中的内存泄漏修复

destroyEditor 方法中的内存泄漏问题已被修复。之前调用 destroyEditor 时并未完全清理已分配的资源。如果您的应用程序频繁创建和销毁编辑器实例（如在单页面应用设置或文档预览工作流中），此修复将直接改善集成的内存占用。

已移除字段

已弃用的 editorConfig.customization.commentAuthorOnly 字段已被移除。如果您的集成仍然引用此参数，现在是时候将其删除以避免任何意外行为。

插件命令日志记录以便于调试

对于插件开发者来说，最实用的新增功能之一就是插件命令日志记录。在浏览器控制台中直接启用插件命令的调试输出。如果您通过猜测实际发生的命令来调试插件行为，那么此功能可以大大减少这种摩擦。它让您可以直接看到插件执行流程，而无需自己进行日志记录。

加载时阻止特定插件

新的 editorConfig.plugins.disable 参数允许您在编辑器初始化时阻止特定插件加载。这在您将编辑器嵌入受控环境并希望限制用户功能以适应相关内容时非常有用，而无需修改插件文件本身。这是一种更清晰的配置层次方法来管理插件表面。

查看文档 API 的完整更改日志

ONLYOFFICE 插件和宏 API 9.4

新的光标控制方法

为文档 API 添加了两个新的 window.Asc.plugin.executeMethod 方法：

• MoveCursorToField：将光标移动到特定表单字段；
• MoveCursorOutsideField：将光标移动到当前字段之外的位置。

Asc.plugin.executeMethod("MoveCursorToField", [fieldId, true]);

Asc.plugin.executeMethod("MoveCursorOutsideField", [fieldId, false]);

这些方法对于引导用户完成表单或自动逐字段导航的插件尤其有用。您的插件可以通过编程方式控制光标位置，而无需依赖用户交互来推进字段。

改进的 StartAction 和 EndAction 控制

StartAction 方法接受两个新参数：lockScroll 和 keepSelection。EndAction 方法增加了 scrollToTarget 和 cancel。这些改进使插件在宏执行期间对编辑器状态的控制更加精细。您可以保留用户的选择，防止在自动操作时出现不必要的滚动，或以更清晰的方式取消操作序列，所有这些都有助于创造更稳定和可预测的插件体验。

查看插件和宏 API 的完整更改日志

Office JavaScript API 9.4

这是 9.4 版本中功能最强大的部分。Office JavaScript API 在文档操作、电子表格数据管理、表单控件等方面有了新功能。查看新方法的完整列表

文档合并

为文档 API 添加了一个新的 Api/MergeDocuments 方法。这使您可以将多个文档合并为一个，这是在报告生成、合同组装和批量文档处理等自动化场景中经常要求的功能。

跨所有编辑器的统一颜色 API

Api/Color 方法在文本文档、电子表格、演示文稿和 PDF API 中可用。在所有四种编辑器类型中拥有一致的颜色接口简化了需要在不同文档格式之间应用样式的代码。您不再需要针对常见操作编写特定格式的颜色处理逻辑。

签名表单支持

版本 9.4 加入了 ApiSignatureForm 类，适用于文档 API 和表单 API。随着它，新增了 GetValue 和 SetValue 方法，用于读取和写入签名字段数据。这开启了对签名字段的编程处理，对需要预填充、验证或提取签名数据作为更大文档处理管道一部分的工作流程非常有用。

// ApiSignatureForm 的 GetValue 方法返回表单中存储的签名图像数据。

// 创建签名表单，将其添加到文档中，并读取其当前值。

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Signature", "tip": "请在此签名", "required": true, "placeholder": "签名"});
signatureForm.Value = "https://static.onlyoffice.com/assets/docs/samples/img/onlyoffice_logo.png";
let paragraph = doc.GetElement(0);
paragraph.AddElement(signatureForm);
let value = signatureForm.GetValue();
paragraph = Api.CreateParagraph();
paragraph.AddText("签名表单的值: " + value);
doc.Push(paragraph);

此外，新的 Api/CreateSignatureForm 方法在表单 API 中允许您通过代码从头创建签名表单字段，而无需依赖手动插入。

表单状态检测

新增的 ApiFormBase/IsFilled 方法，适用于文档 API 和表单 API，允许您检查给定的表单字段是否已填写。这是任何验证或提交逻辑的一个简单但重要的补充。检查表单完成状态时，无需直接解析字段内容。

表单高亮检查

在文档和表单 API 中新增了两个方法（ApiDocument/GetFormsHighlight 和 ApiDocument/GetControlsHighlight）。这些方法让您可以检索应用于表单字段和内容控件的当前高亮设置。如果您的集成管理表单显示配置或需要在外部 UI 元素中反映高亮状态，这些方法提供了之前缺失的读取访问。

扩展的电子表格列表对象 API

这是 9.4 中最强的新增功能之一。电子表格 API 包含一个完整的 ApiListObject 类，用于处理结构化表对象（列表对象），以及支持列、行和排序的类。

关键功能包括：

• 通过 ApiWorksheet/AddListObject 和 ApiWorksheet/GetListObjects 创建和检索列表对象
• 读取和写入表属性，如名称、显示名称、替代文本、样式、标题、总计和自动筛选设置
• 访问表范围，包括标题行、数据主体范围和总计行
• 通过 ApiListColumn 和 ApiListRow 管理列和行，提供名称、索引、范围、总计计算和删除的方法
• 通过新的 ApiSort、ApiSortFields 和 ApiSortField 类提供排序支持，涵盖排序方向、匹配大小写、排序条件（值或颜色）、优先级等

如果您的集成涉及电子表格中的任何结构化数据管理，例如数据导入、动态表创建、报告生成等。该新增功能显著扩展了您可完成的操作，而无需用户手动操作表格。

新的电子表格填充和公式方法

为 ApiRange 添加了四个方向填充方法：FillDown、FillUp、FillRight、FillLeft。

这些方法反映了用户手动触发的电子表格填充行为，现在可用于编程。结合新的 ApiRange/SetFormula 方法，您可以构建动态生成公式驱动的范围的自动化。这对于生成报告、模板电子表格和数据录入自动化非常有用。

在电子表格 API 中还新增了 Api/GetDefNames 方法，允许您访问工作簿中的定义名称（命名范围）。

文本表单格式控制

ApiTextForm 类在文档和表单 API 中新增了四个方法：

• GetFormat/SetFormat：读取并应用格式掩码到文本字段
• GetAllowedSymbols/SetAllowedSymbols：控制用户可以输入的字符

这些方法对于构建验证数据录入表单至关重要，例如，强制日期格式、限制输入为数字字符，或者为电话号码或身份证号应用自定义掩码。

段落属性检查

在文档 API 中为 ApiParaPr 添加了一组 Get 方法，涵盖：

• 边框属性：上、左、右、下、中间
• 分页：GetKeepLines、GetKeepNext、GetPageBreakBefore、GetWidowControl
• 列表：GetNumPr
• 选项卡：GetTabs
• 间距：GetContextualSpacing

这些方法填补了长期以来的空白。您可以通过编程设置许多这些属性，但读取它们并不总是可行。您可以在不依赖于变通方法的情况下检查段落格式，这对文档分析工具和模板验证脚本特别有用。

内容控制颜色

文档 API 中的 ApiInlineLvlSdt 类支持 SetColor 和 GetColor 方法。您可以为内联内容控件分配和读取高亮颜色，从而更容易地构建视觉上独特的表单体验，或根据状态高亮控件。

// 如何更改文档中内联内容控件的颜色？

// 将特定RGB颜色应用于文档中的内容控件，以便视觉上区分。

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("这是一个带有蓝色标签的内联文本内容控件。");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);