# 金山WPS客户端JSAPI加载项集成文档
# 前言
使用WPS加载项无需安装额外控件，在线编辑是打开WPS的客户端，能保证内容1：1还原，并且还能打开微软的Office文件。
# 安装要求
推荐使用WPS2019专业版，版本号为v11.8.2.10255。Windows仅支持10255及其以上专业版。注意：最好使用10255版本，其他版本未过测试。你可以打开WPS，点击右上角设置图标，在关于WPS后面可以看到当前软件的版本号。
使用WPS加载项最重要一点是：保证本机已安装WPS专业版，并且对版本有严格要求，只有从金山供应商购买的WPS并且由供应商提供的WPS安装程序才能使用加载项。
所有个人从金山官网下载的WPS均不支持加载项。
详细要求配置可参考[关联文档](【流版签】【wps】WPS365在OA中集成使用方法 https://open.seeyoncloud.com/#/faq/faq/v1/share?url=Z2JySmU+Nzkz "关联文档")。
# 插件和配置
加载项支持的OA版本是8.0SP2及其以上版本，以系统管理员身份登录，点击设置进入"后台管理"：
进入后台管理后，选择点击"系统参数设置"：
进入系统参数设置后，找到"功能选项"，在"是否混合使用金格插件和WPS加载项"中选择"否"。如果这个选项是"是"，代表在相关的后续的操作中，会优先使用金格控件，但是如果金格控件不可用的话，就会使用WPS加载项，我们在这里选择"否"，来默认使用WPS加载项。（注意：该菜单受加密狗"国标插件"控制，没有插件则无法显示）
设置系统参数后，点击确定，退出并重新登录。
# 使用示例
正常登录系统，在"协同工作"，点击"新建事项"：
在"正文类型"中选择"Word正文"，并确定继续：
# 首次启动WPS服务场景
首次访问，或者重启电脑，均需要启动服务（用于唤醒wps进程）：
点击后，可能浏览器会弹出申请打开链接的弹窗（这是浏览器访问金山接口的安全机制控制），此时可勾选复选框后，单击红框中的按钮即可：
此时可能会弹出如下窗口，这时直接点击启动服务即可(根据电脑性能等影响，可能wps接口无法立即给出响应导致)，重新再启动，如果多次无法启动，则需要判断当前wps版本是否支持加载项：
然后点击重新加载，刷新页面：
然后重新选择在"正文类型"中选择"Word正文"，并确定继续，此时可以成功打开WPS服务。
# 已经启动WPS服务场景
此时点击"Word正文"，可以直接弹出WPS服务：
进入WPS文字后，点击右上角退出后，会回到浏览器界面，此时点击窗口中显示的打开正文，仍然可以重新进入：
最后就可以使用WPS加载项编辑内容了：
# 开启调试模式
开发或者分析问题时，可能需要开启调试模式。
# 调试模式：配置参数
【Windows环境】
进入安装目录，找到oem.ini文件，可能在WPS Office > 11.8.2.10255 > office6 > cfgs 目录下面：
然后【support】增加配置JsApiShowWebDebugger=true：
【信创环境】
卸载 :sudo dpkg -r xxx
安装：sudo dpkg -i xxx
1、授权：
sudo chmod -R 777 /opt/apps/cn.wps.wps-office-pro/files/
2、修改oem.ini：
uos环境：龙芯
cd /opt/apps/cn.wps.wps-office-pro/files/kingsoft/wps-office/office6/cfgs
linux：银河麒麟
cd /opt/kingsoft/wps-office/office6/cfgs
开始修改：
vim oem.ini
JsApiShowWebDebugger=true
3、重启：
cd /opt/apps/cn.wps.wps-office-pro/files/bin
国产机修改后重启：终端执行 quickstartoffice restart
备注：金山文档 https://www.kdocs.cn/l/cCVZwo3LW (opens new window)
查找publish.xml文件
windows: 我的电脑地址栏中输入：%appdata%\kingsoft\wps\jsaddons
linux: 我的电脑地址栏中输入：~/.local/share/Kingsoft/wps/jsaddons
# 调试模式：跟踪调试
WPS打开文档后，鼠标点到页签，按alt+F12：
按了之后会弹出类似浏览器控制台（该控制台主要可调试WPS内部触发的加载项逻辑，例如OA触发打开文件）
"任务窗格"的点击事件需要跟踪，把鼠标放在任务窗格，点ALT+F12
（该控制台主要可调试"任务窗格"点击后的逻辑，例如点击左侧的"保存"按钮）
# 代码实现
OA触发wps客户端执行业务代码的逻辑在wps.js中，通过调用_WpsInvoke方法来调用wps_sdk.js(金山提供的)来和wps客户端通讯。
wps加载项，有一个版本支持多进程方式，目前只给了中石油客开使用，没有提交标准版本。代码工程：http://gitlab.seeyon.com/ctp/apps-common/-/tree/require-wps-cnpc-develop (opens new window)
wps客户端的代码在apps-common工程，代码分别为表格和和文字的，代码逻辑是一模一样，只是表格的语法不一样，因此只要看了文字的功能，表格也就明白：
# 代码实现：打开文档
打开在线文档，oa浏览器触发wps客户端，在wps的func_oastarter.js文件的dispatcher()方法，这个方法是web页面调用WPS的方法入口：
而在这里面，定义了如何打开在线文档的方法，涉及到了位于wps.js文件里面的函数OnlineEditDoc()：
OA浏览器触发wps的最后代码位于wps.js，打开文档方法 OnlineEditDoc()：
该函数的主要功能实际上是修改参数以及调用_WpsInvoke()函数，参数的修改对象是一个全局WPS上下文类型，该对象指定了很多属性来表示WPS文件的各种状态：
OnlineEditDoc()修改了3个属性（业务中会根据他们来进行些控制，这个不是最主要的，分析时可全局搜索），分别是：
\"renderWpsFlag\" ：wps 渲染标记
\"wpsCloseFlag\"：wps打开文档标记
\"changeFlag\"：是否调用模板标记
OnlineEditDoc()根据业务情况和参数传值来修改这些属性的的值：
只要需要打开WPS，必然需要经过_WpsInvoke方法，这是调用wps客户端的最后一个业务方法：
改方法会调用wps_sdk.js(金山提供)的方法和wps客户端通讯，这个文件是金山给我们提供的，我们不做任何修改，如果需要修改，则和master反馈。
# 代码实现：消息通知
1、消息监听
消息通知有消息监听的形式，比如WPS文字监听函数，通过传入参数的信息，来设定文档的属性，实现一个信息的传递功能。例如WPS客户端对文档保存、修改、关闭等操作，需要告诉oa，则通过改消息机制来实现：
表格信息监听的方式如出一辙，也是通过传递的参数信息来判断和修改对象的属性值：
在后面，还对这两个监听方法实现了一个封装，并且为了实现加载上的一个同步，还设置了一个200ms的延迟时间（很多业务组加载js文件是异步的，会存在wps_sdk.js没有引入就开始初始代码而导致undefined错误）：
2、心跳机制
Wps客户端访问oa时，是wps的内置浏览器触发请求，因此存在另一个seesion，这个新的seesion在OA是没有登录的，会被拦截。因此需要一套安全机制。
wps和oa服务器通讯，目前我们使用的是类似一个心跳的机制，下边是它时序图：
当需要使用加载项时，OA页面会触发生成
3、保存文档
进入WPS，点击保存，触发点击事件：
跟踪代码，此时会调用方法OnAction()，最终相应的执行OnBtnSaveToServer()方法：
继续跟踪OnBtnSaveToServer()方法，进入func_tabcontrol.js文件的OnBtnSaveToServer()方法：
进入核心代码行uploadToServer()方法的调用，然后在这里奇怪的是，我进入该行代码的执行，但是显现的并不是我想看到的那个函数（可能是一些浏览器显示乱跳的问题，我们可以使用debugger来强制使用断点进入）：
进入后调用的是这一行，也就是调用btnShowDoc()函数的最末行，而不是uploadToServer()的第一行：
随后执行函数onAutoUploadSuccess()，执行完该函数过后，：
4、保存文档回调
保存文档回调的关键代码是对象WpsConstent的saveFileCallBack()方法：
# 代码实现：执行专业签章
文件wps.js
①判断是否有专业签章函数
fileId：文件Id
ClientType：客户端类型(wps或et)，若不传将被设置为wps
返回值为boolean
②函数_WpsInvoke
funcs：调用的函数名，JSON格式
OAAssistType：客户端类型，若不传将被设置为wps
调用wpsFunc去做判断，其中info的值为{"HasSpecialSignature":fileId...}
判断结果将传入回调函数的参数result
文件func_oastarter.js
①判断是否有金格专业签章
判断doc中sheet的每一项的shape的每一项，有三种情况均可确定有金格专业签章，满足任意一项均可return true。
# 代码实现：执行图片签章
①文件wps.js
传入funcs的函数名为"HasPicSignature"
与专业签章逻辑一致
②文件func_oastarter.js
判断doc中sheet的每一项的shape的每一项，提取出关键字用于判断是否为金格图片签章。
# 代码实现：文档是否已经打开
含义：OA主动发起请求到wps客户端（wps加载项）中请求文档是否处于打开状态。
1、OA主动发起请求
apps-common\src\main\webapp\common\office\js\wps.js
2、wps客户端接收
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_oastarter.js
3、根据本地是否存在对应的文件id判断是否文档已经打开
# 代码实现：套红
含义：OA主动发起请求到wps客户端（wps加载项）中进行在线套红处理。
1、OA主动发起
apps-common\src\main\webapp\common\office\js\wps.js
2、wps客户端接收
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_oastarter.js
3、wps客户端处理
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_docProcess.js
先判断文档是否存在，后执行判断权限是否允许，执行套红操作。
# 代码实现：获取公文域或书签数量
含义：OA主动发起请求到wps客户端（wps加载项）中进行获取公文域或书签数量，参数为文件id。
1、OA主动发起
apps-common\src\main\webapp\common\office\js\wps.js
2、wps客户端接收处理
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_oastarter.js
3、根据文件id处理文件
# 代码实现：获取书签名列表
含义：OA主动发起请求到wps客户端（wps加载项）中进行获取书签名。
1、OA发起
apps-common\src\main\webapp\common\office\js\wps.js
2、wps客户端接收
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_oastarter.js
3、逻辑处理
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_docProcess.js
# 代码实现：删除书签
含义：OA主动发起请求到wps客户端（wps加载项）中进行删除书签操作。
1、OA发起
apps-common\src\main\webapp\common\office\js\wps.js
2、wps客户端处理
apps-common\src\main\webapp\common\wpsOfficeAssist\WpsOAAssist\js\common\func_docProcess.js
# 代码实现：更新参数
更新权限等操作会调用该函数
①文件wps.js
paramObj：参数对象
直接调用_WpsInvoke函数
无需设置ClientType
需要设置ClientType
②文件func_oastarter.js
调用addParamsToDoc函数并刷新权限
文件func_docProcess.js
具体的合并两个params的操作
# 代码实现：激活文档
①文件wps.js
②文件func_docProcess.js
# 代码实现：强制wps保存
文件wps.js
调用_WpsInvoke
# 代码实现：国际化
①获取国际化信息
文件baseOffice.js
②从oa缓存中获取国际化信息
文件wps.js
# 代码实现：打印
含义：在打开的wps客户端的当前打开文档中调起打印页面设置框。进行文档的打印实现。
1、入口函数
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\taskpane.html
2、执行打印逻辑
a. 获取当前激活文档：wpsApp.ActiveDocument
b. 延时加载打印逻辑：wpsApp.CommandBars.ExecuteMso("FilePrint");
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\js\common.js
# 代码实现：WPS权限控制
含义：根据OA系统传递的数据进行任务窗格功能性的动态渲染与Ribbon按钮(wps上层默认功能按钮)是否可用，以及默认功能重写。
# 1、任务窗格
加载逻辑：通过从OA端获取参数，使用wps加载项提供的参数共享方式wps.PluginStorage.setItem()来初始化需要展示的任务窗格参数。wps.PluginStorage.getItem()获取任务窗格参数，在taskpane.html中渲染任务窗格。
OA参数获取与初始化参数。
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\js\common.js
初始化菜单的参数：
params:OA参数
根据OA参数更新菜单权限：
params:OA参数
- 动态显示任务窗格
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\js\common.js
调起加载taskpane.html
{width="5.726388888888889in"
height="1.5303280839895013in"}
渲染任务窗格：
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\taskpane.html
{width="5.726388888888889in"
height="3.4402088801399824in"}
# 2、Ribbon按钮
- 加载逻辑：在ribbon.xml中定义出需要操作的功能权限，在初始化函数OnWPSWorkTabLoad中将需要操作的权限初始化以及挂载WPS的文档事件，比如：监听文档打开，监听文档关闭......。
a. idMso：控件名称，必须使用控件规定的名https://open.wps.cn/docs/office
b. getEnabled:是否生效。
c. onAction:自定义执行逻辑。
- 处理Ribbon按钮的是否可用
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\js\common\func_tabcontrol.js
{width="5.726388888888889in"
height="4.164646762904637in"}
- 自定义菜单按钮的点击执行事件
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\js\common\func_tabcontrol.js
# 代码实现：花脸
含义：简单说对历史编辑做一个展示，并提供选择权限进行一个历史编辑版本的信息展示。
1、执行逻辑
在任务窗格有花脸功能的情况下，点击对应花脸按钮，执行打开弹框逻辑，获取花脸数据，展示在弹框区域中，以进度项方式展示，点击对应任务项，获取对应任务项数据，切换并渲染新页面。打开只读文件。最后关闭弹框，关闭花脸模式。
2、弹框逻辑
a. 入口函数
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\taskpane.html
花脸此处使用了vue.js的展示和执行函数方式。
3、展示花脸弹框信息
wpsOfficeAssist\wpsOfficeAssist\WpsOAAssist\taskpane.html
执行函数：listHualian
发起ajax请求，获取花脸信息。
4、点击花脸对应任务项功能
a. 执行函数：open
b. 参数：item 每一个花脸任务项信息。
渲染新的界面并切换：
# 代码实现：清稿
含义：对文档的历史编辑痕迹进行一个清楚，然后保存全新的文档到服务器中。
1、入口函数
WpsOAAssist\js\common\func_tabcontrol.js
2、清稿后需要保存到服务器中，并刷新花脸
# 代码实现：转OFD、转PDF
①文件baseOffice.js
②文件handWrite_n.js
# 常见Bug和解决
每次重启电脑都会提示启动服务
因为重启电脑，wps进程就会退出。下次使用必定会启动服务来唤起wps，这个我们已经找过金山技术，他们无法做到自动启动，据说是系统安全有限制，无法实现重启电脑来自动启动wps。
无法启动服务或者wps无法唤起
问题排查【WPS 问题排查https://www.kdocs.cn/l/srSD8XlpL】：
注意：请务必确认，当前WPS版本是专业版，window是10255，信创是10290。（大于该版本的未全面测试）
1：文件地址栏输入%AppData%回车,进入如下地址，看看加载项的配置路径文件
如果有其他的xml，则删掉，只保留publish.xml。
2：打开publish.xml，只保留自己访问OA的ip地址的配置，有其他的，则全部删掉。
信创环境publish.xml文件地址：
linux： cd ~/.local/share/Kingsoft/wps/jsaddons
保存不成功
保存有延迟，上传文件到服务器需要时间，不要在保存的时候，立即关闭wps。
访问m3端失败
请访问：http://localhost/seeyon/H5/wechat/html/allApps.html 首页
- fildder总是弹出黄框阻塞
可能是启动了信创vpn或其他vpn
信创vpn
打开服务，将这三个服务关闭后禁用。
