jwecom
微信(企业微信)JSSDK,可用于替代 jweixin.js。
主要特性
- 自动调用 config、agentConfig
- API promise 化
- 提供 ts 定义
- 通过 npm 发布
使用方法
通过 npm 引入:
// 注册应用信息ww // 可以立刻调用JS接口,无需等待ready回调ww
通过 script 标签引入:
API
常规接口可参考以下文档:
所有命令接口均已 promise 化,具体用法请参考 ts 定义。
ww.register(options)
-
参数:
{Object} options
注册参数
-
说明:
注册应用信息,在调用其他JS接口前必须先调用该接口。
在注册应用信息后,SDK会在需要的时候自动调用
wx.config
,此时SDK会通过getConfigSignature
等回调函数获取签名信息。 -
options 结构:
属性 类型 默认值 必填 说明 corpId string 是 当前用户所属企业ID(或公众号的 appId) agentId number / string 否 企业微信第三方应用的AgentID jsApiList Array<string> [ "config" ] 否 需要使用的JS接口列表 getConfigSignature Function 否 config 签名生成函数,详见后续说明 getAgentConfigSignature Function 否 agentConfig 签名生成函数,详见后续说明 openTagList Array<string> 否 需要使用的开放标签列表,例如 [ "wx-open-launch-app" ] onConfigSuccess Function 否 config 成功回调 onConfigFail Function 否 config 失败回调 onConfigComplete Function 否 config 完成回调 onAgentConfigSuccess Function 否 agentConfig 成功回调 onAgentConfigFail Function 否 agentConfig 失败回调 onAgentConfigComplete Function 否 agentConfig 完成回调 -
getConfigSignature、getAgentConfigSignature 返回结构:
属性 类型 必填 说明 timestamp number / string 是 生成签名的时间戳 nonceStr string 是 生成签名的随机串 signature string 是 签名,生成方法见 JS-SDK使用权限签名算法 -
示例代码:
ww -
注意:
- 企业自建应用只需要提供
getConfigSignature
- 对第三方应用:
- 在企业微信 3.0.24 及以后版本中,只需要提供
getAgentConfigSignature
- 在其他环境下,必须同时提供
getConfigSignature
和getAgentConfigSignature
- 在企业微信 3.0.24 及以后版本中,只需要提供
- 签名函数在页面URL发生变更后需要重新调用,对使用哈希路由的单页应用,签名函数只会被调用一次
- 企业自建应用只需要提供
ww.initOpenData([options])
注意:使用通讯录组件前仍需在页面上引入 https://open.work.weixin.qq.com/wwopen/js/jwxwork-1.0.0.js
-
参数:
{Object} [options]
通用回调参数
-
返回值:
Promise<Object>
结构同 wx.agentConfig -
说明:
初始化企业微信通讯录组件。在该接口返回成功后,可以直接调用
WWOpenData.bind
等方法。 -
options 结构:
属性 类型 默认值 必填 说明 success Function 否 成功回调 fail Function 否 失败回调 complete Function 否 完成回调
ww.getSignature(options)
注意:该接口仅用于本地调试,请勿在线上版本中使用
-
参数:
{Object} options
用于生成签名的参数,也可以直接传入 jsapi ticket
-
返回值:
{Object} result
签名结果 -
说明:
根据提供的参数生成签名。若只传入
ticket
参数,则默认为当前页面生成签名。 -
options 结构:
属性 类型 默认值 必填 说明 ticket string 是 用于签名的 JSAPI Ticket nonceStr string 随机生成 否 生成签名的随机串 timestamp number 取当前时间 否 生成签名的时间戳 url string 取当前页面URL 否 生成签名的URL -
result 结构:
属性 类型 说明 nonceStr string 生成签名的随机串 timestamp number 生成签名的时间戳 signature string 签名 -
示例代码:
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!// 该代码仅用于本地调试,请勿在生产环境对外暴露 JSAPI_TICKET// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!const JSAPI_TICKET = 'sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg'ww
ww.on(name, callback)
-
参数:
{string} name
监听的事件名称{Function} callback
事件回调函数
-
返回值:
Promise<void>
成功监听后返回 -
说明:
等待 WeixinJSBridgeReady 后调用
WeixinJSBridge.on
。用于监听 SDK 没有定义的事件。
ww.invoke(name, [params, [callback]])
-
参数:
{string} name
调用的接口名称{Object} [params]
接口传入参数{Function} [callback]
回调函数
-
返回值:
Promise<unknown>
-
说明:
等待 WeixinJSBridgeReady 后调用
WeixinJSBridge.invoke
。用于调用 SDK 没有定义的接口。
ww.onWeixinJSBridgeReady()
-
返回值:
Promise<void>
-
说明:
等待 WeixinJSBridge 注入完成。
ww.isWeixinJSBridgeReady
-
类型:
boolean
-
说明:
当前 WeixinJSBridge 是否已注入。
ww.ensureConfigReady()
-
返回值:
Promise<void>
-
说明:
根据当前环境检查 config 或 agentConfig 的状态。若 config 状态已失效(url 发生变更),会重新触发 config 流程。