# wpsjsrpcsdk.js

用于wpsjs加载项，web端前端页面的编写

目前支持：
* 单进程模式：用户窗口下仅启动一个wps客户端，所有操作都会反映到该wps客户端下
* 多进程模式：用户窗口下可以启动多个wps客户端，通过使用WpsClient对象调用接口，可以将操作发送到对应的wps客户端上，不同wps客户端互不影响
* 多用户模式（目前仅windows）：多个用户同时登陆一个服务器时，每个用户窗口下可以独立地通过web端操作wps客户端，不同用户的操作互不影响；支持单进程模式和多进程模式


# 接口使用
## 管理wps加载项：
`WpsAddonMgr.getAllConfig`
> 获取publish.xml的内容
> 
> @param {*} callBack 回调函数

`WpsAddonMgr.verifyStatus`
> 检查ribbon.xml文件是否有效
> 
> @param {*} element   参数对象
> 
> @param {*} callBack  回调函数

`WpsAddonMgr.enable`
> 启用加载项
> 
> @param {*} element   参数对象
> 
> @param {*} callBack  回调函数

`WpsAddonMgr.disable`
> 禁用加载项
> 
> @param {*} element   参数对象
> 
> @param {*} callBack  回调函数

## 单进程模式：
`WpsInvoke.InvokeAsHttp`
> 以http协议启动wps
> 
> @param {*} clientType    加载项类型， wps / wpp / et
> 
> @param {*} name          加载项名称
> 
> @param {*} func          客户端加载项要执行的方法
> 
> @param {*} param         客户端加载项执行方法的参数
> 
> @param {*} callback      回调函数
> 
> @param {*} showToFront   设置客户端是否显示到前面
> 
> @param {*} jsPluginsXml  设置加载项路径
> 
> @param {*} silentMode    是否是静默启动

`WpsInvoke.InvokeAsHttps`
> 以https协议启动wps
> 
> @param {*} clientType    加载项类型， wps / wpp / et
> 
> @param {*} name          加载项名称
> 
> @param {*} func          客户端加载项要执行的方法
> 
> @param {*} param         客户端加载项执行方法的参数
> 
> @param {*} callback      回调函数
> 
> @param {*} showToFront   设置客户端是否显示到前面
> 
> @param {*} jsPluginsXml  设置加载项路径
> 
> @param {*} silentMode    是否是静默启动

`WpsInvoke.RegWebNotify`
> 注册一个前端页面接收WPS传来消息的方法
> 
> @param {*} clientType wps | et | wpp
> 
> @param {*} name WPS加载项的名称
> 
> @param {*} callback 回调函数

`WpsInvoke.CreateXHR`
> 创建一个xhr对象

`WpsInvoke.IsClientRunning`
> 当前客户端是否在运行，使用WpsInvoke.IsClientRunning()进行调用
> 
> @param {string} clientType       加载项类型
> 
> @param {function} [callback]     回调函数，返回值如下：
> 
> "Client is running." 客户端正在运行
> 
> "Client is not running." 客户端没有运行

`WpsInvoke.ClientType`
> 加载项类型
> 
> wps / et / wpp


## 多进程模式：
`var wpsClient = new WpsClient(WpsInvoke.ClientType.wps)`
> @constructor WpsClient           wps客户端
> 
> @param {string} clientType       必传参数，加载项类型，有效值为"wps","wpp","et"；分别表示文字，演示，电子表格

`wpsClient.InvokeAsHttp`
> 以http启动
> 
> @param {string} name              加载项名称
> 
> @param {string} func              要调用的加载项中的函数行
> 
> @param {string} param             在加载项中执行函数func要传递的数据
> 
> @param {function({int, string})} callback        回调函数，status == 0 表示成功，失败请查看message信息
> 
> @param {bool} showToFront         设置wps是否显示到前面来
> 
> @return {string}                  返回值：
> 
> "Failed to send message to WPS." 发送消息失败；
> 
> "WPS Addon is not response." 加载项阻塞，函数执行失败

`wpsClient.InvokeAsHttps`
> 以https启动
> 
> @param {string} name              加载项名称
> 
> @param {string} func              要调用的加载项中的函数行
> 
> @param {string} param             在加载项中执行函数func要传递的数据
> 
> @param {function({int, string})} callback        回调函数，status == 0 表示成功，失败请查看message信息
> 
> @param {bool} showToFront         设置wps是否显示到前面来

`wpsClient.onMessage`
> 消息注册函数的回调函数

`wpsClient.StartWpsInSilentMode`
> 以静默模式启动客户端
> 
> @param {string} name                 必传参数，加载项名称
> 
> @param {function({int, string})} [callback]         回调函数，status == 0 表示成功，失败请查看message信息

`wpsClient.ShowToFront`
> 显示客户端到最前面
> 
> @param {string} name             必传参数，加载项名称
> 
> @param {function({int, string})} [callback]     回调函数

`wpsClient.CloseSilentClient`
> 关闭未显示出来的静默启动客户端
> 
> @param {string} name             必传参数，加载项名称
> 
> @param {function({int, string})} [callback]     回调函数

`wpsClient.IsClientRunning`
> 当前客户端是否在运行，使用WpsClient.IsClientRunning()进行调用
> 
> @param {function({int, string})} [callback]      回调函数，返回值如下：
> 
> "Client is running." 客户端正在运行
> 
> "Client is not running." 客户端没有运行

`wpsClient.jsPluginsXml`
> 设置加载项路径

## 多用户模式：
`EnableMultiUser()`
> 启用多用户模式

# 接口实现
`startWps`
> web端给加载项本地服务发请求的接口
> 
> 如果是非同步请求，先判断上一次请求是否完成
> 
> 绝大多数请求都建议采用同步请求，防止阻塞造成卡死
> 
> 请求发送后，成功得到响应时根据本地服务返回的内容，生成返回值返回给前端；status == 0 表示该次请求执行成功，status != 0 表示该次请求执行失败，通过访问message获得失败信息

`WpsStart`
> 启动wps客户端，加载项执行操作，无返回值

`WpsStartWrap`
> 加载项本地服务版本为空时，通过该接口启动wps

`WpsStartWrapExInner`
> 启动wps客户端，加载项执行操作，有返回值，支持浏览器触发

`WpsStartWrapVersionInner`
> 获取加载项本地服务的版本号
> 
> 1.0.0原始版本
> 
> 1.0.1版本支持多进程
> 
> 1.0.2版本支持多用户（目前仅windows）

`RegWebNotify`
> 向加载项本地服务发送接收客户端消息的注册请求
> 
> 分为单进程和多进程：
> 
> 单进程的请求不含有clientId，客户端发的消息，所有注册的请求都能收到
> 
> 多进程的请求含有clientId，客户端发的消息，只有当前客户端对应的WpsClient对象能收到
> f
> 同时，onload里有做一个容错处理：
> 
> 如果客户端发的消息是字符串化后的json对象，sdk可以解析成功，并将该对象返回给html，html根据需要获得自己想要的json数据
> 
> 如果客户端发的消息不是标准的json格式数据导致json解析失败，sdk也会将用户数据提取出来返回给html
> 
> 这里还有一个心跳包的机制，默认是开启的，只有当浏览器版本过低不支持worker时才会关闭。开发者可以通过手动注释掉
> ```js
> HeartBeatWorker = new Worker(codeToBlob(HeartBeatCode));
> ```
> 这一段代码来关闭心跳包。这里增加心跳包是为了让客户端发的消息不丢失，都能到达web端。

`GetUrlBase`
> 加载项本地服务监听的端口，http为58890，https为58891
> 
> 默认使用http协议
> 
> 如果要修改监听端口，需要同步修改oem.ini配置

`wpsclient.InvokeAsHttp`
> 以http启动多进程模式客户端
> 
> 回调函数里如果执行失败，会调用传进来的回调函数，然后return
> 
> 如果使用不支持多进程的wps客户端调用该接口，回调函数里会调用传进来的回调函数，并发送接收消息的注册请求，然后return

`wpsclient.InvokeAsHttps`
> 以https启动多进程模式客户端

`wpsclient.RegWebNotify`
> 多进程模式用来调用发送接收消息注册请求的接口
> 外部无需调用，`InvokeAsHttp`的回调函数里调用了

`wpsclient.OnRegWebNotify`
> 多进程模式用来调用消息注册函数的回调函数

`wpsclient.StartWpsInSilentMode`
> 以静默启动模式启动一个wps客户端，逻辑与`InvokeAsHttp`相同，只是增加了一个`silentMode = true`的标记

`wpsclient.ShowToFront`
> 将wps客户端显示到最前面

`wpsclient.CloseSilentClient`
> 关闭没有显现出来的静默启动客户端

`wpsclient.IsClientRunning`
> 判断客户端是否正在运行



# 版本改动
version 1.0.1
- 支持加载项管理

version 1.0.2
- 重命名为wpsjsrpcsdk.js

version 1.0.3
- 修改入口文件

version 1.0.4
- 引入注册监听报错
- 获取插件信息失败重试修改为3次

version 1.0.5
- xhr对象创建修改

version 1.0.6
- 添加wps置顶参数，showtofront

version 1.0.7
- 支持多进程
- 实现自动发送注册请求
- 增加静默启动
- 增加判断客户端是否在运行
- 区别服务器版本

version 1.0.8
- 不支持多进程的wps客户端提示升级客户端

version 1.0.9
- 增加注册超时
- 支持多个加载项同时注册消息

version 1.0.10
- 处理sdk在ie11下的注册问题

version 1.0.11
- 统一url的调用入口

version 1.0.12
- 处理一个url调用错误

version 1.0.13
- 支持消息队列
- 增加心跳包，防止消息被清

version 1.0.14
- 心跳包的创建兼容ie10

version 1.0.15
- 保证非原生加载也能执行InitSdk
- 版本号获取之后，增加自定义协议的启动逻辑

version 1.0.16
- 支持多用户，兼容老版本
- 注册请求添加json解析失败的容错机制
- 接口添加注释
- 多进程接口兼容单进程客户端，保证接口可用，但实际上启动的是单进程客户端

version 1.0.17
- 增加多用户模式的开关，默认关闭多用户模式；想要支持多用户模式，html页面调用一次EnableMultiUser();即可

version 1.0.18
- 关闭多用户模式时，自定义协议去掉参数serverId，兼容linux

version 1.0.19
- 对安全提示弹框的优化，用户点击取消，不再发送注册请求；多进程下不再启动客户端，直接返回

version 1.0.20
- 多进程接口兼容单进程客户端

version 1.0.21
- 给自定义协议加个标记，同一时间保证只执行一次自定义协议

version 1.0.22
- 单进程模式增加静默启动参数
- 默认采用http协议
- 多进程模式全部改为同步请求，通过前端页面来控制避免启动同时启动多个客户端
- 多进程模式支持通过标记single转为单进程模式
- 加载项发送json数据时，直接将json对象返回给前端，前端自行取用json对象里的数据
- 重新处理一下json格式错误时的容错代码
- 增加根据状态码和错误信息返回对应的json数据
- 统一sdk返回的数据格式；加载项执行成功返回{status : 0, response ： responseStr}；加载项执行失败返回{status : 1/2/3/4, message ： errorMsg}；

version 1.0.23
- 注册消息的请求直接发，不要有延时了

version 1.0.24
- publish模式不用多用户时，不要带有serverId
- 开放加载项管理disableAll接口

version 1.0.25
- 重新整理初始化sdk获取服务版本号的流程

version 1.0.26
- 注册消息的请求根据状态码直接返回
- 将msgid的判断改成undefined，处理msgid==0时直接把消息返回给html的情况

version 1.0.27
- 去掉多余的错误判断，仅在有msgId的情况下才去手动解析json数据里data的值

version 1.0.28
- 开放加载项管理接口disableall，用于卸载所有加载项
- 加载项管理相关请求去掉超时
- 加载项管理相关请求增加时间戳，避免重复请求直接返回406报错
- 单进程客户端不处理WPSInnerMessage_quit消息，继续发送注册请求
- 多用户下子进程退出会返回消息"Subserver not available."，此时执行操作会调用自定义协议启动加载项本地服务
- 用户发送json数据，统一返回给前端json字符串，不再返回json对象

version 1.0.29
- 处理serverVersion被覆盖的问题，当返回值为Subserver not available.时，不去修改serverVersion的值，减少自定义协议的弹框

version 1.0.30
- 处理asknotify收到的消息为空的场景，将判断改为data不为未定义，原判断在data未空时不会直接返回data
- 处理多进程runparams返回值为空的场景，此时会导致json解析出错；手动解析出clientId和data的值，并将data的值返回

version 1.0.31
- 多用户下加载项的返回值统一为base64编码，sdk对收到的值进行解码
- 通过服务版本号1.0.3区分是否需要进行解码；同时对之前的版本处理json解析出错的情况 - 如发空值，发字符串
- 统一参数对象为wpsclient

version 1.1.31
- 新增websocket通讯，在http多次请求失败下，采用websocket协议请求，避免高版本浏览器对本地云服务请求的安全拦截