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

基础库 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

进入/退出聊天模式

获取聊天信息

ID 类型

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

发送到聊天

动态消息

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

object.chatType 合法值

示例代码

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 类别。

合法值

示例代码

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

wx.shareAppMessageToGroup

wx.shareAppMessageToGroup(Object object)

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

转发小程序卡片到聊天。

参数

Object object

示例代码

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

wx.shareVideoToGroup

wx.shareVideoToGroup(Object object)

分享视频到聊天。

参数

Object object

示例代码

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

示例代码

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

示例代码

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

object.success 回调函数

####### 参数

######## Object res

示例代码

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

wx.notifyGroupMembers

wx.notifyGroupMembers(Object object)

发送消息提醒群成员。

参数

Object object

object.type 合法值

示例代码

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

完整文档

详见 reference.md