wechat-chat-tool
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese微信小程序聊天工具开发指南
WeChat Mini Program Chat Tool Development Guide
基础库 3.7.8+ 支持,Android/iOS 微信 8.0.56+
Supported on Base Library 3.7.8+, WeChat 8.0.56+ for Android/iOS
快速配置
Quick Configuration
app.json 配置示例
app.json Configuration Example
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 渲染
- 每个小程序目前仅支持配置一个聊天工具
json
{
"subPackages": [
{
"root": "packageChatTool",
"pages": ["pages/entry/index"],
"entry": "entry.js", // Independent subpackage entry file (required)
"independent": true,
"componentFramework": "glass-easel",
"renderer": "skyline"
}
],
"chatTools": [{
"root": "packageChatTool",
"entryPagePath": "pages/entry/index",
"desc": "Function Description",
"scopes": []
}],
"rendererOptions": {
"skyline": {
"disableABTest": true,
"defaultDisplayBlock": true,
"defaultContentBox": true
}
}
}The typical code for :
entry.js// Independent subpackage entry file
// Used for initialization in chat tool mode
const enterOptions = wx.getEnterOptionsSync()
console.log('[ChatTool Entry] Enter options:', enterOptions)Notes:
- Subpackage size should not exceed 500KB
- Must use skyline renderer
- Each Mini Program currently supports only one chat tool configuration
核心 API
Core APIs
进入/退出聊天模式
Enter/Exit Chat Mode
| API | 用途 |
|---|---|
| 打开聊天工具模式(可传入 opengid 或 open_single_roomid) |
| 判断是否在聊天工具模式(apiCategory === 'chatTool') |
| 退出聊天工具模式 |
| API | Purpose |
|---|---|
| Open chat tool mode (can pass opengid or open_single_roomid) |
| Determine if in chat tool mode (apiCategory === 'chatTool') |
| Exit chat tool mode |
获取聊天信息
Obtain Chat Information
| API | 用途 |
|---|---|
| 在聊天工具分包内获取绑定群聊信息 |
| 进入前获取群聊 id 信息 |
| 选择聊天室成员,返回 group_openid |
| API | Purpose |
|---|---|
| Obtain bound group chat information within chat tool subpackage |
| Obtain group chat id information before entering |
| Select chat room members, return group_openid |
ID 类型
ID Types
- : 群聊唯一标识
opengid - : 单聊唯一标识
open_single_roomid - : 用户在此聊天室下的唯一标识
group_openid
- : Unique identifier for group chats
opengid - : Unique identifier for one-on-one chats
open_single_roomid - : Unique identifier for a user in a specific chat room
group_openid
发送到聊天
Send to Chat
| API | 用途 |
|---|---|
| 发送小程序卡片 |
| 发送提醒消息(@成员 + 任务) |
| 发送图片 |
| 发送视频 |
| 发送文件 |
| 发送表情 |
| API | Purpose |
|---|---|
| Send Mini Program card |
| Send reminder messages (@members + tasks) |
| Send images |
| Send videos |
| Send files |
| Send emojis |
动态消息
Dynamic Messages
- 服务端创建
activity_id - 前端 声明动态消息
wx.updateShareMenu - 服务端 更新状态
setChatToolMsg
javascript
wx.updateShareMenu({
withShareTicket: true,
isUpdatableMessage: true,
activityId: "xxx",
useForChatTool: true,
chooseType: 1, // 1=指定成员, 2=全部成员
participant: members,
templateInfo: {
templateId: "4A68CBB88A92B0A9311848DBA1E94A199B166463", // 完成类
// 或 '2A84254B945674A2F88CE4970782C402795EB607' 参与类
},
});- Server creates
activity_id - Frontend uses to declare dynamic messages
wx.updateShareMenu - Server uses to update status
setChatToolMsg
javascript
wx.updateShareMenu({
withShareTicket: true,
isUpdatableMessage: true,
activityId: "xxx",
useForChatTool: true,
chooseType: 1, // 1=specified members, 2=all members
participant: members,
templateInfo: {
templateId: "4A68CBB88A92B0A9311848DBA1E94A199B166463", // Completion type
// or '2A84254B945674A2F88CE4970782C402795EB607' Participation type
},
});禁用能力
Disabled Capabilities
聊天工具模式下不支持:
- 普通转发(button open-type=share)
- 外跳接口(navigateToMiniProgram 等)
- 广告组件(ad、ad-custom)
The following are not supported in chat tool mode:
- Ordinary forwarding (button open-type=share)
- External jump interfaces (navigateToMiniProgram, etc.)
- Ad components (ad, ad-custom)
7. 聊天工具核心API详解
7. Detailed Explanation of Core Chat Tool APIs
wx.openChatTool
wx.openChatTool
打开聊天工具。
Open chat tool.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| url | string | 是 | 聊天工具分包内的页面路径 | |
| roomid | string | 否 | 聊天室id,不传则拉起群选择框,可以传入多聊群的 opengid 值,或者单聊群的 open_single_roomid 值 | |
| chatType | number | 否 | 群聊类型 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| url | string | Yes | Page path within the chat tool subpackage | |
| roomid | string | No | Chat room id, if not passed, group selection box will pop up; can pass opengid of multi-person group chat or open_single_roomid of one-on-one chat | |
| chatType | number | No | Group chat type | |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
object.chatType 合法值
Valid Values for object.chatType
| 值 | 说明 |
|---|---|
| 1 | 微信联系人单聊 |
| 2 | 企业微信联系人单聊 |
| 3 | 普通微信群聊 |
| 4 | 企业微信互通群聊 |
| Value | Description |
|---|---|
| 1 | WeChat contact one-on-one chat |
| 2 | WeChat Work contact one-on-one chat |
| 3 | Ordinary WeChat group chat |
| 4 | WeChat Work interoperable group chat |
示例代码
Example Code
javascript
wx.openChatTool({
url: "pages/chat/index", // 示例路径
chatType: 1, // 微信联系人单聊
success(res) {
console.log("打开聊天工具成功", res);
},
fail(err) {
console.error("打开聊天工具失败", err);
},
});javascript
wx.openChatTool({
url: "pages/chat/index", // Example path
chatType: 1, // WeChat contact one-on-one chat
success(res) {
console.log("Open chat tool successfully", res);
},
fail(err) {
console.error("Failed to open chat tool", err);
},
});wx.getApiCategory
wx.getApiCategory
wx.getApiCategory()
wx.getApiCategory()
基础库 2.22.1 开始支持,低版本需做 兼容处理。
获取当前小程序的 API 类别。
Supported since Base Library 2.22.1, need to do compatibility handling for lower versions.
Obtain the API category of the current Mini Program.
返回值
Return Value
string
string
当前 API 类别。
合法值
| 值 | 说明 |
|---|---|
| default | 默认类别 |
| nativeFunctionalized | 原生功能化,视频号直播商品、商品橱窗等场景打开的小程序 |
| browseOnly | 仅浏览,朋友圈快照页等场景打开的小程序 |
| embedded | 内嵌,通过打开半屏小程序能力打开的小程序 |
| chatTool | 聊天工具打开小程序 |
Current API category.
Valid Values
| Value | Description |
|---|---|
| default | Default category |
| nativeFunctionalized | Native functionalization, Mini Programs opened in scenarios like Video号 live goods, product showcase, etc |
| browseOnly | Browse only, Mini Programs opened in scenarios like Moments snapshot pages |
| embedded | Embedded, Mini Programs opened via half-screen Mini Program capability |
| chatTool | Mini Program opened via chat tool |
示例代码
Example Code
javascript
const apiCategory = wx.getApiCategory();
console.log(apiCategory);javascript
const apiCategory = wx.getApiCategory();
console.log(apiCategory);wx.shareAppMessageToGroup
wx.shareAppMessageToGroup
wx.shareAppMessageToGroup(Object object)
wx.shareAppMessageToGroup(Object object)
基础库 3.7.12 开始支持,低版本需做 兼容处理。
转发小程序卡片到聊天。
Supported since Base Library 3.7.12, need to do compatibility handling for lower versions.
Forward Mini Program card to chat.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| title | string | 是 | 转发标题 | |
| path | string | 当前页面 | 否 | 转发路径,必须是以 / 开头的完整路径,默认为当前页面 |
| imageUrl | string | 截图 | 否 | 自定义图片路径,支持 PNG 及 JPG,显示图片长宽比是 5:4,默认使用截图 |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| title | string | Yes | Forwarding title | |
| path | string | Current page | No | Forwarding path, must be a complete path starting with /, defaults to current page |
| imageUrl | string | Screenshot | No | Custom image path, supports PNG and JPG; aspect ratio of displayed image is 5:4, defaults to screenshot |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
示例代码
Example Code
javascript
wx.shareAppMessageToGroup({
title: "分享标题",
path: "/path/to/page",
imageUrl: "",
});javascript
wx.shareAppMessageToGroup({
title: "Share Title",
path: "/path/to/page",
imageUrl: "",
});wx.shareVideoToGroup
wx.shareVideoToGroup
wx.shareVideoToGroup(Object object)
wx.shareVideoToGroup(Object object)
分享视频到聊天。
Share video to chat.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| videoPath | string | 是 | 要分享的视频地址,必须为本地路径或临时路径 | |
| thumbPath | string | 否 | 缩略图路径,若留空则使用视频首帧 | |
| needShowEntrance | boolean | true | 否 | 分享的图片消息是否要带小程序入口 |
| entrancePath | string | '' | 否 | 从消息小程序入口打开小程序的路径,默认为聊天工具启动路径 |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| videoPath | string | Yes | Path of the video to share, must be local or temporary path | |
| thumbPath | string | No | Thumbnail path; if left blank, the first frame of the video will be used | |
| needShowEntrance | boolean | true | No | Whether to show Mini Program entrance in the shared image message |
| entrancePath | string | '' | No | Path to open Mini Program from message entrance, defaults to chat tool startup path |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
示例代码
Example Code
javascript
wx.shareVideoToGroup({
videoPath: "path/to/video.mp4",
thumbPath: "path/to/thumb.png",
needShowEntrance: true,
success(res) {
console.log("分享视频成功", res);
},
fail(err) {
console.error("分享视频失败", err);
},
});javascript
wx.shareVideoToGroup({
videoPath: "path/to/video.mp4",
thumbPath: "path/to/thumb.png",
needShowEntrance: true,
success(res) {
console.log("Share video successfully", res);
},
fail(err) {
console.error("Failed to share video", err);
},
});wx.shareImageToGroup
wx.shareImageToGroup
wx.shareImageToGroup(Object object)
wx.shareImageToGroup(Object object)
分享图片到聊天。
Share image to chat.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| imagePath | string | 是 | 要分享的图片地址,必须为本地路径或临时路径 | |
| needShowEntrance | boolean | true | 否 | 分享的图片消息是否要带小程序入口 |
| entrancePath | string | '' | 否 | 从消息小程序入口打开小程序的路径,默认为聊天工具启动路径 |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| imagePath | string | Yes | Path of the image to share, must be local or temporary path | |
| needShowEntrance | boolean | true | No | Whether to show Mini Program entrance in the shared image message |
| entrancePath | string | '' | No | Path to open Mini Program from message entrance, defaults to chat tool startup path |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
示例代码
Example Code
javascript
wx.shareImageToGroup({
imagePath: "path/to/image.png",
needShowEntrance: true,
success(res) {
console.log("分享图片成功", res);
},
fail(err) {
console.error("分享图片失败", err);
},
});javascript
wx.shareImageToGroup({
imagePath: "path/to/image.png",
needShowEntrance: true,
success(res) {
console.log("Share image successfully", res);
},
fail(err) {
console.error("Failed to share image", err);
},
});wx.shareEmojiToGroup
wx.shareEmojiToGroup
wx.shareEmojiToGroup(Object object)
wx.shareEmojiToGroup(Object object)
分享表情到聊天。
Share emoji to chat.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| imagePath | string | 是 | 要分享的表情地址,必须为本地路径或临时路径 | |
| needShowEntrance | boolean | true | 否 | 分享的表情消息是否要带小程序入口 |
| entrancePath | string | '' | 否 | 从消息小程序入口打开小程序的路径,默认为聊天工具启动路径 |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| imagePath | string | Yes | Path of the emoji to share, must be local or temporary path | |
| needShowEntrance | boolean | true | No | Whether to show Mini Program entrance in the shared emoji message |
| entrancePath | string | '' | No | Path to open Mini Program from message entrance, defaults to chat tool startup path |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
示例代码
Example Code
javascript
wx.shareEmojiToGroup({
imagePath: "path/to/image.png",
needShowEntrance: true,
success(res) {
console.log("分享表情成功", res);
},
fail(err) {
console.error("分享表情失败", err);
},
});javascript
wx.shareEmojiToGroup({
imagePath: "path/to/image.png",
needShowEntrance: true,
success(res) {
console.log("Share emoji successfully", res);
},
fail(err) {
console.error("Failed to share emoji", err);
},
});wx.selectGroupMembers
wx.selectGroupMembers
wx.selectGroupMembers(Object object)
wx.selectGroupMembers(Object object)
从群组中选择成员。
Select members from group.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| maxSelectCount | number | 否 | 最多可选人数 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| maxSelectCount | number | No | Maximum number of selectable members | |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
object.success 回调函数
Callback Function for object.success
####### 参数
######## Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| members | Array.<string> | 所选用户在此聊天室下的唯一标识,同一个用户在不同的聊天室下id不同 |
####### Parameters
######## Object res
| Property | Type | Description |
|---|---|---|
| members | Array.<string> | Unique identifiers of selected users in this chat room; the same user has different ids in different chat rooms |
示例代码
Example Code
javascript
wx.selectGroupMembers({
maxSelectCount: 10,
success(res) {
console.log("选择成员成功", res.members);
},
fail(err) {
console.error("选择成员失败", err);
},
});javascript
wx.selectGroupMembers({
maxSelectCount: 10,
success(res) {
console.log("Select members successfully", res.members);
},
fail(err) {
console.error("Failed to select members", err);
},
});wx.notifyGroupMembers
wx.notifyGroupMembers
wx.notifyGroupMembers(Object object)
wx.notifyGroupMembers(Object object)
发送消息提醒群成员。
Send message reminders to group members.
参数
Parameters
Object object
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| title | string | 是 | 文字链标题,发送的内容将由微信拼接为:@的成员列表+“请完成:”/"请参与:"+打开小程序的文字链,如「@alex @cindy 请完成:团建报名统计」。 | |
| members | Array.<string> | 是 | 需要提醒的用户 group_openid 列表 | |
| entrancePath | string | 是 | 文字链跳转路径 | |
| type | string | complete | 否 | 展示的动词 |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| title | string | Yes | Text link title; the sent content will be spliced by WeChat as: @mentioned members + "Please complete:"/"Please participate:" + text link to open Mini Program, e.g.「@alex @cindy Please complete: Team Building Registration Statistics」。 | |
| members | Array.<string> | Yes | List of group_openid of users to be reminded | |
| entrancePath | string | Yes | Text link jump path | |
| type | string | complete | No | Displayed verb |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function for interface call completion (executed on both success and failure) |
object.type 合法值
Valid Values for object.type
| 值 | 说明 |
|---|---|
| participate | 请参与 |
| complete | 请完成 |
| Value | Description |
|---|---|
| participate | Please participate |
| complete | Please complete |
示例代码
Example Code
javascript
wx.notifyGroupMembers({
title: "团建报名统计",
members: ["openid1", "openid2"],
entrancePath: "/pages/index/index",
type: "complete",
success(res) {
console.log("提醒成功", res);
},
fail(err) {
console.error("提醒失败", err);
},
});javascript
wx.notifyGroupMembers({
title: "Team Building Registration Statistics",
members: ["openid1", "openid2"],
entrancePath: "/pages/index/index",
type: "complete",
success(res) {
console.log("Notify successfully", res);
},
fail(err) {
console.error("Failed to notify", err);
},
});完整文档
Complete Documentation
详见 reference.md
See reference.md