ONLYOFFICE 插件调试：实用指南

ONLYOFFICE 插件的开发与调试工作可能存在一定难度，但只要掌握合适的工具与技巧，整个过程就会变得轻松许多。本指南将逐步介绍在不同环境中高效调试插件所需的具体方法。

关于 ONLYOFFICE 插件

ONLYOFFICE 支持通过插件扩展编辑器功能。插件本质上是嵌入编辑器中的 HTML 页面，并通过 API 与编辑器进行交互。理解插件的基本结构与调试方式，是成功进行插件开发的关键。

插件结构

一个典型的 ONLYOFFICE 插件通常包含以下文件：

• config.json：定义插件基本信息的配置文件
• index.html：插件的主页面文件
• scripts：存放插件功能所需 JavaScript 文件的目录

关于详细结构和具体示例，可参考此处文档。

在网页编辑器中调试插件

若要在 ONLYOFFICE 在线编辑器中调试插件，请按以下步骤操作：

• 在您的脚本中添加 debugger 命令

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• 按下 F12 键在浏览器中打开开发者控制台
• 在 ONLYOFFICE 编辑器中，转到插件选项卡并运行您的插件

注意：debugger 命令仅在开发者工具开启时才会生效；否则将被忽略。您可在此页面了解更多相关信息。

在桌面编辑器中调试插件

若要在 ONLYOFFICE 编辑器桌面版本中进行调试，请采用以下方法：

• 使用 –ascdesktop-support-debug-info 参数启动编辑器

• 此参数将显示对调试有帮助的附加信息
• 与网页编辑器类似，在代码中需要中断的位置插入 debugger; 语句

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• 按下 F1 键打开控制台，随后运行插件。

在使用指定参数启动编辑器后，即可打开插件并跟踪代码执行过程。

有关不同操作系统的详细说明，请参阅此处文档。

管理作用域

开发 ONLYOFFICE 插件时，关键在于掌握如何在插件的用户界面（HTML 页面）与执行文档编辑器 API 的运行环境之间进行数据传递。这两者分别处于不同的上下文环境中，即不同的作用域。

常见错误通常源于未能正确处理不同作用域间的数据交互。为简化这一过程，ONLYOFFICE 提供了 Asc.scope 对象：您可以在插件的主脚本中将变量附加到 Asc.scope 上，这样在传递给 this.callCommand() 的函数中即可直接访问这些变量。

以下示例演示了如何将文本变量传递给插件及编辑器：

(function (window, undefined) {
    window.Asc.plugin.init = function () {
    // In your main script (e.g., scripts/plugin.js)
    let text = "Hello from the plugin!";
    Asc.scope.dataForEditor = text; // Export variable to the shared plugin scope
    // In the command executed in the editor's scope
    this.callCommand(function () {
         debugger;
         let oDocument = Api.GetDocument();
         let Paragraph = Api.CreateParagraph();
         oParagraph.AddText(Asc.scope.dataForEditor);// Access the variable via Asc.scope
         oDocument.InsertContent([oParagraph]);
    }, true);
  };
})(window, undefined);

正确使用 Asc.scope 能确保数据在不同上下文间准确传递，这对构建复杂插件至关重要。

常见问题及故障排除

调试过程中，您可能会遇到一些常见问题。以下列出了一些最常见问题及其解决方法：

调试器语句不起作用

debugger; 语句被忽略，程序无法暂停执行。

• 运行插件前，请确保已打开浏览器的开发者工具（按 F12 键）。
• debugger; 语句仅在开发者工具开启时生效。

插件无法加载或不可见

• 检查 config.json 文件格式是否正确（是否为有效的 JSON）。
• 确认 config.json 中包含所有必填字段（name、guid、baseUrl）。
• 检查浏览器控制台是否有任何加载错误。
• 确保插件已在 ONLYOFFICE 插件选项卡中正确安装。
• 使用压缩的 .plugin 文件或 Asc.editor.installDeveloperPlugin() 方法手动安装。

跨域资源共享 (CORS) 错误

• 安装 ONLYOFFICE 文档
• 对于 ONLYOFFICE 文档中的网页编辑器，请确保在插件文件夹内运行 http-server
• 或在 installDeveloperPlugin() 函数中调整 config.json 文件的路径

Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")

文件已更改，旧代码仍在运行 – 网页编辑器

• 如果您更改了插件的本地文件，则需要刷新页面并清除缓存。
• 右键单击​​浏览器的刷新按钮，选择“清空缓存并强制刷新”，然后再次运行插件。

高效的调试对于开发稳定且功能完善的 ONLYOFFICE 插件至关重要。通过使用上述技巧和工具，您可以快速识别并解决代码中的问题，从而提升插件的质量和性能。

我们欢迎您的提问、建议和插件创意。如果您想与我们分享您的作品，请随时联系我们。我们乐于合作，并期待与您交流。