主页 2.1 Help

开发手册

创建项目

wpsjs create {工程名}

按需选择（文字、表格、演示），回车 按需选择框架（JS、Vue、React），回车 根据需要选择框架此处按照无框架演示 如下，创建成功

? 选择 WPS 加载项类型: 文字 ? 选择UI框架: 无 added 1 package in 1s ==>> 执行以下命令进行 WPS 加载项开发: $ cd test2222 $ wpsjs debug

加载项工程结构介绍

  • 项目名

    • node_modules

    • images

      • 1.svg

      • 2.svg

      • 3.svg

      • newFromTemp.svg

    • js

      • dialog.js

      • ribbon.js

      • systemdemo.js

      • taskpane.js

      • util.js

    • ui

      • dialog.html

      • taskpane.html

    • index.html

    • main.js

    • package.json

    • ribbon.xml

目录

文件

描述

images

-

图片资源 ribbon 菜单中的图标等

js

-

-

dialog.js

对话框功能 JS

-

ribbon.js

ribbon 入口功能 JS

-

systemdemo.js

业务系统接口定义

-

taskpane.js

任务窗格JS

-

util.js

工具类 包括枚举定义等

wps-jsapi

-

代码提示工具

ui

-

-

-

dialog.html

定义对话框内部页面

-

taskpane.html

定义侧边栏内部页面

-

index.html

入口文件

-

main.js

用来加载各JS

-

ribbon.xml

定义customUI

其中index.html和ribbon.xml为核心文件

  • index.html代表项目加载的入口，在业务系统唤醒WPS时，首先加载的就是该文件

  • ribbon.xml代表定义的功能，如按钮、右键菜单、事件重写等。并对其这些事件定义了visible/enable/action的入口

index.html说明

index入口文件：在index中我们只加载了main.js一个文件 事实上我们可以根据业务系统的需求自行修改

<!DOCTYPE html> <html> <meta charset="utf-8"> <script type="text/javascript" src="./main.js"></script> </html> <!--这个文件是wps加载项的入口文件，wps在启动时加载这个文件-->

main.js说明

该文件主要用来加载所有代码

//这个文件由index.html包含 document.write("<script language='javascript' src='js/util.js'></script>"); document.write("<script language='javascript' src='js/ribbon.js'></script>"); document.write("<script language='javascript' src='js/systemdemo.js'></script>");

在main.js中加载代码时在末尾添加时间参数，用户每次打开客户端可获取到最新代码，免去清除缓存步骤（如下例图） {id="

main-js_1"}

//main.js文件由index.html包含 var developVersion = new Date().getTime(); var JSALL = [ //wps4oa devTest 加载时注意先后顺序 "js/util.js", //枚举 "js/ribbon.js", //工具栏控制 "js/lib/common.js", //lib 一些通用方法 "js/lib/formdata.js", //lib formdata "js/wpsApi.js", //提供给业务系统的调用入口，以及业务逻辑、功能逻辑 "js/Event.js", //wps 监听事件 ]; JSALL.forEach((JSURL) => { document.write( "<script language='javascript' src='" + JSURL + "?v=" + developVersion + "'></script>" ); });

ribbon.xml说明

ribbon.xml名词解释表

名词

解释

Tab

工具栏

Group

组

Button

按钮

Label

显示名称

GetLabel

设置名称的事件

OnAction

按钮点击事件/命令执行事件

Enabled

启用状态

GetEnabled

设置启用状态的事件

Visible

可视状态

GetVisible

设置可视状态的事件

GetImage

设置图标的事件

Size

按钮大小

Command

命令

IdMso

命令的idMso(不等于id)

ContextMenu

右键菜单

OnLoad

初始化事件

GetLabel、GetEnabled、GetVisible、GetImage这些属性的值应该填写一个函数名 在加载到该按钮的时候，会根据这些函数去动态返回一个按钮的属性

function GetImage(control) { const eleId = control.Id return "images/newFromTemp.svg" } function OnGetEnabled(control) { const eleId = control.Id return true } function OnGetVisible(control){ return true } function OnGetLabel(control){ const eleId = control.Id return "按钮" }

Label、Enabled、Visible 等属性则需要直接赋予默认值

部署模式

动态传递模式

动态传递模式，业务系统调用才会加载加载项，需唤醒时传入加载项地址 版本要求：windows 10321及以上； linux 10681及以上

动态传递部署模式步骤

  1. 使用wpsjs包的wpsjs build命令进行打包

  2. 配置jsplugin.xml文件, url属性为加载项地址

    此步参考demo中server/wwwroot/jsplugin.xml 文件

    <jsplugins> <jsplugin name="JdjwJZX" type="wps" url="http://172.16.16.88:8080/jzx/package/JdjwJZX-230614.7z" version="3.0.0"/> </jsplugins>

  3. 将目录wps-addon-build下的文件署到服务器 (加载项代码)

  4. 将jsplugin.xml文件部署到服务器上 (WPS访问jsplugin.xml的配置加载对应代码)

  5. 业务系统集成时，调用唤起WpsInvoke传入jsplugin.xml地址
    [金山文档] jsplugins.xml配置文档.docx
    https://kdocs.cn/l/cBk8tsBIf

例: jsplugins部署

  1. 使用wpsjs包进行build打包

    wpsjs build ? 选择 WPS 加载项发布类型: 在线插件 ==>> 编译成功。请将目录C:\Users\NUC\Desktop\test222\test2222\wps-addon-build下的文件署到服务器...

  2. 将加载项代码署到服务器 (tomcat为例）

    将文件放到web目录

  3. jsplugins.xml文件部署到服务器上 (tomcat为例）

    jsplugins.xml放到相同目录

  4. 服务器调用时传入jsplugins.xml地址

  5. 服务器调用唤起WPS后，查看是否代码正常加载

  6. 加载项没正常显示？参考: 常见问题排查手册

代码调试

调试器开启和使用

  1. 配置oem.ini文件, 在support栏下配置 JsApiShowWebDebugger=true oem.ini文件路径

    [windows] 安装路径\WPS Office\{版本号}\office6\cfgs

    [linux] /opt/kingsoft/wps-office/office6/cfgs/

    [uos] /opt/apps/cn.wps.wps-office-pro/files/kingsoft/wps-office/office6/cfgs/

  2. linux机器上需要使用quickstartoffice restart重启WPS

  3. WPS打开后，在有文档的情况下按alt+F12 (index.html页面的调试器)

  4. ShowDialog和Taskpane页面的调试器，点击该弹窗或者任务窗格，按F12

如果无法打开调试器，说明加载项加载失败

注：动态传递模式，需要以业务系统唤醒的方式打开wps才有调试功能

业务系统集成加载项

集成SDK ： wpsjsrpcsdk.js_用于wpsjs加载项，web端前端页面的编写_

Npm下载最新版本SDK npm install wpsjs-rpc-sdk

目前支持：

  • 单进程模式 ：用户窗口下仅启动一个wps客户端，所有操作都会反映到该wps客户端下

  • 多进程模式 ：用户窗口下可以启动多个wps客户端，通过使用WpsClient对象调用接口，可以将操作发送到对应的wps客户端上，不同wps客户端互不影响

项目打包

wpsjs build
Last modified: 26 August 2024
环境依赖组件关系