如何创建 ONLYOFFICE 插件：实用技巧、进阶窍门与避坑指南

为 ONLYOFFICE 编辑器构建插件可能看似简单，但在实际开发中，往往会遇到意想不到的挑战，从性能瓶颈、网络问题到网页版与桌面版环境间的细微差异。本文将介绍一些实用技巧、进阶窍门与避坑指南，帮您创建能够跨编辑器和部署场景稳定运行的可靠插件。

消息桥与工作流

插件的 UI 界面运行在独立窗口中，通过消息桥与编辑器进行通信。该消息桥更适合传输少量数据和执行精准的编辑操作。将 UI 相关操作（如数据获取、列表筛选）与文档修改操作（如文本插入）分离处理，能显著提升运行速度、简化调试流程，并在多人协同编辑场景下保证效果可预期。

保持文档编辑操作简洁聚焦

原因：编辑器命令会一次性执行，将相关修改分组处理可避免界面闪烁，同时确保文档状态一致。

示例（文档编辑器：插入引用文献）：

// UI side: prepare compact data
const citation = `${title} - ${source}${date ?  ', ' + date : ''}`;
Asc.scope.citation = citation;

// Editor side: run atomically
window.Asc.plugin.callCommand(function () {
  var doc = Api.GetDocument();
  var p = Api.CreateParagraph();
  p.AddText(Asc.scope.citation);
  doc.InsertContent([p]);
}, true);

小贴士：​ 在集成到插件之前，先在 Playground 中测试编辑器 API 调用，以验证语法和行为。

避免在编辑器命令内部获取数据

原因：​ 在命令内部等待网络请求会使编辑器冻结。

示例（反例 vs. 正确做法）：

    // Anti-pattern: async in callCommand (don't do this)
window.Asc.plugin.callCommand(async function () {
  const res = await fetch(url);
  const text = await res.text();
  Api.GetDocument().InsertContent([Api.CreateParagraph().AddText(text)]);
}, true);

// Correct: fetch in the plugin window, then pass small data
const res = await fetch(url);
const text = await res.text().then(t => t.slice(0, 200)); // trim
Asc.scope.snippet = text;
window.Asc.plugin.callCommand(function () {
  var p = Api.CreateParagraph();
  p.AddText(Asc.scope.snippet);
  Api.GetDocument().InsertContent([p]);
}, true);

仅通过消息桥传输少量数据

原因：消息桥针对类 JSON 格式的轻量数据优化，大型字符串或嵌套对象会显著增加延迟。

分离 UI 操作与文档操作

原因：数据获取、解析、筛选等操作应在插件窗口中完成，仅将最终需要插入的内容通过编辑器命令执行。

安全与网络处理

插件常需从 RSS 订阅、API 等外部来源获取内容，若缺乏必要校验，可能导致恶意代码注入、跨域请求被拦截，或因 HTTP/HTTPS 混用引发隐性故障。一套简单有效的安全与网络处理方案能避免这些问题。

进阶窍门（含示例）

在显示前先清理不可信的 HTML

原因：订阅摘要或代码片段可能包含恶意 HTML，不仅会破坏插件 UI，还可能带来安全风险。

示例：

// Quick plain-text extraction
function toPlainText(html) {
  const tmp = document.createElement("div");
  tmp.innerHTML = html;
  return tmp. textContent || "";
}
const safeText = toPlainText(untrustedHtml);

// If rendering controlled HTML, use a sanitizer (e. g., DOMPurify)
// const safeHtml = DOMPurify.sanitize(untrustedHtml);
// container.innerHTML = safeHtml;

优先向文档插入纯文本

原因：纯文本可避免意外格式延续，同时减小消息桥的传输负载；而富格式则应保留用于有明确目的的、编辑器端的 API 使用场景。

采用 HTTPS 并避免混合内容

原因：在安全上下文环境中，浏览器会阻止 HTTP 资源；当端点不是 HTTPS 时，无声失败的情况很常见。

用简单代理处理跨域请求

原因：许多端点不允许直接的跨域访问；通过小型代理服务器可以添加跨域资源共享（CORS）头信息并规范输出。

示例（Node/Express 简易代码）：

 // Minimal CORS/normalize proxy (server-side)
import express from "express";
import fetch from "node-fetch";

const app = express();
app.get("/feed", async (req, res) => {
  try {
    const url = new URL(req.query.src);
    const r = await fetch(url.toString(), { timeout: 8000 });
    const text = await r.text();
    // Convert to normalized JSON shape server-side as needed
    res.set("Access-Control-Allow-Origin", "*");
    res.json({ items: normalizeToCommonShape(text) });
  } catch (e) {
    res.set("Access-Control-Allow-Origin", "*");
    res.status(502).json({ error: "Upstream fetch failed" });
  }
});

app.listen(3000);

性能优化、打包与发布前准备

插件需在用户编辑文档时实时运行，响应速度至关重要。良好的性能习惯、简洁的打包方式和发布前的全面测试，能让插件保持流畅、稳定，且便于后续更新。

性能优化需养成持续习惯：对搜索和筛选功能做防抖处理、实现长列表虚拟化、预计算待插入的精确字符串以降低单次操作成本。插件关闭时，需清理定时器、中止未完成的请求、移除可删除监听器，避免跨会话累积的缓慢资源泄漏。

const controller = new AbortController();
const timer = setInterval(refresh, 300000);

window.Asc.plugin.button = function () {
  controller.abort();
  clearInterval(timer);
  window.Asc.plugin.executeCommand("close", "");
};

核心技巧

1. 本地打包 JavaScript 和 CSS 文件，避免依赖外部 CDN；
2. 自定义深浅色系主题，而不是假定编辑器会提供这些方案；
3. 保持插件标识符（GUID）跨版本稳定，确保更新顺利；
4. 使用清晰的版本号（如 1.0.0、1.1.0、2.0.0），明确标识更新内容；
5. 包含插件管理器和应用市场所需的全部图标及元数据；
6. 使用类似生产环境 URL 进行测试，排查图片或脚本路径错误。

在发布之前，需要对支持的编辑器（文档、电子表格、演示文稿）、环境（网页版和桌面版）、主题（浅色和深色）、协作（同时插入）、网络条件（离线、慢速、代理宕机）、数据集大小（极小和非常大）以及采用更严格 CSP（无内联脚本或样式）的情况，进行一次精简而严格的测试。这样，当真实用户和真实网络对插件进行测试时，其行为才能保持一致。

总结

优质的插件源于一套简洁实用的开发习惯：先准备数据，集中一步完成文档修改，清理外部内容，通过小型代理路由网络请求，并将所有资源本地打包 —— 这样才能确保插件在各类环境中表现一致。发布前务必在不同的编辑器类型、运行环境、主题模式和网络条件下进行测试，让插件在真实使用场景中稳定可靠。