会话展示组件 - 文档 - 企业微信开发者中心

准备好一个自建应用或者第三方应用或代开发应用（企业需授权“使用会话展示组件”权限），应用保证 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 或 企业授权了第三方应用或代开发应用后的应用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
ww-open-data-export-button

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-x	boolean	false	否	是否允许横向滚动
scroll-y	boolean	false	否	是否允许纵向滚动
upper-threshold	number	50	否	距顶部/左边多远时（单位px），触发 scrolltoupper 事件
lower-threshold	number	50	否	距底部/右边多远时（单位px），触发 scrolltolower 事件
scroll-top	number	0	否	设置竖向滚动条位置
scroll-left	number	0	否	设置横向滚动条位置
scroll-with-animation	boolean	false	否	在设置滚动条位置时使用动画过渡

事件说明

事件名称	说明	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`

展示单个名称。

参数说明

参数	类型	默认值	必填	说明
type	string		是	名称类型，可选值：userName，chatName
openid	string		是	名称对应的 id，当 type 为 userName 时，对应 openUserid；当 type 为 chatName 时，对应 chatid

更多 type 与 openid 组合，详情参考下表：

type	openid	说明
userName	openUserid	企业用户名称
userAvatar	openUserid	企业用户头像
externalUserName	若是企业客户填：externalUserId 若是客户群的外部成员填：chatid/externalUserId，例如：wraaaabbbb/wmccccdddd	客户名称
externalUserAvatar	若是企业客户填：externalUserId 若是客户群的外部成员填：chatid/externalUserId，例如：wraaaabbbb/wmccccdddd	客户头像
chatName	chatid	内部群或客户群名

自定义头像样式

<ww-open-data type="userAvatar" id="test" class="user-avatar" />

.user-avatar {
	width: 64px;
	height: 64px;
	border-radius: 4px;
}

`ww-open-message`

展示会话消息内容。

参数说明

参数	类型	必填	说明
message-id	string	是	消息 ID
secret-key	string	是	消息密钥，对会话记录中的 encrypted_secretkey 字段进行解密得到，参考 encrypt_secretkey 解密方式
highlight-text	string	否	需要高亮的文本，文本会由企业微信后台进行智能分词处理
static-highlight-text-list	string[]	否	需要高亮的静态文本列表，不会进行智能分词处理，如果存在 `highlight-text`，最终高亮表现以 `hightlight-text` 为准
highlight-color	string	否	高亮文本的 `color`，用于自定义高亮文本的字体颜色, e.g. `#267EF0`

open-type

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

支持高亮文本的消息类型

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

`ww-open-button`

业务授权按钮。

参数说明

参数	类型	默认值	必填	说明
open-type	string		是	业务类型：`getExportCode`

事件说明

事件名称	说明	event.detail
bindgetexportcode	open-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-id	string	是	异步任务结果 ID
message-id	string	是	消息密钥（与 result 结果相关的任一消息）
secret-key	string	是	消息密钥（与 message-id 配对一致的 secret-key）

`ww-open-result-text`

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

参数	类型	必填	说明
result-id	string	是	异步任务结果 ID
secret-key	string	是	异步任务结果解密 key
encrypt-info（已废弃，后续不再使用）	object	否	异步任务结果解密信息

encrypt-info @deprecated

{
	"secret_key": ""
}

`ww-suspense`

用于 ww-open-data、ww-open-message、ww-open-result-link、ww-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>

`ww-open-data-export-button`

导出包含人名部门名的文件。

关于文件下载 url：先调用“异步通讯录id转译”接口提交转译任务，然后通过“获取异步任务结果”获取最终下载文件的url，注意该url仅能在有用户登录态的浏览器打开以下载文件，详情参见“通讯录ID转译”。

@wecom/jssdk 版本要求：2.1.0 及以上版本。

参数说明

参数	类型	默认值	必填	说明
href	string		是	文件下载 url

模板示例

<ww-open-data-export-button
	class="export-button"
	href="{{data.fileUrl}}"
	binderror="onExportError"
>
	点击下载文件
</ww-open-data-export-button>

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 })

滚动至指定位置。

示例代码

<scroll-view ref="refName">...</scroll-view>

const scrollViewContext = await ww.createScrollViewContext(instance, 'refName')

scrollViewContext.scrollTo({ top: 100 })

3. 错误处理

登录态过期或者异常

用户在使用过程中，常见的异常状态为 “当前登录态过期”，此时需要服务商引导用户重新进行扫码登录。

“登录态异常”的出现时机以及对应特征如下：

使用 ww-xxx 组件过程，登录态失效出错

错误事件会在 ww-xxx 组件的 binderror 回调中返回，有如下错误特征：

组件初始化过程中，判定当前登录态过期，detail.errCode 为 42006：
组件获取数据时判定登录态过期，detail.errCode 为 42003 或者 40029：
浏览器判断登录过期后自动删除票据，detail.errMsg 为 “Missing open sid”：

4. 推荐用法

列表中展示会话组件

如下图，如果想在列表中渲染会话组件，强烈建议将整个列表放到 OpenDataFrame 里面实现，而不是每一行或者每一个表格都用独立的 OpenDataFrame 展示。

在列表中进行多个 OpenDataFrame 单独渲染，会增加区域中的白屏时间，同时会触发多次校验请求，若过于频繁，会触发企业微信后台的安全频率限制，导致渲染失败。

推荐用法：整个绿框区域使用 OpenDataFrame 实现；
不推荐用法：红框区域每行数据使用多个 OpenDataFrame 实现；

FAQ

会话组件 ww-open-message 渲染视频后，在外部浏览器无法点击预览
解答：外部浏览器下，如果要在会话组件上点击预览 “图片”、“视频”、“聊天记录详情”，需要服务商开发者通过 handleModal 回调实现预览表现，请仔细参考文档中 handleModal 回调的具体说明。