@wecom/jssdk
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.10 • Public • Published

    @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://wwcdn.weixin.qq.com/node/open/js/wecom-jssdk-1.1.10.js"></script>
    <script>
      alert(ww.VERSION)
    </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.register({
        corpId: 'ww7ca4776b2a70000',
        jsApiList: ['selectExternalContact'],
        async getConfigSignature(url) {
          /** 根据 url 生成 config 签名 */
          return { timestamp, nonceStr, signature }
        }
      })
    • 注意:

      • 企业自建应用只需要提供 getConfigSignature
      • 对第三方应用:
        • 在企业微信 3.0.24 及以后版本中,只需要提供 getAgentConfigSignature
        • 在其他环境下,必须同时提供 getConfigSignaturegetAgentConfigSignature
      • 签名函数在页面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.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 流程。

    Keywords

    none

    Install

    npm i @wecom/jssdk

    DownloadsWeekly Downloads

    11

    Version

    1.1.10

    License

    MIT

    Unpacked Size

    452 kB

    Total Files

    79

    Last publish

    Collaborators

    • wecom-bot