微信小程序聊天工具开发指南

基础库 3.7.8+ 支持，Android/iOS 微信 8.0.56+

快速配置

app.json 配置示例

{
  "subPackages": [
    {
      "root": "packageChatTool",
      "pages": ["pages/entry/index"],
      "entry": "entry.js", // 独立分包入口文件（必须）
      "independent": true,
      "componentFramework": "glass-easel",
      "renderer": "skyline"
    }
  ],
  "chatTools": [{
    "root": "packageChatTool",
    "entryPagePath": "pages/entry/index",
    "desc": "功能描述",
    "scopes": []
  }],
  "rendererOptions": {
    "skyline": {
      "disableABTest": true,
      "defaultDisplayBlock": true,
      "defaultContentBox": true
    }
  }
}

其中 entry.js 的代码通常：

// 独立分包入口文件
// 用于聊天工具模式的初始化

const enterOptions = wx.getEnterOptionsSync()
console.log('[ChatTool Entry] Enter options:', enterOptions)

注意事项:

• 分包体积不超过 500KB
• 必须使用 skyline 渲染
• 每个小程序目前仅支持配置一个聊天工具

核心 API

进入/退出聊天模式

API	用途
wx.openChatTool	打开聊天工具模式（可传入 opengid 或 open_single_roomid）
wx.getApiCategory	判断是否在聊天工具模式（apiCategory === 'chatTool'）
wx.navigateBack	退出聊天工具模式

获取聊天信息

API	用途
wx.getChatToolInfo	在聊天工具分包内获取绑定群聊信息
wx.getGroupEnterInfo	进入前获取群聊 id 信息
wx.selectGroupMembers	选择聊天室成员，返回 group_openid

ID 类型

• opengid: 群聊唯一标识
• open_single_roomid: 单聊唯一标识
• group_openid: 用户在此聊天室下的唯一标识

发送到聊天

API	用途
wx.shareAppMessageToGroup	发送小程序卡片
wx.notifyGroupMembers	发送提醒消息（@成员 + 任务）
wx.shareImageToGroup	发送图片
wx.shareVideoToGroup	发送视频
wx.shareFileToGroup	发送文件
wx.shareEmojiToGroup	发送表情

动态消息

1. 服务端创建 activity_id
2. 前端 wx.updateShareMenu 声明动态消息
3. 服务端 setChatToolMsg 更新状态

wx.updateShareMenu({
  withShareTicket: true,
  isUpdatableMessage: true,
  activityId: "xxx",
  useForChatTool: true,
  chooseType: 1, // 1=指定成员, 2=全部成员
  participant: members,
  templateInfo: {
    templateId: "4A68CBB88A92B0A9311848DBA1E94A199B166463", // 完成类
    // 或 '2A84254B945674A2F88CE4970782C402795EB607' 参与类
  },
});

禁用能力

聊天工具模式下不支持：

• 普通转发（button open-type=share）
• 外跳接口（navigateToMiniProgram 等）
• 广告组件（ad、ad-custom）

7. 聊天工具核心API详解

wx.openChatTool

打开聊天工具。

参数

Object object

属性	类型	默认值	必填	说明
url	string		是	聊天工具分包内的页面路径
roomid	string		否	聊天室id，不传则拉起群选择框，可以传入多聊群的 opengid 值，或者单聊群的 open_single_roomid 值
chatType	number		否	群聊类型
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.chatType 合法值

值	说明
1	微信联系人单聊
2	企业微信联系人单聊
3	普通微信群聊
4	企业微信互通群聊

示例代码

wx.openChatTool({
  url: "pages/chat/index", // 示例路径
  chatType: 1, // 微信联系人单聊
  success(res) {
    console.log("打开聊天工具成功", res);
  },
  fail(err) {
    console.error("打开聊天工具失败", err);
  },
});

wx.getApiCategory

wx.getApiCategory()

基础库 2.22.1 开始支持，低版本需做 兼容处理。

获取当前小程序的 API 类别。

返回值

string

当前 API 类别。

合法值

值	说明
default	默认类别
nativeFunctionalized	原生功能化，视频号直播商品、商品橱窗等场景打开的小程序
browseOnly	仅浏览，朋友圈快照页等场景打开的小程序
embedded	内嵌，通过打开半屏小程序能力打开的小程序
chatTool	聊天工具打开小程序

示例代码

const apiCategory = wx.getApiCategory();
console.log(apiCategory);

wx.shareAppMessageToGroup

wx.shareAppMessageToGroup(Object object)

基础库 3.7.12 开始支持，低版本需做 兼容处理。

转发小程序卡片到聊天。

参数

Object object

属性	类型	默认值	必填	说明
title	string		是	转发标题
path	string	当前页面	否	转发路径，必须是以 / 开头的完整路径，默认为当前页面
imageUrl	string	截图	否	自定义图片路径，支持 PNG 及 JPG，显示图片长宽比是 5:4，默认使用截图
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.shareAppMessageToGroup({
  title: "分享标题",
  path: "/path/to/page",
  imageUrl: "",
});

wx.shareVideoToGroup

wx.shareVideoToGroup(Object object)

分享视频到聊天。

参数

Object object

属性	类型	默认值	必填	说明
videoPath	string		是	要分享的视频地址，必须为本地路径或临时路径
thumbPath	string		否	缩略图路径，若留空则使用视频首帧
needShowEntrance	boolean	true	否	分享的图片消息是否要带小程序入口
entrancePath	string	''	否	从消息小程序入口打开小程序的路径，默认为聊天工具启动路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.shareVideoToGroup({
  videoPath: "path/to/video.mp4",
  thumbPath: "path/to/thumb.png",
  needShowEntrance: true,
  success(res) {
    console.log("分享视频成功", res);
  },
  fail(err) {
    console.error("分享视频失败", err);
  },
});

wx.shareImageToGroup

wx.shareImageToGroup(Object object)

分享图片到聊天。

参数

Object object

属性	类型	默认值	必填	说明
imagePath	string		是	要分享的图片地址，必须为本地路径或临时路径
needShowEntrance	boolean	true	否	分享的图片消息是否要带小程序入口
entrancePath	string	''	否	从消息小程序入口打开小程序的路径，默认为聊天工具启动路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.shareImageToGroup({
  imagePath: "path/to/image.png",
  needShowEntrance: true,
  success(res) {
    console.log("分享图片成功", res);
  },
  fail(err) {
    console.error("分享图片失败", err);
  },
});

wx.shareEmojiToGroup

wx.shareEmojiToGroup(Object object)

分享表情到聊天。

参数

Object object

属性	类型	默认值	必填	说明
imagePath	string		是	要分享的表情地址，必须为本地路径或临时路径
needShowEntrance	boolean	true	否	分享的表情消息是否要带小程序入口
entrancePath	string	''	否	从消息小程序入口打开小程序的路径，默认为聊天工具启动路径
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.shareEmojiToGroup({
  imagePath: "path/to/image.png",
  needShowEntrance: true,
  success(res) {
    console.log("分享表情成功", res);
  },
  fail(err) {
    console.error("分享表情失败", err);
  },
});

wx.selectGroupMembers

wx.selectGroupMembers(Object object)

从群组中选择成员。

参数

Object object

属性	类型	默认值	必填	说明
maxSelectCount	number		否	最多可选人数
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

####### 参数

######## Object res

属性	类型	说明
members	Array.<string>	所选用户在此聊天室下的唯一标识，同一个用户在不同的聊天室下id不同

示例代码

wx.selectGroupMembers({
  maxSelectCount: 10,
  success(res) {
    console.log("选择成员成功", res.members);
  },
  fail(err) {
    console.error("选择成员失败", err);
  },
});

wx.notifyGroupMembers

wx.notifyGroupMembers(Object object)

发送消息提醒群成员。

参数

Object object

属性	类型	默认值	必填	说明
title	string		是	文字链标题，发送的内容将由微信拼接为：@的成员列表+“请完成：”/"请参与："+打开小程序的文字链，如「@alex @cindy 请完成：团建报名统计」。
members	Array.<string>		是	需要提醒的用户 group_openid 列表
entrancePath	string		是	文字链跳转路径
type	string	complete	否	展示的动词
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.type 合法值

值	说明
participate	请参与
complete	请完成

示例代码

wx.notifyGroupMembers({
  title: "团建报名统计",
  members: ["openid1", "openid2"],
  entrancePath: "/pages/index/index",
  type: "complete",
  success(res) {
    console.log("提醒成功", res);
  },
  fail(err) {
    console.error("提醒失败", err);
  },
});

完整文档

详见 reference.md