ONLYOFFICE插件三端复用：config.json配置让Word、Excel、PPT同时支持

最近在做企业内部在线文档改造时，接了一个“插件同时支持Word、Excel、PPT”的需求。说实话，ONLYOFFICE插件本身并不天然具备三端复用能力，它需要通过配置文件里的variations区段，明确告诉编辑器“我这个插件要进哪些文档类型”。很多同事卡在“明明照着示例写了，插件只在Word里出现，Excel和PPT的工具栏上就是找不到”。这篇文章我会把整套配置思路、配置代码和排错方式完整串一遍，适合正在做ONLYOFFICE插件集成、想让一套业务工具在文字编辑、表格编辑、演示文稿编辑三端统一露出的开发同学参考。

核心答案并不复杂：一份config.json，加上插件代码里对editorType的分支判断，就可以让同一个插件的入口同时出现在Word、Excel、PPT三端工具栏中。难点主要在于理解加载顺序、不同编辑器的API边界，以及联调时可能遇到的缓存和路径问题。我会从需求场景讲起，逐步拆到具体字段，再给一个可以直接套用的配置模板。

1. 这个需求到底要解决什么问题

1.1 业务背景和使用场景

先说我遇到的实际场景：公司内部用ONLYOFFICE做了一套在线文档预览编辑平台，Word、Excel、PPT三类文件都挂在一个统一入口下。产品要做一个内部业务工具插件，功能是快速从当前文档中提取选中内容、按模板批量插入批注，并且希望这个工具在三种文档里都能用。如果用户正在编辑一个销售报表（Excel），他需要这个工具；正在写方案（Word）也需要；正在做汇报PPT，还需要。所以这不是一个“锦上添花”的诉求，而是业务闭环里绕不开的一个基础能力。

这类需求在企业内部其实很常见，不只是做提取批注，还包括：

• 翻译助手：选中文本后调用内部翻译接口，把结果回填到文档、单元格或文本框；
• 合规检查：读取当前文档全文、当前工作表内容、当前幻灯片文本，检查敏感词并高亮；
• 模板填充：把固定的合同模板、报表模板插入到当前编辑状态里；
• 格式清洗：统一字体、字号、颜色、页面边距，或清除多余空格。

如果插件像常见的教程演示那样只配置了word类型，那么用户在表格编辑器和演示文稿编辑器的“插件”标签页里根本看不到这个插件，业务逻辑写得再好也无效。所以第一步不是写功能，而是先把“能出现在哪里”这件事通过配置固化下来。

1.2 如果只配置单文档类型会有什么后果

很多初次接触ONLYOFFICE插件的人，会习惯性把官方示例里的config.json直接复制过来，改个名字和按钮文字就完事。官方那个最简单的示例通常只声明了word编辑器，不包含cell和slide。演示场景下没什么问题，一旦挂到生产环境，问题立刻暴露：

• 用户从Word切到Excel，发现插件入口消失了，只能去“插件管理器”重新安装一遍才能加载；
• 如果三个编辑器部署在两台不同服务器上，你还得各自维护一套插件包，版本更新要同步三次；
• 插件内部如果有公共配置项，也会因为入口不统一，出现“Word里改了配置，Excel里还是旧版”的割裂状态。

说白了，这个问题本质是“插件启动清单”不完整。启动清单就是config.json里的variations字段，它决定了插件在哪些编辑器类型下被加载、显示。只要把三端类型都声明进去，问题就解决一大半。

1.3 解决问题的两条主线

我把整个解决思路拆成了两条线。第一是静态声明：在config.json里把插件支持的编辑器类型全部列出，让ONLYOFFICE在启动文档编辑器时就把插件加载进来。第二是运行态判断：插件代码在初始化时通过当前编辑器的类型标识，走不同的业务分支，因为Word、Excel、PPT的API对象和工作方式差异很大，不可能用同一套方法处理选中内容。两条线缺一不可，只有声明了类型却不在代码里做区分，插件虽然三个地方都能打开，但功能调用会互相冲突。

2. 插件加载机制与config.json的核心作用

2.1 插件的运行原理

ONLYOFFICE插件本质上是一个web应用，通常包含一个HTML页面作为界面层，一个或多个JavaScript脚本作为业务逻辑，再配一个config.json作为声明文件。编辑器启动后，会读取config.json，按照里面的信息决定是否加载这个插件、何时显示按钮、点击后打开哪个页面。

插件目录典型结构是这样的：

my-plugin/ ├── config.json ├── index.html ├── js/ │ ├── core.js │ ├── word.js │ ├── cell.js │ └── slide.js ├── css/ │ └── style.css └── assets/ └── logo.png

config.json里最关键的就是variations字段。这个字段是一个数组，数组里每个对象对应一种编辑器类型。ONLYOFFICE把文档编辑器类型划分为：word代表文字处理、cell代表电子表格、slide代表演示文稿。实际配置时，你想让插件在哪个编辑器环境出现，就往variations里加对应name的配置。注意，这里的name值是固定的小写字符串，不能写成Word、Excel、PPT，也不能用中文“文档”“表格”“幻灯片”。这是我见到最常见的低级错误之一。

2.2 config.json字段说明

一个相对完整的config.json主要包含这些字段：

关于这些字段，有两个容易被忽略的点。一个是guid，我之前图省事直接复制了示例代码里的guid，结果在多个测试文档之间出现“同一个插件加载多次”的奇怪现象，换了新的UUID后问题立刻消失。另一个是baseUrl，如果路径写错或者写成相对路径，编辑器加载不到index.html，插件列表里能看到名字，但一点开就是一片空白。

2.3 variations数组的工作方式

variations数组是插件能否三端共用的关键。ONLYOFFICE启动某个编辑器时，会遍历数组，找到name匹配当前编辑器类型的项，然后根据这一项里的url、scripts、buttons等信息完成插件挂载。换句话说，同一个插件在Word里可能走word.js，在Excel里走cell.js，在PPT里走slide.js，三种环境分别加载自己需要的脚本，互不干扰。

如果你想所有文档类型都完全共用同一套逻辑，也可以给三项配置完全相同的脚本和界面入口。但从工程角度来看，我并不推荐这么做，因为不同编辑器的交互对象差异明显，至少要在代码里保留一个分发的入口，否则后面扩展功能会很难受。

3. 同时支持Word、Excel、PPT的具体配置写法

3.1 可直接套用的config.json

我把自己在项目里验证可用的配置摘出来，去掉业务相关部分，保留最核心的结构。

{ "name": "三端业务工具", "guid": "asc.{D9F7B0A1-2C34-4E5F-9A6B-8C0D1E2F3A4B}", "baseUrl": "https://your-static-server.example.com/onlyoffice-plugins/tools/", "variations": [ { "name": "word", "url": "index.html", "size": [760, 500], "buttons": [ { "text": "打开工具", "command": "openToolPanel" } ], "scripts": [ "js/core.js", "js/word.js" ], "isDisplayedInEditor": true, "isDisplayedInViewer": false, "hasSettings": false }, { "name": "cell", "url": "index.html", "size": [760, 500], "buttons": [ { "text": "打开工具", "command": "openToolPanel" } ], "scripts": [ "js/core.js", "js/cell.js" ], "isDisplayedInEditor": true, "isDisplayedInViewer": false, "hasSettings": false }, { "name": "slide", "url": "index.html", "size": [760, 500], "buttons": [ { "text": "打开工具", "command": "openToolPanel" } ], "scripts": [ "js/core.js", "js/slide.js" ], "isDisplayedInEditor": true, "isDisplayedInViewer": false, "hasSettings": false } ] }

这段配置的核心逻辑是：三个编辑器类型各自配置了一份variation，但界面统一用index.html，这样用户点开插件后看到的是同一个工具面板；入口脚本略有区分，Word加载word.js，Excel加载cell.js，PPT加载slide.js，它们负责各自环境下的初始化动作。公共能力放在core.js里，三端共用。

3.2 字段选择背后的理由

你可能注意到每个variation里都写了isDisplayedInEditor和isDisplayedInViewer。这是有意为之。如果只配编辑器可见而不配查看器可见，那么用户在预览模式下不会看到插件入口，可以避免普通查看者误点插件造成不必要的调用。size字段控制插件面板宽度和高度，我按业务场景设到760x500，太小的画布放表单会挤，太大又遮挡文档内容。

另外我发现，不少例子会把buttons放在variations外层，这样三个编辑器会共用同一批按钮定义。如果三端按钮行为完全一致，放在外层确实更简洁。但在我这次的业务里，Word、Excel、PPT虽然都叫“打开工具”，实际点击后的面板内容需要按文档类型动态变化，所以我把按钮放在每个variation内部，让配置更贴近实际使用方式。这个没有绝对标准，取决于你的插件是否要为不同文档类型展示不同控件。

3.3 用共享页面适配三端显示

除了按钮，界面入口共用index.html也是一个需要留意的设计点。既然三端共用同一个HTML，那这个页面必须在初始化时知道自己当前跑在什么环境里。ONLYOFFICE插件运行时提供了当前编辑器信息，可以在代码里直接读取。我通常在index.html加载完成后，立刻拿到当前编辑器类型，再决定渲染哪些控件、发起哪些API调用。

window.Asc.plugin.init = function () { const editorType = this.info.editorType; // editorType 的值分别是 "word"、"cell"、"slide" if (editorType === "word") { initWordPanel(); } else if (editorType === "cell") { initCellPanel(); } else if (editorType === "slide") { initSlidePanel(); } else { console.warn("未知的编辑器类型：", editorType); } };

这样一来，业务界面和逻辑都能最大化复用。config.json负责让插件在三个环境下都能被加载，运行时的editorType分支负责让同一套界面正确响应不同编辑器的能力差异。

4. 按编辑器类型划分插件业务逻辑

4.1 Word、Excel、PPT的API调用差异

配置做完只是第一步，后面写插件功能时最大的分水岭是API调用。ONLYOFFICE三类编辑器共用同一套插件框架，但具体操作对象和可用方法差异很大。简单说：

• Word环境里，你操作的是文档、段落、书签、选区文本、表格等对象；
• Excel环境里，你操作的是工作表、单元格区域、公式、数据透视表等对象；
• PPT环境里，你操作的是幻灯片、形状、文本框、图片、动画等对象。

如果你在Word环境里调用获取单元格区域的API，大概率会报错或者返回空对象。这个不是ONLYOFFICE设计奇怪，而是文档模型本身就不一样，就好像你不能在Word表格里用Excel单元格坐标一样。所以插件代码里必须把“当前编辑器类型”当作一个一等公民来处理，所有和具体文档对象打交道的逻辑都放到对应的分支里。

4.2 分支处理的参考代码

业务逻辑的骨架我一般这样写。以“从当前选中内容中提取文本并回填一个提示框”为例。

function extractCurrentContent() { let actionName = ""; switch (currentEditorType) { case "word": actionName = "GetSelectedText"; break; case "cell": actionName = "GetSelectedText"; break; case "slide": actionName = "GetSelectedShapeText"; break; default: break; } if (!actionName) { console.error("当前编辑器不支持该操作"); return; } window.Asc.plugin.executeMethod(actionName, [], function (result) { document.getElementById("resultBox").innerText = result || "无选中内容"; }); }

这里只是举例，实际项目中API方法名要以你所接入的ONLYOFFICE版本官方文档为准，不同版本可能存在细微差异。但代码分层的思路是通用的：公共逻辑放在外面，把唯一的差异点收敛到actionName这类变量上，不要在每个功能里都写一大段if/else。功能多了以后，这种写法最好维护。

4.3 公共层与差异层分离的设计

三个编辑器之间其实有相当一部分能力是重合的，比如“读取选中文本”“向当前光标位置插入内容”“弹出对话框提示”。这些公共能力我可以抽到core.js里，由内部根据editorType自动选择实现。而每个编辑器独有的一些操作，比如Word的批注、Excel的区域计算、PPT的形状选中，则在word.js、cell.js、slide.js里各自实现。这样改Word功能不会影响Excel，改Excel也不会波及PPT。

我最开始做的时候没有把公共逻辑抽出来，直接在各自入口脚本里复制了相似代码。结果后来发现“读取选中文本”这个功能需要加一个去空格逻辑，我连续改了word.js、cell.js、slide.js三份文件，改完又担心漏了一个，体验非常差。后来把公共逻辑收拢到core.js，一份修改，三端生效。

5. 本地联调与部署经验

5.1 插件部署的三种常见方式

ONLYOFFICE插件可以集成在独立安装的Document Server里，也可以嵌入到你的业务系统前端页面中。部署方式会直接影响baseUrl配置，这块如果不搞清楚，插件很容易在本地好好的、一上测试环境就加载不出来。

我实际用过的三种方式：

• 本地静态服务器：适合开发阶段，用HTTP服务托管整个插件目录，baseUrl写本地地址，比如http://localhost:8080/plugins/tools/。打开ONLYOFFICE编辑页前先跑起这个本地服务。
• 对象存储或CDN：适合生产环境，把插件整个目录上传到对象存储，baseUrl填写对应的访问域名。注意要允许跨域访问，否则插件脚本可能被浏览器拦下。
• Document Server插件目录：把插件目录放到Document Server服务器的指定插件目录下，配置好后由Document Server自己加载。这种方式适合不想单独维护静态服务的场景。

方式一最方便调试，因为改动代码后浏览器刷新就能看到最新效果。方式二最符合企业内部分发场景，因为多个Document Server节点可以共用一份插件包。方式三适合插件包不大、不想额外引入存储依赖的环境。

5.2 联调时最容易翻车的几个点

联调过程中，我列几个自己踩过的坑，按出现频率排：

• 改了config.json但编辑器内不生效。这不是ONLYOFFICE没读文件，而是浏览器缓存了旧版本。插件页面本质是网页，config.json也会走HTTP缓存，修改后最好强制刷新或给静态服务加禁用缓存头。
• baseUrl末尾少写斜杠。很多资源拼接会把baseUrl作为前缀，如果你写成https://your-server.com/onlyoffice-plugins/tools，而系统拼接成tools + "/index.html"，就会得到toolsindex.html这种路径。统一在目录后加斜杠最省心。
• 插件只显示在编辑模式，查看器里不显示。这是isDisplayedInViewer配置为false造成的，如果你的业务要求预览时也能用插件，把它改成true。但这个要看需求，普通预览场景下我并不建议开着，避免无谓的接口调用。
• 跨域问题。插件调试时，编辑器页面和插件静态服务如果不在同一个域名下，浏览器的安全策略可能会拦截脚本。开发阶段临时关掉安全校验可以跑通，但正经联调要配好跨域白名单。

5.3 给联调配置一个快速验证环境

为了提高联调效率，我给团队配了一个极简的本地换代方案。在插件根目录里放了一份专门用于调试的demo.html，页面里直接列出三个按钮，分别代表Word、Excel、PPT环境，点击后模拟触发当前编辑器的初始化事件。这样不用每次都在ONLYOFFICE编辑器里切来切去，单页就能验证公共逻辑是否正确。真正和编辑器API相关的部分再回到编辑器里验证。

这个页面本身很简单，本质是模拟一个plugin init上下文，把editorType作为假值传进去。

<!-- demo.html 用于快速验证三端分支是否正常 --> <button>