用网页技术驱动WPS客户端：wps-js-demo 加载项开发从入门到实战

简介面向WPS插件开发者的Node.js示例程序核心目标是解决网页端调用并打开WPS进行文档操作的问题适合正在评估网页集成方案、准备编写插件或需要将WPS能力嵌入办公系统、在线文档平台、企业内容管理等场景的前后端开发者。压缩包共一百六十一个文件其中包含十八个JavaScript与六个TypeScript源文件、六个HTML页面以及十一个sample示例JSON与XML配置可用于参数调整CSS与SVG资源用于页面样式和图标展示Markdown和docx文档用于阅读说明和使用指引同时包内还保留了Git版本元数据方便查看项目演进记录。整体大小仅一点五二MB虽然体积紧凑但代码、配置、样式、文档几个维度都覆盖较全可帮助开发者理解WPS网页调用的具体流程、插件封装思路与部署注意事项省去从零搭建的麻烦示例与说明文档相互配合为二次开发或功能验证提供直观参照。目前已有1119人学习下载适合具备一定前端或Node.js基础、正在开展WPS插件调研或希望快速上手网页集成开发的开发者参考。1. wps-js-demo 是什么用网页技术驱动 WPS 客户端的那条最短路径一个常见需求给业务人员做 WPS 表格批量处理又不想全员培训 VBA。wps-js-demo 就是这条路的现成起点——用 JavaScript 写 WPS 插件的示例工程插件本质是个网页能通过 wpsjs SDK 反向调用 WPS 客户端打开文档、读写单元格、操作选区、控制放映。它解决的核心问题是“用网页技术驱动 WPS”。相比 wps vba 和 wps js宏加载项界面可以是任意 HTML/CSS/JS分发维护更接近 Web 应用相比 C 插件又不碰底层 COM 接口门槛低得多。适合给公司做内部自动化工具的前端以及想从 VBA 换技术栈的人。接下来按骨架 → 最小闭环 → API → 排错 → 交付展开每步都有可抄的代码和参数。2. 拆开 wps-js-demo 的骨架manifest、本地服务与 SDK 加载拿到这类仓库先别急着 npm install把它当一个“加载项工程”来拆。加载项和传统插件最本质的区别WPS 不直接加载你的 JS 文件而是加载一个网页地址之后所有交互都发生在这个网页里。所以整个 demo 只有三块——描述插件身份的 manifest 文件、托管页面的 Web 服务、调用 wpsjs SDK 的前端代码。这也是它和 wps js宏 的分水岭宏在编辑器内执行加载项是网页在反向驱动客户端。2.1 manifest 里的关键字段插件 ID、组件类型和页面地址manifest 是一个 XML部分新版 SDK 也接受 JSONWPS 启动加载项时第一件事就是读它。常见结构如下?xml version1.0 encodingUTF-8? PluginConfiguration AppInfo PluginIDcn.demo.wpsjs/PluginID Namewps-js-demo/Name Version1.0.0/Version Publisherinternal/Publisher /AppInfo JsApi Debugtrue/Debug /JsApi Apps App nameet Urlhttp://localhost:8080/index.html/Url /App /Apps /PluginConfiguration逻辑说明PluginID 是全局唯一标识WPS 靠它区分插件重复的话先导入的会被覆盖Name 是展示名JsApi 里的 Debug 控制 SDK 是否输出调试日志。Apps 里每个 App 声明插件在哪种组件中生效et 是表格wps 是文字wpp 是演示Url 指向插件首页。一个插件可以同时声明多个 App但同一个页面同时被 et 和 wps 打开时代码里必须先判断当前容器再选 API。参数说明Url 字段最容易出问题。localhost 可以工作但个别版本对 localhost 的 TLS 策略不一致我习惯在 hosts 里配一个本地域名比如 wps-dev.local 指向 127.0.0.1manifest 里写这个域名从根上避开“本地正常、换机器就 404”的玄学。另外注意标签名在不同 SDK 版本里可能有出入以 demo 仓库自带的 manifest 为基准修改不要凭空另写一份。导入 manifest 的常见路径打开 WPS进入「开发工具」选项卡点「加载项」选择「导入」后选中 manifest 文件。如果你找不到开发工具选项卡去 WPS 设置里把功能区勾上开发工具。导入成功的标志是加载项面板里出现你 Name 字段的值。2.2 wpsjs SDK 的加载顺序先于一切业务代码wpsjs SDK 本质是一层消息封装页面在 WPS 内置 WebView 里加载时宿主会注入一个消息通道SDK 负责把wps.et.Application()这类调用翻译成宿主认识的消息再把结果异步返回。所以加载顺序不是代码风格问题是能不能握手成功的问题!DOCTYPE html html head meta charsetutf-8 / titlewps-js-demo/title /head body !-- 先加载 SDK再加载业务脚本 -- script src./wpsjs/wpsjs.js/script script src./main.js/script /body /html逻辑说明wpsjs.js 必须声明在全部业务脚本之前因为页面初始化阶段就要完成消息通道握手。npm 方式的话把import wpsjs from wpsjs放在入口文件第一行本地静态文件方式保持上面的 script 顺序。凡是报 “wps is not defined” 的案例查到最后多半是 script 顺序写反、或加了 async/defer 导致时序被打乱。提示如果你看到 wps 对象但上面没有任何 et/wps/wpp 属性说明握手还没完成等页面完全加载后再调用。这个握手过程大概是页面加载时 SDK 先 postMessage 一条 ready 消息宿主收到后回一条 ack之后的每次调用都走“请求—回执”的消息对。你不需要理解协议细节但要知道这条通道是异步建立的所以不要在脚本执行阶段就调用 API只能在页面交互阶段调用。把初始化放到 DOMContentLoaded 之后是常见写法但最省心的还是后面章节说的“按钮触发”。SDK 就位后window 下挂全局对象 wps结构是wps.et表格、wps.wps文字、wps.wpp演示三组命名空间。如果你在 Chrome 里直接打开插件页面wps 对象也存在但调用会一直 pending——因为浏览器里没有宿主在回消息。这是加载项没法脱离 WPS 调试的根本原因后面排查章会专门展开。2.3 开发模式与正式模式同一个 demo 的两种部署姿态demo 默认是开发姿态Debugtrue、Url 指向 localhost、服务本地起。到了正式环境这三处都要变。配置项开发模式正式模式JsApi.DebugtruefalseApps.Urlhttp://localhost:8080https://你的内部域名服务端npm run dev静态资源服务器改的时候注意正式模式要求资源地址是可被所有用户访问的 https 地址WPS 对明文 http 的控制严格一些尤其是新版本。我一般维护两套 manifestdev/release或者用一个构建脚本在打包时替换 Url避免手工改错。Debug 日志在正式环境一定要关因为 SDK 日志会把文档名、单元格内容打出来内部工具也一样。验证部署是否成功我习惯在页面角落放一个版本号加载项面板里能看到这个版本号才算真的部署到位而不是依赖浏览器缓存。3. 跑通最小闭环本地起服务、插件装进 WPS、网页打开文档这一章只做一件事让你从拿到代码到在网页里点一个按钮把本地 Excel 打开整个过程三个节点——服务、导入、调用。任何一个节点断了后面的代码都白写。3.1 本地服务与导入网页搭建从两个命令开始cd wps-js-demo npm install npm run dev逻辑说明第一行进入工程目录第二行安装依赖npm install 会读取 package.json 把 wpsjs、构建工具等装到 node_modules第三行启动本地调试服务。端口以工程里 vite.config.js 或 package.json 里的配置为准默认一般是 8080。如果你不想用 Node 那一套纯静态版 demo 也可以用python -m http.server 8080顶替只要端口和 manifest 的 Url 一致就行。参数说明端口是这里的唯一硬约束。改了端口却忘了改 manifest 里的 UrlWPS 打开加载项时必然 404。起服务后先在普通浏览器里访问一次http://localhost:8080/index.html确认页面渲染正常再去做 WPS 侧导入——这一步能提前排除“服务没起来”这类低级问题。导入 manifest 后在 WPS 的「加载项」面板里点击你的插件名。此时 WPS 会新开一个 WebView 窗口加载 Url 指向的页面页面里右键一般能找到“检查元素”入口调试体验和浏览器开发者工具接近。3.2 网页里调用“打开文件”的最小代码新建一个 main.js内容就是下面这段// main.js —— 网页调用 WPS 打开文档的最小闭环 async function openDocument() { // 1. 获取表格宿主中的 Application 对象这一步是异步握手 const app await wps.et.Application(); // 2. 用绝对路径打开本地工作簿 const workbook await app.Workbooks.Open(D:/demo/data.xlsx); // 3. 读第一个工作表 A1 单元格验证真的打开了 const sheet workbook.Worksheets.Item(1); const value await sheet.Range(A1).Value2(); console.log(A1 , value); } document.getElementById(openBtn) .addEventListener(click, openDocument);逻辑说明这段代码做了三件事——获取 Application、打开工作簿、读 A1。wpsjs 的 API 几乎全部返回 Promise所以要么 await 要么 then漏掉 await 的典型表现是后续代码拿到一个 pending 对象再调方法就报错。注意我把调用挂在按钮事件里而不是页面加载时立即执行这是有意的宿主通道在页面刚加载时不一定就绪靠用户点击这个手势能避开大量时序问题。参数说明Workbooks.Open 的第一个参数是 WPS 所在机器的本地绝对路径注意 Windows 路径反斜杠在 JS 字符串里要写成D:\\demo\\data.xlsx或用正斜杠Range(A1) 是类 Excel 的引用写法等价于 Cells(1,1)。Value2() 返回原始值日期、数字都是底层存储形态想拿显示文本用 Text 属性但做数据搬运优先用 Value2。另外一个值得养成的验证动作在 WebView 控制台敲一下!!wps.et返回 true 说明宿主通道在返回 false 就回去查 manifest 和服务别在业务代码里翻。这个动作把“代码问题”和“环境问题”一刀切开。到这一步最小闭环已经通了网页按钮 → wpsjs → WPS 打开真实文件并回传数据。接下来的问题是“还有哪些操作可以调”也就是下一章的 et/wps/wpp 三件套。4. wpsjs 对象树实战et 表格读写、wps 文字替换与 wpp 演示放映wpsjs 把能力按组件分成三组命名空间wps.et表格、wps.wps文字、wps.wpp演示。对象树的结构基本对齐 VBA 的 Application → 文档 → 工作表/选区这条链所以写过 wps vba 的人不会陌生差别只在“每个操作都是异步的”。这一章把三件套里最高频的操作各给一段能抄的代码。4.1 表格 et读写单元格、批量搬数据与 html 表格转换// 表格组件读写单元格 批量取值 async function tableDemo() { const app await wps.et.Application(); const wb app.ActiveWorkbook; // 当前工作簿 const sheet wb.ActiveSheet; // 当前工作表 // 单个单元格写入 await sheet.Range(B2).Value2(2024-06-01); // 批量读取一块区域返回二维数组 const values await sheet.Range(A1:D4).Value2(); console.table(values); // 第一行就是 A1~D1 // 区域整体赋值数组维度要和区域大小一致 await sheet.Range(A10:C10).Value2([ [a, b, c] ]); }逻辑说明先拿 Application 再顺着 ActiveWorkbook / ActiveSheet 往下走每个属性拿到的都是 Promise 或需要 await 的对象所以一连串取值时及时 await 是关键。批量读取是表格场景里最重要的接口——网页抓到的数据、接口返回的 JSON最终都要通过“二维数组 ↔ Range”的映射落到表格里这比一格一格写快一个数量级。参数说明Value2 写日期时传 Date 对象或可解析的字符串WPS 会按单元格格式存储读到的二维数组从 (行, 列) 索引values[0][1] 对应 A1 右边那格。区域赋值要求数组的行列数和区域完全一致多一行少一行都会报错所以我先 console.table 打印出来核对维度再写入。这个“先打印、后写入”的习惯能省掉大量调维度的血泪时间。如果你要做“html 格式转换 WPS 表格”这类需求思路同样是抓取 → 清洗成二维数组 → 一次写入注意 html 里的合并单元格要先展开否则行列数对不上。4.2 文字 wps 与演示 wpp选区替换、放映与宿主判断// 文字组件替换当前选区内容 async function wordDemo() { const app await wps.wps.Application(); const doc app.ActiveDocument; const sel doc.Selection; // 当前选区 await sel.Text(替换后的内容); // 直接改文字 }// 演示组件从当前页开始放映 async function wppDemo() { const app await wps.wpp.Application(); const ppt app.ActivePresentation; await ppt.SlideShowSettings.Run(); // 全屏放映 }逻辑说明文字组件的核心是 Selection——用户选了什么你就能改什么。典型用法是网页里选模板 → 替换选中文字 → 保存适用于合同、通知这类批量生成场景。演示组件的核心是 Presentation 对象放映之外编辑单页Slide内容、按页导出也是高频操作。参数说明Selection.Text 赋值会替换整个选区想追加内容就先取原文本再拼接SlideShowSettings.Run() 是异步的调用后画面切到放映你的网页会暂时不可见涉及放映的流程要先确认用户后面不需要再操作网页。还需要提一个常见需求判断当前页面到底跑在哪个组件里。同一个 Url 可能同时登记到 et、wps、wpp 三个 App 下运行时就要做判断。有的 SDK 版本提供环境标识字段优先用它没有的话用下面的兜底判断// 判断当前宿主组件 if (wps.et) { // 表格分支 } else if (wps.wps) { // 文字分支 } else if (wps.wpp) { // 演示分支 }这段判断放在所有业务调用之前避免拿表格的 API 去操作文档对象。对象不存在时 wpsjs 给的回执是“对象无此成员”一类很笼统的错误不容易定位提前分流能省不少事。5. 网页调用 WPS 的高频报错与排查五个案例加载项开发一大半时间花在排错上而且报错信息往往笼统。下面五条是我见过最典型的按“现象 → 原因 → 解决”写对照着查比自己翻文档快。5.1 控制台报 “wps is not defined”现象WebView 控制台直接抛 Uncaught ReferenceError: wps is not defined业务代码一行都执行不了。原因SDK 没加载或加载时机晚于业务代码。最常见是 script 顺序写反或者打包时把 wpsjs 设成了 external 却没有在 HTML 里手工引入。解决把所有引用 wpsjs 的 script 挪到业务脚本之前去掉 async/defer 属性用 npm 的话改成在入口第一行 import。改完重新打开加载项。5.2 wps.et.Application() 的 Promise 一直 pending现象不报错但 await 永远不返回页面像卡死控制台没有任何输出。原因页面不在 WPS 宿主环境里。两类典型一是你直接在 Chrome 里打开了插件 URL浏览器里没有宿主回消息二是 manifest 里 Url 和实际服务不一致WebView 加载的是一份代码你调试的是另一份根本不在同一条通道上。解决确认页面只能从 WPS 加载项入口打开核对 manifest Url 与服务的端口、路径完全一致。另外页面刚加载完的 1~2 秒内调用也可能 pending所以我把首个调用挂在按钮点击上用用户手势兜底。提示如果怎么都确认不了页面是否在宿主里把 Debug 打开宿主会在控制台打印一条 ready 日志。5.3 浏览器里正常、装进 WPS 就翻车现象Chrome 里样式、交互都对导入 WPS 后布局错乱、按钮没反应或脚本报语法错误。原因WPS WebView 的内核版本通常落后于浏览器新语法可选链、展开符和部分 CSS 特性不支持同时 WebView 的安全策略与浏览器不完全一致localStorage、跨域限制都有差异。解决构建配置把编译目标调低到 ES2018 级别并在真机 WPS 里验证不要只依赖浏览器。核心状态优先放在内存变量别押在 localStorage真有持久化需求先做特性检测再决定分支。5.4 manifest 改了不生效现象改完 manifest 里的 Url 或 VersionWPS 里加载的还是旧页面旧版本号。原因WPS 对加载项有缓存同一 PluginID 重复导入时新配置不一定立即生效WebView 的页面缓存比 manifest 缓存更顽固。解决改完 manifest 后彻底退出 WPS含系统托盘图标重新打开再导入。页面更新类问题先确认服务端文件真的变了浏览器访问一次再在 WebView 里强制刷新或重启加载项。如果都不行换个 PluginID 重来最省时间。5.5 网页读不到本地文件路径现象用户在网页里填了一个D:/xxx/数据.xlsxWorkbooks.Open 报文件不存在或者 WebView 里拿到的路径和真实路径对不上。原因网页是沙箱拿不到文件系统真实句柄即便路径写对WPS 进程权限低于文件所在目录比如管理员目录下的文件时也会打不开。这是加载项的边界它能驱动 WPS但不会变成桌面应用。解决优先让用户通过 WPS 宿主的文件选择对话框拿路径而不是自己填字符串文件必须放在当前用户可读的目录。跨文件调用也一样两个工作簿之间取数先各自通过宿主打开拿到 Workbook 对象再在代码里引用对方单元格不要尝试拼接路径去猜文件。6. 从 demo 到正式插件交付前还差这三件事第一件给所有 wpsjs 调用包一层超时和错误处理。宿主通道一旦异常Promise 可能永远悬挂用户看到的就是“按钮点了没反应”。我一般封装一个 callWpsfunction callWps(task) { return new Promise((resolve, reject) { const timer setTimeout( () reject(new Error(wps call timeout)), 5000 ); Promise.resolve(task()) .then(v { clearTimeout(timer); resolve(v); }) .catch(e { clearTimeout(timer); reject(e); }); }); }用法await callWps(() wps.et.Application())。超时时间按操作复杂度调简单读值 3 秒足够打开大文件可以放宽到 10 秒。第二件权限和日志收敛。正式环境关 Debug、走 https、不打印文档内容。wpsjs 的异步报错很容易被吞掉建议在最外层统一 catch 并把错误信息上报。版本号跟着 manifest 走每次发布递增用户侧的版本问题靠它定位。第三件把常用的“打开 → 取数 → 写回 → 保存”封装成业务函数不要散落在按钮事件里。这样后续接“网页抓取数据写表格”“html 格式转换 WPS 表格”这类需求只是换数据源不换框架。我自己第一次接这类项目时就是没做超时封装用户反馈“多点几次就卡死”最后定位是某次调用 Promise 永不 resolve。所以现在凡是调 wpsjs一律先过 callWps 再进业务逻辑这个习惯救了我很多次。希望帮到你。本文还有配套的精品资源点击获取