WPS 加载项开发

最新推荐文章于 2024-07-25 16:31:51 发布

顺其自然~

最新推荐文章于 2024-07-25 16:31:51 发布

阅读量1.4w

点赞数 6

文章标签： wps加载项 wps

原文链接：https://open.wps.cn/docs/office

版权

WPS 加载项概述

WPS 加载项（Add-ins）是一套基于 Web 技术用来扩展 WPS 应用程序的解决方案。每个 WPS 加载项都对应打开了一个网页，并通过调用网页中 JavaScript 方法来完成其功能逻辑。 WPS 加载项打开的网页可以直接与 WPS 应用程序进行交互，同时一个 WPS 加载项中的多个网页形成了一个整体，相互之间可以进行数据共享。开发者不必关注浏览器兼容的问题，因为 WPS 加载项的底层是以 Chromium 开源浏览器项目为基础进行的优化扩展。 WPS 加载项具备快速开发、轻量化、跨平台的特性，目前已针对Windows/Linux操作系统进行适配。 WPS 加载项功能特点如下：（原理分析：内置chrome中集成了与wps客户端进行通讯的机制，同时可以调用wps开放的API。wps可通过内置chrome与第三方服务器进行通讯）。

完整的功能。可通过多种不同的方法对文档（相应的Word）、电子表格（相当于Excel）和演示文稿（相当于PowerPoint）进行创作、格式设置和操控；通过鼠标、键盘执行的操作几乎都能通过WPS 加载项完成；可以轻松地执行重复任务，实现自动化；
三种交互方式。 自定义功能区，采用公开的CustomUI标准，快速组织所有功能； 任务窗格，展示网页，内容更丰富； Web 对话框，结合事件监听，实现自由交互。
标准化集成。不影响 JavaScript 语言特性，网页运行效果和在浏览器中完全一致；WPS 加载项开发文档完整，接口设计符合 JavaScript 语法规范，避免不必要的学习成本，缩短开发周期。

生成首个 WPS 加载项

在本教程中，将创建一个 WPS 加载项，该加载项将：

设计自定义功能区
打开对话框
创建自定义任务窗格

准备开发环境

安装wps
安装Node.js
安装代码编辑器 Visual Studio Code

新建 WPS 加载项

1、管理员权限(如果安装的是wps个人版，不需要管理员权限)启动命令行，通过npm全局安装wpsjs开发工具包:
安装命令： npm install -g wpsjs, 如果之前已经安装了，可以检查下wpsjs版本，更新wpsjs的命令为:npm update -g wpsjs

2、新建一个wps加载项，假设这个wps加载项取名为"HelloWps"。
输入命令： wpsjs create HelloWps, 会出现如下图的几个选项:

通过上下方向键可以选择要创建的wps加载项的类型，如果选择“文字”，则创建的加载项会在wps文字程序中加载并运行，
同理选择“电子表格”，则会在wps表格中运行，这里假设我们选择的是“文字”，按Enter健确定。

3、选择示例代码的代码风格类型
wpsjs工具包提供了两种不同代码风格的示例，“无”代表示例代码中都是原生的js及html代码，没有集成vue\react等流行的前端框架。
"Vue"代表生成的示例代码集成了Vue相关的脚手架，在实际的项目中选用Vue基于示例代码可能更适合做工程化的开发，感兴趣的同学可以两种都尝试一下。
这里我们选择“无”，按Enter健确认。
确认后wpsjs工具包会在当前目录下生成一个HelloWps的文件夹，我们进入到此文件夹，可以看到HelloWps的相关代码已经生成：

4、开始调试并愉快的写代码
执行命令： wpsjs debug
执行此命令后即可开始调试，wpsjs工具包会自动启动wps并加载HelloWps这个加载项，同时wpsjs工具包启了一个http服务,此服务主要提供两方面的能力:
a、提供前端页的的热更新服务，wpsjs工具包检测到网页数据变化时，自动刷新页面。
b、提供wps加载项的在线服务，wpsjs生成的代码示例是一个在线模式，wps客户端程序实际上是通过http服务来请求在线的wps加载项相关代码和资源的。（自动下载wps加载项到某个临时文件夹中或者直接加载到内存中）
最后，可以用visual studio code打开示例代码，开始愉快的写代码了。

备注：wpsjs工具包为示例代码中有一个package.json文件，这是node工具标准的配置文件，其中有一个依赖包为wps-jsapi,
这个依赖包是wps支持的全部接口的TypeScript描述，方便在vscode中敲代码时，提供代码联想功能，由于wps接口会跟随业务
需求不断更新，因此当发现代码联想对于有些接口不支持时，通过 npm update --save-dev wps-jsapi命令定期更新这个包。

以上展示了如何开始第一个wps加载项的制作，在实际用况中，如果需要让企业的业务系统与wps加载项进行集成，可以参考以下示例：OA助手示例

WPS 加载项开发说明

WPS 加载项结构

WPS 加载项由自定义功能区和网页两部分组成。自定义功能区只需要一个配置文件，对应 WPS 加载项目录中的ribbon.xml文件；网页部分负责执行自定义功能区对应的逻辑功能。因为不需要显示网页，所以省略了 HTML 文件，并用main.js来引入所有的外部 JavaScript 文件；在这些 JavaScript 文件中通常包含了一系列用 JavaScript 实现的函数，这些函数与自定义功能区的功能一一对应，我们称之为接口函数。

启动流程

WPS 加载项启动时，首先在 WPS 加载项对应文件夹中自动创建index.html网页并打开，index.html从当前路径引入main.js，从而能够在接下来的过程中执行接口函数。当网页打开成功之后，开始解析ribbon.xml生成自定义功能区，解析过程中会调用若干次接口函数，最终完成加载。注意，开发者应当避免在该目录下创建index.html。

WPS 加载项 API 使用

WPS 加载项 API 通过对 JavaScript 功能进行的扩展，实现了网页与 WPS 应用程序交互的能力。这些 API 被集中在window.wps对象下，而我们在开发中通常会省略掉window，直接以wps开始。

调试

WPS 加载项调试是对其中的一个网页单独进行的调试。调试时会弹出一个独立调试器对话框，除此之外和网页调试基本一致。可以在调试器的 Console 中直接查看任意的 API 属性和调用 API 方法。调试自动生成的index.html网页，使用快捷键 ALT + F12。注意调试过程中需要先关闭alert或其它同步弹框，才能继续向下调试。

系统集成

用户可以在自己的浏览器中调用 WPS 加载项的 JavaScript 方法。 wps_sdk.js对调用进行了封装，让开发者可以快速调用， wps_sdk.js对Chrome、Edge、IE8及IE8以上浏览器进行了支持。其它方式的集成请参考wps_sdk.js实现。点击这里试一下吧。

WpsInvoke.InvokeAsHttp(WpsInvoke.ClientType.wps, 'JsDemo', 'OnbtnShowDialogClick', {}, function (res) {
if (res.status == 0)
	alert('finish')
else
	alert(res.message)
})

接口定义

WpsInvoke.InvokeAsHttp(type, name, func, params, callBack)

参数

其中 WpsInvoke 是wps_sdk.js封装的对象，InvokeAsHttp是启动 WPS 应用程序的接口。

type ： WPS 应用程序的类型，类型的定义在ClientType中，ClientType.wps代表文字（word process ）、ClientType.et代表表格（electric table）、ClientType.wpp代表演示（wps power point）。
name ： WPS 加载项名称。
func ：执行的 JavaScript 方法。
params ：传递给方法func的参数。
callBack ： WpsInvoke.InvokeAsHttp执行的回调函数。

说明

启动 WPS 应用程序需要用户在浏览器点击允许启动 WPS Office。WpsInvoke.InvokeAsHttp执行是异步的，调用后立刻返回。等到WpsInvoke.InvokeAsHttp执行完成后，执行callBack回调函数，并给回调函数传参

{
	status: 0,  //返回状态。0 代表成功；1 代表上次请求没有完成；2 代表没有允许执行。
	message: "" //返回状态描述信息
}

发布部署

加载项开发完成后，很多开发者可能会有这样的一些问题：加载项如何部署呢、用户如何访问部署后的加载项呢、用户需要安装什么、用户是否需要去手动修改配置呢

目前我们提供两种部署方式，jsplugins.xml模式和publish.xml模式，两种都不需要用户去手动配置什么。只需要本地安装好相应版本的WPS就行。WPS可以同时支持这两种模式。

1、publish模式

1.1 模式介绍

publish模式是通过wpsjs工具包的wpsjs publish命令打包，将生成的文件夹下的所有文件部署到打包时填写服务器地址去。告知用户publish.html地址，业务系统开发商可将publish.html的功能按需整合到自己的页面中，便于做基础环境监测。也可以复用此页面给到用户，用户可自己控制启用和禁用哪些加载项。
1.2 部署
- 使用wpsjs包的wpsjs publish命令进行打包
- 将目录wps-addon-build下的文件署到服务器
- 将wps-addon-publish下的publish.html文件部署到服务器上，一般与加载项分开部署。
- 告知用户publish.html文件地址。
  wpsjs工具包使用
1.3 加载项加载流程
- 用户在浏览器中打开publish.html文件
- 校验加载项是否正常
  - 在线模式：去请求地址+/ribbon.xml和地址+/index.html
  - 离线模式：校验改地址是否能够访问到压缩包
- 点击安装或卸载的加载项
- 本地自动生成publish.xml文件
  - window：%appdata%/kingsoft/wps/jsaddons
  - linux: ~/.local/share/Kingsoft/wps/jsaddons
- 启动WPS
- 读取本地publish.xml文件
- 加载对应组件的所有加载项
- 根据业务系统指定的加载项名称，使用该加载项来接收参数
- 业务开发方可将此页面的方法按需整合到自己的需要调起WPS的业务场景中，从而达到自动化的环境配置。
1.4 适用场景
- 只交付WPS基础包，无需二次打包
- 实现集成松耦合
- 便于业务开发方按需定义集成场景
1.5 版本支持情况
- Windows：企业版20200425分支之后版本
- Linux：企业版20200530分支之后版本

2、jsplugins.xml模式

2.1 模式介绍

    jsplugins.xml模式是通过设置oem.ini配置文件的JSPluginsServer的值为加载项管理文件jsplugins.xml来控制加载项的加载（相当于WPS加载项列表文件），二次打包时，业务开发商需要告知我们JSPluginsServer的配置地址，将起配置到oem.ini文件中，业务开发商再做安装包分发。

    后续的加载项的控制用，业务开发商可以自由的更改jsplugins.xml文件，实现加载项的新增，修改。

    jsplugins.xml文件的配置
2.2 部署
- 使用wpsjs包的wpsjs build进行加载项打包
- 将目录wps-addon-build下的文件署到服务器
- 配置jsplugins.xml文件
- 部署jsplugins.xml文件，一般和加载项项目分开部署
- 告知WPS获取jsplugins.xml的网络地址，即JSPluginsServer。（只需要打一次包，后续更改jsplugins.xml的内容不需要再次打包）
  wpsjs工具包使用
2.3 加载项加载流程
- 启动WPS
- 读取oem.ini，去下载JSPluginsServer对应地址的jsplugins.xml文件
  - window：%appdata%/kingsoft/wps/jsaddons
  - linux: ~/.local/share/Kingsoft/wps/jsaddons
- 读取jsplugins.xml文件
- 加载对应组件的所有加载项
- 根据业务系统指定的加载项名称，使用该加载项来接收参数
2.4 适用场景
- 本来就需要做二次打包的项目
2.5 版本支持情况
- Windows：2019版本，2020发的版本
- Linux：2019版本，2020年3月后发的版本