微信小程式快速整合

本頁用原生微信小程式寫一個最小的示例：建立客戶端、登入、顯示會話列表、收發訊息，再說明怎樣傳送圖片、語音和檔案，以及怎樣在 Taro React 中接入。

開始之前，先按概述安裝已釋出的 npm 包（或使用本地構建的包），並讓你的業務服務端能為登入使用者簽發登入憑證。

建立客戶端

在 app.js 中建立整個小程式唯一的客戶端，並用同一個引用建立頁面使用的 Behavior：

const {
  createDRMiniProgramClient, createDRClientRef, createDRBehavior, locale,
} = require('@deeprespond/im-miniprogram');
const imRef = createDRClientRef();
App({
  behavior: createDRBehavior(imRef),
  onLaunch() {
    this.im = createDRMiniProgramClient({
      appKey: '组织#应用', apiUrl: 'https://im.example.com', autoMarkRead: true,
    });
    imRef.set(this.im);
  },
  report(error) {
    wx.showToast({ title: locale.describeError(error), icon: 'none' });
  },
});

登入頁拿到業務服務端簽發的憑證後登入，並等待連線就緒：

await getApp().im.auth.loginWithTicket({ ticket });
await getApp().im.connection.waitUntilReady({ timeoutMs: 20000 });

客戶端建立後自動恢復上次的登入，已經登入的不需要再登入。
登入憑證由業務服務端簽發，不要把憑證和 App Secret 寫死在小程式中。
同一個 appKey 只能建立一個客戶端，再次建立返回 client_exists。不再使用時呼叫 await im.destroy() 銷燬。

會話和聊天頁

頁面加入 app.behavior 後，用 this.drList() 把會話列表繫結到頁面資料，列表變化時頁面自動更新：

const app = getApp();
Page({
  behaviors: [app.behavior],
  data: {},
  onLoad() { this.drList('list', im => im.conversations.list()); },
  onShow() { this.drPageShow(); },
  onHide() { this.drPageHide(); },
  onUnload() { this.drPageUnload(); },
});

xml

<view wx:for="{{list.items}}" wx:key="conversation_key">
  {{item.peer || item.group_id}}：{{item.unread_count}}
</view>

聊天頁用 this.drMessageList('chat', conversationKey) 繫結訊息列表，用 wx:for 迴圈訊息時 wx:key 寫 _key。傳送文字：

await app.im.messages.send({ conversation_key: conversationKey }, {
  type: 'text', body: { text: '你好' },
});

生命週期：Component 透過 Behavior 自動接收生命週期；Page 要像上例那樣在 onShow、onHide、onUnload 中呼叫 drPageShow()、drPageHide()、drPageUnload()。
切換使用者：登入的使用者變化後，繫結自動釋放並重新建立。
效能：每個元件的 setData 按順序逐個執行，一次傳入的資料不超過 512 KiB；訊息列表預設只顯示最近 100 條。
分包：只需要繫結的頁面可以從單獨的 /bind 入口匯入 createDRClientRef、createDRBehavior、bindSnapshot、bindState、DR_STATES；SDK 本身放在分包中，載入後呼叫 imRef.set(im)。
聊天室：用 drChatroom 繫結。同一個聊天室的多個繫結共用一個進入計數，最後一個解除繫結時才離開聊天室。

路徑檔案和錄音

小程式中的檔案都用本地路徑（如 wx.chooseMedia 返回的臨時路徑）交給 SDK，不使用 Blob。下面傳送圖片、錄製併傳送語音、下載並開啟檔案：

wx.chooseMedia({
  count: 1, mediaType: ['image'],
  success: result => app.im.messages.send({ to_user: 'alice' }, {
    type: 'image', file: { path: result.tempFiles[0].tempFilePath },
  }).catch(error => app.report(error)),
});

const recorder = await app.im.files.recordVoice({ maxSeconds: 60 });
await recorder.start();
const voice = await recorder.stop();
await app.im.messages.send({ to_user: 'alice' }, {
  type: 'voice', file: voice.file, body: { duration_seconds: voice.duration_seconds },
});

const task = app.im.files.download({ message });
const { path, fileType } = await task;
wx.openDocument({ filePath: path, fileType });

影片：傳 { path, width, height, duration, thumbnail: { path } }。
後設資料：傳送前 SDK 去掉 JPEG、PNG 中的拍攝地點等後設資料，MP4 按分段處理。無法處理的格式以 metadata_unremovable 拒絕；只有業務明確接受保留後設資料時，才設定 keepMetadata: true。
快取：app.im.files.localPath(url) 返回已下載檔案的本地路徑，可以用作圖片快取。下載任務可以呼叫 cancel() 取消。
切到後臺：預覽圖片、開啟文件時小程式會切到後臺。呼叫 keepForeground() 讓連線最多再保持 60 秒，使用者返回後呼叫它返回的函式釋放。

Taro React

Taro 工程使用 Web SDK 的小程式入口和 React 繫結。先匯入補齊（polyfills）入口，再建立客戶端：

tsx

import '@deeprespond/im-web/polyfills';
import { createDRMiniProgramClient } from '@deeprespond/im-web/miniprogram';
import { DRProvider } from '@deeprespond/im-web-react/miniprogram';
const im = createDRMiniProgramClient({ appKey: '组织#应用', apiUrl: 'https://im.example.com' });
export default function App({ children }) {
  return <DRProvider client={im}>{children}</DRProvider>;
}

各包使用同一個版本。
Taro 不需要安裝原生小程式的預打包包。完整示例見倉庫中的 sdk/miniprogram/example-taro。

獨立頻道能力

小程式目前只能查詢頻道、本人的頻道會話和頻道成員，並匯出了頻道的型別定義；還沒有接入 LiveKit 媒體，不能加入頻道進行音影片。channels.supported 為 false，呼叫加入會在佔用席位之前被拒絕，見頻道查詢與限制。

微信小程式快速整合 ​

建立客戶端 ​

會話和聊天頁 ​

路徑檔案和錄音 ​