简介面向WPS插件开发者的Node.js示例程序包适合需要在网页端调用并操作WPS文档的前端及Node.js工程师。压缩包内共161个文件以JavaScript和TypeScript源码为主配合HTML示例页面、SVG图标、JSON配置、Markdown说明、Docx样例、CSS样式及字体文件基本覆盖插件调用逻辑、页面入口、资源配置、界面样式和说明文档等模块包中保留的Git仓库元数据还有助于查看项目提交与演进脉络。整个压缩包仅1.52MB体量轻巧目录结构清晰便于快速定位关键代码并直接改造。目前已有1114人学习下载尤其适合刚接触WPS二次开发、希望借助可运行示例理解网页唤起WPS、打开文档并执行操作的完整链路的开发者可作为正式插件项目的脚手架参考。 很久前有朋友找我说公司内部OA系统要升级业务提了一个需求能不能在网页里直接打开WPS文档打开之后还能把文档内容读出来甚至回填到表单里 当时第一反应是这需求听着挺折腾网页和本地Office套件之间隔着一层浏览器安全沙箱常规做法要么是下载模板让用户本地编辑再上传要么是套一个大而全的在线文档服务。后来我在研究WPS官方开放能力时碰到过 wps-js-demo 这类项目才把整条链路彻底跑通。今天这篇文章就围绕网页调用WPS这件事完整拆解JS插件模式的原理、Demo工程的搭建、核心API的使用方法以及我在实际集成过程中踩过的坑。这套方案的适用人群很明确企业内部的OA、ERP、项目管理系统的开发者需要在网页端唤起WPS、打开指定文档、操作文档内容但又不想把整个业务系统搬进某个云端文档平台。只要你能写JavaScript哪怕不太熟Office对象模型也能在两三天内把一个能用的Demo跑起来。1. 网页操作WPS的机制先弄清楚它和浏览器插件的区别1.1 需求场景网页里打开WPS不只是打开而已早期大家做网页文档功能普遍是这么干的后端把文档转成PDF或者图片用户在线看真要编辑就下载到本地改完再传回来。这套流程能用但有很明显的问题来回传输文件导致版本容易乱而且用户根本不想离开网页去开一个桌面软件。后来有了WPS的开放平台提供了网页唤起本地的能力。但这里有个核心认知要纠正网页不能直接通过JavaScript去操作一个本地的WPS软件。浏览器出于安全考虑禁止网页访问本地进程。而wps-js-demo这种项目之所以能实现是因为它走的是本地WebSocket服务 页面通信的桥接机制相当于WPS在本地起了个小型服务网页和这个服务通信由服务再去指挥WPS干这干那。1.2 三类网页调用WPS的技术路线对比现实世界里网页调用WPS这个需求有三条常见实现路线我做了个对比表方便你根据不同场景选型技术路线实现方式适合场景局限URL协议唤起wps://网页通过链接或window.location跳转WPS协议打开本地文档简单打开场景无法一键执行读取内容、回写等复杂操作WPS网页JS-SDK在线服务引入SDK在前端页面显示文档所有处理都在浏览器内纯网页端预览/编辑不依赖本地软件需要接入WPS在线服务涉及文档存储与权限体系WPS JS插件本地桥接本地安装WPS客户端插件框架提供WebSocket服务网页通过API调用本地WPS企业内部系统希望在网页与本地文档之间打通数据的场景依赖客户端环境需要做本地服务通信wps-js-demo属于第三种。它的本质是开发一个WPS加载项Add-in而这个加载项里的界面可以用HTML/JavaScript来写。当你在网页里需要操作文档时可以通过加载项提供的API去调用。1.3 JS插件模式的工作流程用一句话概括这套模式网页端通过HTTP请求或WebSocket连接到WPS加载项启动的本地服务本地服务再调用WPS的文档对象模型Document Object Model接口去操作文档。整个过程就像是你打开了一个远程桌面网页负责下发指令WPS负责干活中间通信的信使是加载项框架。这样说可能有点抽象我举个生活中的例子。你可以把WPS想象成一个只会说方言的老员工浏览器是一个只会说普通话的新人两边无法直接沟通。加载项框架就是一个翻译官新人用标准指令JavaScript API对翻译官说话翻译官再转述成老员工能听懂的命令。所以开发WPS插件和解剖复杂原理没有太大关系真正要掌握的是调用API的姿势以及理解这个翻译官的工作边界。2. 本地环境搭建与第一个Demo复盘2.1 环境依赖清单跑通wps-js-demo之前先检查本地环境。很多人在这一步就被卡住了不是WPS没装就是装的是旧版本加载项功能都没开放。我建议按以下清单核对Windows系统WPS对Windows支持最完善WPS Office 2019及以上版本必须安装完整版精简版可能不包含VBA和加载项相关组件Node.js 14以上用于跑CLI工具和本地调试浏览器Chrome或Edge均可有一个比较隐蔽的坑WPS安装好后默认有可能没有开启开发工具相关的权限入口。你需要打开WPS进入设置找到高级或开发相关的选项确认允许加载第三方加载项。这一步不做好后面所有代码都是白写。2.2 wpsjs CLI初始化项目wps-js-demo这类项目通常可以用官方脚手架工具快速创建。我习惯这样操作npm install -g wpsjs wpsjs create my-wps-plugin cd my-wps-plugin创建出来的项目会有一个典型的加载项目录结构包含一个前端资源目录html/js/css、一个manifest.xml配置文件以及一个用于存放文档操作代码的目录。这里我想多说一句CLI工具的价值。它不只是帮你生成目录更重要的是它封装了加载项的打包和校验。如果你手工创建一个manifest文件字段稍微写错WPS客户端很可能直接拒绝加载连错误提示都看不到。用官方CLI能在打包阶段就发现问题。2.3 manifest.xml的权限声明细节manifest.xml是加载项的身份证WPS客户端拿到这个文件才知道插件叫什么名字、从哪个页面加载界面、需要哪些权限。下面是核心字段的样例?xml version1.0 encodingUTF-8? OfficeApp xmlnshttp://schemas.microsoft.com/office/appforoffice/1.1 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:bthttp://schemas.microsoft.com/office/officeappbasictypes/1.0 xmlns:ovhttp://schemas.microsoft.com/office/taskpaneappversion/1.0 xsi:typeTaskPaneApp Idyour-plugin-id-here/Id Version1.0.0.0/Version ProviderNameYour Company/ProviderName DefaultLocalezh-CN/DefaultLocale DisplayName DefaultValue演示插件 / Description DefaultValueWPS JS 插件演示/ Hosts Host NameDocument / /Hosts DefaultSettings SourceLocation DefaultValuehttps://localhost:3000/index.html / /DefaultSettings PermissionsReadWriteDocument/Permissions /OfficeApp很多人会把SourceLocation照着网上的例子写成线上地址结果本地调试发现页面加载不出来。这个字段指向的是你加载项UI所在的页面地址。开发阶段我建议指向本地开发服务器地址比如https://localhost:3000/index.html然后通过wpsjs的调试命令启动本地HTTPS服务。Permissions字段值得单独说。它声明了插件能对文档做什么。只读需求就写ReadDocument需要修改内容就写ReadWriteDocument。权限过大风险高权限过小功能跑不起来按需申请就行。3. 核心API调用从打开文档到拿到内容3.1 文档打开与加载完成判断当加载项被加载到WPS之后你的任务窗格页面就运行在一个内嵌浏览器环境里。这个时候就可以通过API去控制文档了。首先要解决的就是怎么拿到当前打开的文档对象。// 等待WPS插件环境初始化完成 window.office.onReady(function() { // 获取当前文档对象 const doc WPS.Api.Document; console.log(文档对象已获取, doc); });需要注意office.onReady的触发时机表示插件环境已经就绪但并不意味着文档已经完全加载。如果你在文档非常大的情况下执行读取操作可能会拿到还在加载的残缺内容。稳妥的做法是在onReady回调里再监听文档加载状态或者直接通过API检查文档是否处于就绪状态。3.2 选区读取与内容写回假设你现在已经打开了Word类型的文档WPS的Document宿主需要读取用户选中的一段文字然后把它回填到网页表单的一个输入框里。这个场景在企业审批、合同审核流程里非常常见。核心代码大致是这样function getSelectedText() { const range WPS.Api.Document.GetSelection(); const text range.Text; document.getElementById(selectedText).value text; }如果你要做网页表单生成一份新文档这种更进阶的操作可以直接操作文档对象模型。我去年给一家公司做投标文件生成系统时就是基于这个思路用户在网页上填完关键信息点一下生成文档代码就往WPS文档的指定书签Bookmark位置写入内容再自动保存。function insertTextAtBookmark(bookmarkName, content) { const bookmark WPS.Api.Document.GetBookmarkByName(bookmarkName); if (bookmark) { bookmark.InsertText(content); } }写这段代码时有一个容易被忽略的问题书签不存在时InsertText会报错。所以每次写之前一定要先判断书签是否拿到。我习惯写一个辅助函数专门做存在性检查。3.3 任务窗格与事件回调加载项模式下用户同时面对两个界面左侧或右侧的任务窗格你的HTML页面和中间的WPS文档。交互经常是这样用户点击文档某处任务窗格实时显示当前光标所在的段落信息。这需要注册文档事件。window.office.context.document.addHandler(WPS.EventType.DocumentSelectionChanged, function() { const range WPS.Api.Document.GetSelection(); updatePanelInfo(range); });事件回调的机制带来一个好处你不需要在网页里轮询文档状态WPS会主动推送变化。这个设计让我想起了浏览器里的MutationObserver都是订阅-通知模式比定时器刷新的体验好太多。4. 网页端集成把Demo变成业务系统里的一个功能4.1 嵌入方式的选择Demo跑通之后真正的考验是怎么把这个插件能力变成业务系统的功能。我实践下来网页端集成主要有两种方式第一种是iframe内嵌把任务窗格页面作为iframe嵌入到OA系统的页面里第二种是独立弹窗或新标签页打开。如果选择iframe内嵌有一个非常重要的注意点WPS插件框架对跨域通信有安全限制。你的业务系统域名和加载项SourceLocation域名一旦不一致iframe内的页面可能无法正常调用WPS API。实际开发中我建议让加载项页面通过postMessage与父页面通信再由父页面决定如何处理业务数据。4.2 postMessage通信与免登处理真实场景里网页端往往有自己的登录态。插件的任务窗格页面如果独立加载它并不知道当前用户是谁。我踩过一次比较痛的跟头把一个内部知识库系统的文档合同审核页面嵌进WPS插件页面一加载就向后端请求用户信息结果因为跨域且没有带上登录Cookie接口直接返回401。后来我的解决思路是网页端先校验自己的登录态通过postMessage把必要的用户身份信息传给孩子页面// 业务系统侧 const pluginFrame document.getElementById(pluginFrame); pluginFrame.contentWindow.postMessage({ type: auth, token: getUserToken(), userId: getUserId() }, *);这种做法的核心是业务系统负责认证插件页面只负责文档操作。不要把敏感逻辑全部塞进插件UI否则后面维护会非常痛苦。4.3 多人协作和文件保存链路的注意点还有一个实际业务中一定会遇到的问题文件保存。用户通过网页唤起WPS修改完文档后文档可能是保存在本地的也可能是存储在服务器上的。如果是服务器上的文档加载项打开之后本地修改和服务器版本之间如何同步稳妥的方案是本地修改只作为临时工作副本关闭WPS后通过网页端的上传/同步按钮手动提交到服务器。这样做的原因很简单——自动化实时同步涉及文件锁、版本冲突处理等复杂逻辑贸然做成全自动一旦多人同时编辑同一份文档很容易互相覆盖。我在给企业做集成时一般会在任务窗格页面上加两个按钮打开服务器文档和保存回服务器。前者从后端拉取文档流再调用WPS打开后者获取当前文档内容并上传。整个流程清晰可控用户也不会因为文档被莫名覆盖而产生困扰。5. 调试与常见问题排查5.1 本地调试连不上WPS实例怎么办我刚开始调试时遇到最频繁的问题就是页面明明加载出来了但调WPS Api.Document的时候提示undefined或者当前环境不支持。排查这个问题我建议按以下顺序来确认WPS版本是否支持加载项检查设置里有没有开发工具相关入口确认manifest.xml里Hosts声明是不是Document如果你打开的是表格但插件声明只支持文档API就会失效在页面启动代码里加console.log打印当前的WPS.Api是否存在如果依然不行把WPS进程全部结束重新启动WPS再加载插件5.2 API行为差异与版本兼容开发过程中要记住一个原则WPS的JS API规范和微软Office的JavaScript API规范有相似之处但并非完全一致。网上很多教程是基于Office插件写的代码搬到WPS上可能会报错。我建议在写代码时多查WPS开放平台的最新API文档碰到API不确定时先写一个最小测试页在目标机器上验证过了再继续往下写。与其靠猜不如花十分钟验证一次这个习惯能省下很多调试时间。5.3 三个最容易踩的坑第一个坑是HTTP和HTTPS混用。WPS加载项页面如果用了HTTPS但API请求指向HTTP的本地服务会被浏览器拦截。开发时统一走HTTPS自签名证书要提前配置信任否则页面白屏。第二个坑是事件绑定之后忘记卸载。插件任务窗格反复重建时事件处理函数如果越积越多你会发现文档操作越来越卡。在页面销毁或插件关闭时记得调用移除事件的方法。第三个坑是中文路径和特殊字符。打开服务器上的文档时路径或文件名里有中文、空格、百分号解析失败的概率大增。我习惯在上传下载前用encodeURIComponent处理后端保存时生成临时文件再传给WPS能避开绝大多数乱码或找不到文件的问题。6. 从演示到落地的一点心得wps-js-demo的核心思路虽然简单但从能跑通的Demo到稳定落地的功能中间其实隔着一层对业务场景的理解。技术本身并不难难的是把网页流程和本地文档操作整合进一条顺畅的用户路径里。有条件的话尽早让用户参加测试你才会发现哪些操作是用户真正需要的哪些只是技术人员的自嗨。如果产品形态允许优先做小范围试点再逐步推广这样既能把风险控制在可接受范围内也能根据反馈持续打磨交互细节。本文还有配套的精品资源点击获取
