第三方应用开发 服务端API 会话内容存档 会话展示组件
会话展示组件
最后更新:2024/04/24
可联系渠道经理采购或代理智慧硬件接口已支持设备 联系渠道经理
会话展示组件
最后更新:2024/04/24

目录

  • 1. 背景介绍
  • 2. 使用方法
  •       2.1 环境要求
  •       2.2 准备工作
  •       2.3 开始使用
  • 3. API 说明
  •       3.1 参数说明
  •             el?: HTMLElement | string
  •             data?: unknown
  •             template: string
  •             style?: string
  •       3.2 回调方法
  •             error(error: unknown)
  •             handleModal(event: { modalUrl }): boolean | Promise<boolean>
  •             handleMounted(): void
  •             handleUpdated(): void
  •       3.3 组件方法
  •             setData(data: unknown)
  •       3.4 功能标签
  •             scroll-view
  •       3.5 模板组件
  •             ww-open-data
  •             ww-open-message
  •             ww-open-button
  •             ww-open-result-link
  •             ww-open-result-text
  •             ww-suspense
  •       3.6 模板组件错误事件
  •       3.7 Context
  •             ScrollViewContext
  • 3. 更新记录
  •       2024-04-24
  •       2024-04-01
  •       2024-02-02
  •       2024-01-09
  •       2023-12-27
  • 1. 背景介绍

    企业会话记录是企业的重要敏感数据,第三方不能直接获得授权企业的会话内容数据。第三方页面若需要展示企业的会话记录信息,可使用如下的 『会话展示组件』,以提供安全良好的体验。

    2. 使用方法

    2.1 环境要求

    企业微信 2.8.10 及以上版本。


    注意
    由于新版本 @wecom/jssdk 尚处于开发调试阶段,暂未发布到公网环境,可以暂时使用如下链接下载最新版 @wecom/jssdk 代码,放到项目中使用:
    @wecom/jssdk beta.7

    2.2 准备工作

    • 企业授权了“会话存档接口授权”后,服务商拉取到会话记录信息;
    • 准备好一个第三方应用或代开发应用,企业授权了该应用,第三方或代开发应用保证 agentConfig 签名可以正常工作;
    • 非企业微信内置浏览器中使用时,页面需要使用 Web 登录组件进行登录,必须使用企业微信登录组件方式(非构造登录链接),且使用会话展示组件的域名必须与嵌入 Web 登录组件的域名完全一致;
    • 前端项目引入 sdk:@wecom/jssdk
    • 页面 html 引入:https://open.work.weixin.qq.com/wwopen/js/jwxwork-1.0.0.js

    2.3 开始使用

    在初始化阶段,页面需要调用 @wecom/jssdk 提供的 ww.register 接口初始化应用信息:

    ww.register({
      corpId, // 必填,企业微信的corpid,必须与当前登录的企业一致
      agentId, // 必填,企业授权了第三方应用或代开发应用后的应用id (e.g. 1000247)
      jsApiList,
      async getAgentConfigSignature() {
        // 获取并返回 agentConfig 签名信息
      }
    })
    
    // 会话组件需要确保 WWOpenData 初始化成功
    await ww.initOpenData();

    其中 jsApiList 需要在页面现有 JSAPI 列表的基础上增加 wwapp.invokeJsApiByCallInfo

    jsApiList = [
      'selectExternalContact',
      'shareAppMessage',
      'wwapp.invokeJsApiByCallInfo' // <- Add this
    ]

    初始化完成后,创建“展示组件工厂”对象备用:

    const factory = ww.createOpenDataFrameFactory()

    在需要展示会话记录数据时,调用 factory.createOpenDataFrame 函数创建展示组件:

    const msgList = [
      {
        msgid,    // 消息 ID
        secretKey // 消息密钥
      }
    ]
    
    const instance = factory.createOpenDataFrame({
      el: containerElement, // “容器”元素,用于挂载展示组件
      template: `
        <view
          wx:for="{{data.msgList}}"
          wx:key="msgid"
          class="msg"
          data-index="{{index}}"
          bindclick="handleClickEvent"
        >
          <ww-open-message
            message-id="{{item.msgid}}"
            secret-key="{{item.secretKey}}"
            open-type="viewMessage"
          />
        </view>
      `,
      style: `
        .msg {
          height: 100%;
          overflow: auto;
        }
      `,
      data: {
        msgList
      },
      methods: {
        handleClickEvent() {
          // 响应消息点击事件
          instance.setData({
            msgList: newMsgList
          })
        }
      }
    })

    组件会在容器元素内展示指定的消息数据。

    3. API 说明

    3.1 参数说明

    el?: HTMLElement | string

    组件容器,可以是实际的 DOM 元素或 CSS 选择器字符串。

    data?: unknown

    组件自定义数据,可以在模板中访问。

    template: string

    组件模板,用于自定义组件内的展示内容。语法参考 WXML。目前支持以下组件:

    • block
    • view
    • scroll-view
    • span
    • image
    • checkbox
    • ww-open-data
    • ww-open-message
    • ww-open-button
    • ww-open-result-link
    • ww-open-result-text
    • ww-suspense

    style?: string

    组件模板样式表,语法是 CSS 的子集,目前仅支持以下语法:

    • Class Selector
    • Pseudo
    • @media
    • @supports
    • @font-face
    • @page
    • @keyframes
    • @counter-style

    其他限制

    • ww- 开头的类名为企业微信预留,无法修改样式
    • 一个选择器组内需要至少包含一个类选择器,如 span.example

    3.2 回调方法

    error(error: unknown)

    错误回调。

    handleModal(event: { modalUrl }): boolean | Promise<boolean>

    调起模态框回调,当用户点击需要预览的消息时触发。开发者可以根据场景手动创建预览 iframe 展示消息内容。

    在企业微信内置浏览器环境下,展示组件默认会打开新窗口展示消息内容。

    参数

    • modalUrl: string
      预览 URL,在 iframe 中加载可以展示预览内容

    返回

    当返回 false 时表示阻止展示组件处理预览事件。

    示例代码

    /**
     * 创建 modal iframe、设置 src 并添加到 document.body
     */
    handleModal({ modalUrl }) {
      const iframe = document.createElement('iframe')
      iframe.src = modalUrl
      iframe.className = 'modal'
      document.body.appendChild(iframe)
    }

    handleMounted(): void

    视图挂载成功后的回调。

    handleUpdated(): void

    视图更新成功后的回调。

    3.3 组件方法

    setData(data: unknown)

    更新组件自定义数据,支持通过对象路径设置深层数据:

    instance.setData({
      key: 'value',
      'data.path["computed member"][1]': 'deepValue'
    })
    /**
     * result:
     *
     * {
     *   key: 'value',
     *   data: {
     *     path: {
     *       'computed member': [
     *         ,
     *         'deepValue'
     *       ]
     *     }
     *   }
     * }
     */

    3.4 功能标签

    scroll-view

    可滚动视图区域。可以通过 ScrollViewContext 操作滚动条。

    参数说明

    参数类型默认值必填说明
    scroll-xbooleanfalse是否允许横向滚动
    scroll-ybooleanfalse是否允许纵向滚动
    upper-thresholdnumber50距顶部/左边多远时(单位px),触发 scrolltoupper 事件
    lower-thresholdnumber50距底部/右边多远时(单位px),触发 scrolltolower 事件
    scroll-topnumber0设置竖向滚动条位置
    scroll-leftnumber0设置横向滚动条位置
    scroll-with-animationbooleanfalse在设置滚动条位置时使用动画过渡

    事件说明

    事件名称说明event.detail
    bindscrolltoupper滚动到顶部/左边时触发
    bindscrolltolower滚动到底部/右边时触发
    bindscroll滚动时触发{ scrollTop, scrollLeft, scrollHeight, scrollWidth }

    模板示例

    <scroll-view
      scroll-y="{{true}}"
      scroll-top="{{data.scrollTop}}"
      scroll-with-animation="{{true}}"
      bindscrolltoupper="onScrollUpper"
      bindscrolltolower="onScrollLower"
      bindscroll="onScroll"
    >
      <view class="title">员工列表</view>
      ...
    </scroll-view>

    3.5 模板组件

     

    ww-open-data

    展示单个名称。

    参数说明

    参数类型默认值必填说明
    typestring名称类型,可选值:userName,chatName
    openidstring名称对应的 id,当 type 为 userName 时,对应 openUserid;当 type 为 chatName 时,对应 chatid

    更多 type 与 openid 组合,详情参考下表:

    typeopenid说明
    userNameopenUserid企业用户名称
    userAvataropenUserid企业用户头像
    externalUserName若是企业客户填:externalUserId
    若是客户群的外部成员填:chatid/externalUserId,例如:wraaaabbbb/wmccccdddd
    客户名称
    externalUserAvatar若是企业客户填:externalUserId
    若是客户群的外部成员填:chatid/externalUserId,例如:wraaaabbbb/wmccccdddd
    客户头像
    chatNamechatid内部群或客户群名

    自定义头像样式

    <ww-open-data type="userAvatar" id="test" class="user-avatar" />
    .user-avatar {
    	width: 64px;
    	height: 64px;
    	border-radius: 4px;
    }

    ww-open-message

    展示会话消息内容。

    参数说明

    参数类型默认值必填说明
    message-idstring消息 ID
    secret-keystring消息密钥,对会话记录中的 encrypted_secretkey 字段进行解密得到,参考 encrypt_secretkey 解密方式
    highlight-textstring需要高亮的文本
    highlight-colorstring高亮文本的 color,用于自定义高亮文本的字体颜色, e.g. #267EF0

    open-type

    open-type说明
    viewMessage当用户点击消息时,打开新窗口预览消息内容

    支持高亮文本的消息类型

    • 文本消息
    • 链接消息 - 标题
    • 小程序消息 - 标题
    • 在线文档消息 - 文档名称
    • 微盘文件消息 - 文件名称
    • 混合消息 - 文本部分

     

    ww-open-button

    业务授权按钮。

    参数说明

    参数类型默认值必填说明
    open-typestring业务类型:getExportCode

    事件说明

    事件名称说明event.detail
    bindgetexportcodeopen-type 为 getExportCode 时,用户点击后,会触发回调{ exportCode }

    示例代码

    <ww-open-button open-type="getExportCode" bindgetexportcode="onExportCodeReady">点击授权</ww-open-button>
    onExportCodeReady(event) {
    	console.log(event.detail.exportCode);
    }

     

    ww-open-result-link

    以链接形式展示异步任务结果。

    参数类型默认值必填说明
    result-idstring异步任务结果 ID

     

    ww-open-result-text

    以文本形式展示异步任务结果。

    参数类型默认值必填说明
    result-idstring异步任务结果 ID
    secret-keystring异步任务结果解密 key
    encrypt-info(已废弃,后续不再使用)object异步任务结果解密信息

    encrypt-info @deprecated

    {
    	"secret_key": "" // 异步任务解密密钥
    }

     

    ww-suspense

    用于 ww-open-dataww-open-messageww-open-result-linkww-open-result-text 在加载数据过程中,提供 fallback 渲染的能力。与 React 的 Suspense 功能类似。

    示例代码

    <ww-suspense>
      <ww-open-message message-id="{{data.msgid}}" secret-key="{{data.secret_key}}" />
      <block wx:slot="fallback">
        <view class="msgCnt-fallback">消息内容正在加载...</view>
      </block>
    </ww-suspense>

    3.6 模板组件错误事件

    模板组件有统一的错误事件回调方式 binderror,通过监听错误事件,开发者可以判断组件的工作状态。

    示例代码

    <ww-open-message message-id="{{item.msgid}}" secret-key="{{item.encrypt_info.secret_key}}" binderror="onOpenMsgError" />
    factory.createOpenDataFrame({
    	...
    	methods: {
    		...
    		onOpenMsgError(event) {
    			console.warn('open message error: ', event);
    		},
    	},
    });

     

    3.7 Context

    ScrollViewContext

    增强 scroll-view 实例,可以通过 ww.createScrollViewContext 接口获取。

    方法

    ScrollViewContext.scrollTo(options: { top?: number; left?: number })

    滚动至指定位置。

    options 参数说明:
    top:垂直位置,单位:像素;
    left:水平位置,单位:像素;

    ScrollViewContext.scrollIntoView(selector: string, options?: { block?: string; inline?: string })

    滚动至指定位置。

    options 参数说明:
    block:定义垂直方向的对齐,可选值有:start | center | end | nearest
    inline:定义水平方向的对齐,可选值有:start | center | end | nearest

    示例代码

    <scroll-view ref="refName">...</scroll-view>
    const scrollViewContext = await ww.createScrollViewContext(instance, 'refName')
    
    scrollViewContext.scrollTo({ top: 100 })

    3. 更新记录

    2024-04-24

    • 新增 handleUpdated 回调

    2024-04-01

    • @wecom/jssdk 更新至 v1.5.0-beta.6
    • 更新 ScrollViewContext.scrollIntoView 接口说明
    • 更新 ww-open-data 参数说明

    2024-02-02

    • @wecom/jssdk 更新至 v1.5.0-beta.5
    • 补充 handleMounted 接口
    • 补充 ww-suspense 说明
    • 补充 ww-open-result-linkww-open-result-text 组件说明

    2024-01-09

    • @wecom/jssdk 更新至 v1.5.0-beta.4
    • 补充 ScrollViewContext 说明
    • 补充 API 参数类型说明

    2023-12-27

    • 更新 @wecom/jssdk 依赖包
    • 新增 handleModal 回调
    • 补充 API 参数说明
    • 补充外部浏览器支持说明
    上一篇
    收费方案
    下一篇
    获取授权存档的成员列表