@wecom/jssdk

微信（企业微信）JSSDK，可用于替代 jweixin.js。

主要特性

1. 自动调用 config、agentConfig
2. API promise 化
3. 提供 ts 定义
4. 通过 npm 发布

使用方法

通过 npm 引入：

import * as ww from '@wecom/jssdk'

// 注册应用信息
ww.register({
  corpId: 'ww7ca4776b2a70000',
  jsApiList: [
    'selectExternalContact',
  ],
  async getConfigSignature(url) {
    // 根据 url 生成 config 签名信息（需要开发者自行实现）
    // 返回 { timestamp, nonceStr, signature }
    return getJsApiSignature(url)
  }
})

// 可以立刻调用JS接口，无需等待ready回调
ww.selectExternalContact({
  success(res) {
    console.log(res.userIds[0])
  }
})

通过 script 标签引入：

<script src="https://unpkg.com/@wecom/jssdk"></script>
<script>
  alert(ww.SDK_VERSION)
</script>

API

常规接口可参考以下文档：

• 企业微信 JS-SDK 文档
• 微信 JS-SDK 说明文档

所有命令接口均已 promise 化，具体用法请参考 ts 定义。

ww.register(options)

• 参数：
• {Object} options 注册参数
• 说明：

注册应用信息，在调用其他JS接口前必须先调用该接口。

在注册应用信息后，SDK会在需要的时候自动调用 wx.config，此时SDK会通过 getConfigSignature 等回调函数获取签名信息。

• options 结构：

• getConfigSignature、getAgentConfigSignature 返回结构：

• 示例代码：

js ww.register({ corpId: 'ww7ca4776b2a70000', jsApiList: ['selectExternalContact'], async getConfigSignature(url) { /** * 根据 url 生成 config 签名 */ return { timestamp, nonceStr, signature } } })

• 注意：

• 企业自建应用只需要提供 getConfigSignature

• 对第三方应用：
  • 在企业微信 3.0.24 及以后版本中，只需要提供 getAgentConfigSignature
  • 在其他环境下，必须同时提供 getConfigSignature 和 getAgentConfigSignature
• 签名函数在页面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 结构：

ww.getSignature(options)

注意：该接口仅用于本地调试，请勿在线上版本中使用

• 参数：
• {Object} options 用于生成签名的参数，也可以直接传入 jsapi ticket
• 返回值： {Object} result 签名结果
• 说明：

根据提供的参数生成签名。若只传入 ticket 参数，则默认为当前页面生成签名。

• options 结构：

• result 结构：

• 示例代码：

```js
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// 该代码仅用于本地调试，请勿在生产环境对外暴露 JSAPI_TICKET
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
const JSAPI_TICKET = 'sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg'

ww.register({
corpId: 'ww7ca4776b2a70000',
jsApiList: ['selectExternalContact'],
getConfigSignature(url) {
return ww.getSignature(JSAPI_TICKET)
}
})
```

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 流程。