# 小程序聊天工具模式開發(fā)指南Beta

# 一、功能介紹

聊天工具模式是為了幫助小程序更好與微信聊天結合而推出的模式，可用于實現(xiàn)群問卷、群拼單、群任務等功能。其與小程序普通模式相比開放更多與聊天緊密結合的能力：

1. 聊天成員相關能力：開發(fā)者可調用聊天成員選擇器并獲取成員相關id，通過開放數(shù)據(jù)域渲染聊天成員的頭像昵稱
2. 發(fā)送內容到聊天能力：開發(fā)者可發(fā)送文本、提醒、圖片、表情、視頻等內容類型到聊天中
3. 動態(tài)消息能力：小程序卡片上的輔標題可以動態(tài)更新，在用戶完成/參與了活動后下發(fā)系統(tǒng)消息

同時，聊天工具模式需要使用獨立分包基于skyline開發(fā)，該分包也可被普通模式打開。開發(fā)者可通過「小程序示例-接口Tab-聊天工具」入口體驗平臺推出的Demo：

# 二、開發(fā)指南

從基礎庫 3.7.8 開始支持

支持平臺：Android：微信8.0.56及以上版本、iOS：微信8.0.56及以上版本

# 1. 聊天工具分包配置

開發(fā)者需要在小程序全局配置 (app.json)中聲明 subPackages 與 chatTools：

1. subPackages 為分包的基本配置，屬性說明可參考分包結構配置
2. chatTools 為聊天工具配置，類型為 Object[] ，字段包括：

注意事項：

1. desc字段請按照自己的功能設計填寫，不得包含虛假、營銷信息；scopes 字段請如實填寫；否則將影響小程序審核的結果
2. 開發(fā)者需保證分包的首頁路徑進入后可以使用聊天工具的完整功能，否則將影響小程序審核的結果
3. 每個小程序目前僅支持配置一個聊天工具，后續(xù)可能放開
4. 聊天工具的分包體積需不超過 500KB
5. 聊天工具分包頁需使用 skyline 渲染，若開發(fā)者未配置，微信會在預覽/上傳代碼包時提示出錯

配置示例：

{
  "subPackages": [
    {
      "root": "packageA",
      "name": "alias",
      "pages": ["pages/cat"],
      "independent": true,
      "entry": "index.js",
      "componentFramework": "glass-easel",
      "renderer": "skyline",
    },
  ],
  "chatTools": [{
    "root": "packageA",
    "entryPagePath": "x",
    "desc": "功能描述",
    "scopes": ["scope.userLocation"]
  }],
  "rendererOptions": {
    "skyline": {
      "disableABTest": true,
      "defaultDisplayBlock": true,
      "defaultContentBox": true,
      "tagNameStyleIsolation": "legacy",
      "sdkVersionBegin": "3.7.0",
      "sdkVersionEnd": "15.255.255"
    }
  }
}

# 2. 聊天工具模式的進入與退出

# 2.1 進入聊天模式

聊天工具模式在進入時需要綁定一個微信單聊或群聊的聊天室，目前有三種進入方式：

1. 當小程序處于普通模式時，開發(fā)者調用 wx.openChatTool 但不傳入聊天室id，微信會拉起聊天列表讓用戶選擇，用戶選擇后綁定聊天室進入聊天工具模式
2. 當小程序處于普通模式時，開發(fā)者調用 wx.openChatTool 并在接口中傳入聊天室id（群聊為opengid，單聊為open_single_roomid），會直接綁定該聊天室進入
3. 用戶在聊天工具模式里發(fā)送各種類型內容到綁定的聊天后，當用戶從同一個聊天的這些內容入口再此回到小程序中，會使用聊天工具模式打開，此時綁定的聊天不變

# 2.2 退出聊天模式

聊天工具目前有三種退出方式：

1. 在聊天工具中回到非聊天工具分包頁面中（包括用戶自己觸發(fā)返回、開發(fā)者調用 wx.navigateBack / wx.switchTab ），會觸發(fā)退出聊天工具模式
2. 小程序 reLaunch 到普通頁面（包括用戶點擊其他非聊天工具模式入口、開發(fā)者調用 wx.reLaunch 等），會觸發(fā)退出聊天工具模式

注意：在聊天工具分包頁，無法通過 wx.navigateTo 或者 wx.redirectTo 跳轉到非聊天工具分包頁。如需跳轉，先通過 wx.navigateBack 退出當前聊天工具分包，在使用路由接口進行跳轉。

# 2.3 聊天工具模式的判定

開發(fā)者可通過 wx.getApiCategory 中的 apiCategory字段是否為 chatTool，判斷當前是否處于聊天工具模式。

# 3. 聊天成員相關能力

# 3.1 獲取相關id接口

聊天工具模式下有以下3種id信息：

1. opengid：微信群的唯一標識id
2. open_single_roomid：單聊的唯一標識id
3. group_openid：微信用戶在此聊天室下的唯一標識，同一個用戶在不同的聊天室下id不同

相關接口如下：

1. wx.getGroupEnterInfo：進入聊天工具模式前，獲取群聊id信息
2. wx.getChatToolInfo：進入聊天工具模式后，獲取群聊id信息

這兩個接口的區(qū)別在于，在聊天工具分包頁，推薦用 wx.getChatToolInfo 獲取綁定群相關信息即可。在進入聊天工具分包頁之前，例如從群聊會話卡片打開小程序，此時希望復用卡片所在的群聊，可通過 wx.getGroupEnterInfo 獲取卡片所在群的 opengid, 并在 wx.openChatTool 時傳入，此時可不喚起群選擇列表，直接進入。

# 3.2 選擇聊天成員接口

開發(fā)者可調用wx.selectGroupMembers讓用戶選擇聊天室的成員，并返回選擇成員的group_openid。需要注意的是，若當前聊天室為單聊，則直接返回對方用戶的group_openid，不再拉起選擇器。

# 3.3 渲染聊天成員的頭像昵稱

開發(fā)者可通過 open-data-list 與 open-data-item 渲染聊天成員的頭像昵稱

# 4. 發(fā)送到聊天能力

可將小程序卡片、提醒消息、文本、圖片、表情、文件發(fā)送到聊天中，相關接口如下：

1. wx.shareAppMessageToGroup：將小程序卡片發(fā)送到綁定的聊天室
2. wx.notifyGroupMembers：提醒用戶完成任務，發(fā)送的內容將由微信拼接為：@的成員列表+“請完成：”/"請參與："+打開小程序的文字鏈，如「@alex @cindy 請完成：團建報名統(tǒng)計」
3. form bind:submitToGroup="onSubmitToGroup" 與 button form-type="submitToGroup"：將輸入框內的文本內容發(fā)送到綁定的聊天室
4. wx.shareImageToGroup：將圖片發(fā)送到綁定的聊天室
5. wx.shareEmojiToGroup：將表情發(fā)送到綁定的聊天室
6. wx.shareVideoToGroup：將視頻發(fā)送到綁定的聊天室
7. wx.shareFileToGroup：將文件發(fā)送到綁定的聊天室

# 5. 動態(tài)消息能力

從聊天模式中發(fā)送的小程序卡片，可以獲得動態(tài)消息能力，該能力的用戶表現(xiàn)包括：

1. 小程序卡片上的輔標題可以動態(tài)更新
2. 可以在聊天中下發(fā)系統(tǒng)消息，內容為：成員A+“完成了”/"參與了"+成員B+“發(fā)布的”+打開小程序的文字鏈，如「alex 完成了 cindy 發(fā)布的 團建報名統(tǒng)計」

該功能的開發(fā)步驟包括：

# 5.1 創(chuàng)建activity_id

服務端通過創(chuàng)建activity_id接口創(chuàng)建activity_id

# 5.2 聲明分享卡片為動態(tài)消息

前端通過 wx.updateShareMenu 聲明要分享的卡片為動態(tài)消息，請求參數(shù)如下：

注意事項：

1. useForChatTool 為 true 時，chooseType 和 participant 才會生效
2. chooseType = 1，表示按指定的 participant 當作參與者
3. chooseType = 2，表示群內所有成員均為參與者（包括后加入群）

代碼示例：

wx.updateShareMenu({
        withShareTicket: true,
        isUpdatableMessage: true,
        activityId: 'xxx',
        useForChatTool: true,
        chooseType: 1,
        participant: that.data.members,
        templateInfo: {
          templateId:    '4A68CBB88A92B0A9311848DBA1E94A199B166463'
        },
)

模版區(qū)別（target_state與participator_state含義見步驟3）：

# 5.3 更新活動狀態(tài)或用戶完成情況

服務端通過 setChatToolMsg 接口更新活動狀態(tài)或用戶完成情況。

也可通過云開發(fā)調用，接口名 chattoolmsg.send。

調用示例：

//變更單個成員狀態(tài)
{
    "activity_id": "xxx",
    "target_state":1,
    "version_type": 0,
    "participator_info_list": [
        {
            "group_openid": "aaa",
            "state": 1
        },
        {
            "group_openid": "bbb",
            "state": 1

        }
    ]
}
//變更動態(tài)消息狀態(tài)
{
    "activity_id": "xxx",
    "target_state":3,
    "version_type": 0,
}

# 6. 聊天工具模式內禁用的能力

以下能力暫不支持聊天工具模式下使用，請開發(fā)者做好適配。

1. 聊天工具模式禁用普通轉發(fā)能力，請使用上文「發(fā)送到聊天能力開放」中的接口實現(xiàn)：button open-type=share 和 小程序右上角「…-發(fā)送給朋友」
2. 聊天工具模式希望服務盡可能閉環(huán)在小程序中，外跳類接口暫不支持使用：
   • navigateToMiniProgram;
   • openEmbeddedMiniProgram;
   • openOfficialAccountArticle;
   • openChannelsUserProfile;
   • openChannelsLive;
   • openChannelsEvent;
   • openChannelsActivity。
3. 聊天工具模式暫不支持廣告：ad 和 ad-custom