聊天訊息

一、功能概述

聊天室模块(chat) 提供聊天功能 API，供開發者整合聊天功能。

二、聊天室狀態資訊

2.1 取得聊天室資訊

與使用者、聊天室有關的狀態均儲存在聊天室模組中，並透過 getChatInfo 取得聊天室狀態資訊。

Api 方法： getChatInfo(): ChatModuleInfo

回傳值說明： 聊天室狀態資訊，ChatModuleInfo 類型，詳細類型說明如下

範例：

const chatInfo = watchCore.chat.getChatInfo();
console.log('房间是否被关闭', chatInfo.chatRoomIsClosed);
console.log('当前用户是否被禁言', chatInfo.isShield);

三、聊天訊息來源

透過聊天室訊息事件 ChatEvents.ChatMessage、聊天歷史記錄 API getChatHistory 等取得的聊天訊息類型均為 ChatMsgType 命名空間下的類型。 所有訊息資料都有對應的訊息來源 msgSource 欄位，該欄位為 ChatMsgSource 列舉，開發者可根據該欄位顯示對應的訊息樣式。

Enum 列舉： ChatMsgSource

四、發送聊天訊息

4.1 發送文字訊息

用於觀眾進行聊天發言，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendSpeakMsg(options: SendSpeakMsgOptions): Promise<ChatMsgSpeakType>

參數說明：

• options：發言參數，SendSpeakMsgOptions 類型，必傳，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgSpeakType> 類型，詳細類型說明如下

範例：

import { ChatMsgQuoteOriginType, ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';
// 发送的文本
const content = '今天天气真好[呲牙][酷]';
// 被回复的消息
const currentQuoteMsg: ChatMsgSpeakType | undefined = undefined;
// 发送消息
watchCore.chat.sendSpeakMsg({
  content,
  quoteMsg: currentQuoteMsg,
});

4.2 發送圖片訊息

用於觀眾發送圖片訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendImageMsg(options: SendImageMsgOptions): Promise<ChatMsgImageType>

參數說明：

• options：發送圖片參數，SendImageMsgOptions 類型，必傳，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgImageType> 類型，詳細類型說明如下

範例：

import { uuidV4 } from '@polyv/utils/es/string';
// 图片 id
const imageId = uuidV4();
// 图片地址
const imageUrl = '发送到图片地址，需要带有协议';
// 图片地址
const size = { width: 200, height: 100 };
// 发送图片消息
watchCore.chat.sendImageMsg({ imageId, imageUrl, size });

4.3 發送表情圖片訊息

透過 getEmotionImages 方法取得表情圖片列表後，透過列表項的 id、url 發送表情圖片訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

開發者可透過 getEmotionImages 取得表情圖片列表。

Api 方法： sendEmotionImageMsg(options: SendEmotionImageMsgOptions): Promise<ChatMsgEmotionType>

參數說明：

• options：發送表情圖片參數，SendEmotionImageMsgOptions 類型，必填，詳細類型說明如下

回傳值說明： 發送到伺服器後的訊息物件，Promise<ChatMsgEmotionType> 類型，詳細類型說明如下

範例：

// 获取表情图片列表
const emotionImages = await watchCore.chat.getEmotionImages();
// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({ emotionId: item.id, emotionUrl: item.url });

4.4 發送系統訊息

用於發送系統訊息到聊天區，請注意該訊息並不會發送到伺服器端，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendSystemMsg(content: string): void

參數說明：

• content：訊息內容，string 類型，必填

範例：

watchCore.chat.sendSystemMsg('聊天室已关闭');

五、監聽聊天訊息事件

當有觀眾發言、打賞等涉及聊天訊息操作時，聊天室模組會回呼 ChatEvents.ChatMessage 事件，開發者可透過監聽該事件進行聊天訊息的渲染。

由於本地發送訊息時，在發送至伺服器端前就會回呼 ChatEvents.ChatMessage 事件，此時回呼的訊息 id 即 chatMsg.id 為本地建立的 id，伺服器端回呼後，透過 ChatEvents.ReplaceChatMessage 進行訊息資料替換（包括圖片違規等均透過該事件修改訊息資料）。

import { ChatEvents, ChatMsgType } from '@polyv/live-watch-miniprogram-sdk';

// 聊天消息列表
const chatMsgList: ChatMsgType[] = [];

// 聊天消息事件
watchCore.chat.eventEmitter.on(ChatEvents.ChatMessage, (data) => {
  // 插入到聊天消息列表
  chatMsgList.push(data.chatMsg);
  // 渲染聊天消息...
});

// 替换聊天消息数据事件
watchCore.chat.eventEmitter.on(ChatEvents.ReplaceChatMessage, (data) => {
  // 需要被替换的消息 id
  const replaceId = data.id;
  // 新的消息对象
  const chatMsg = data.chatMsg;

  const index = chatMsgList.findIndex((item) => item.id === replaceId);
  if (index !== -1) {
    chatMsgList[index] = chatMsg;
  }
  // 将视图的消息节点替换...
});

六、取得聊天歷史記錄

6.1 取得聊天歷史訊息

透過 getChatHistory 方法取得頻道下的聊天歷史訊息。

Api 方法： getChatHistory(options?: GetChatHistoryOptions): Promise<ChatMsgType[]>

參數說明：

• options：取得選項，GetChatHistoryOptions 類型，可選傳遞，預設為 {}，詳細類型說明如下

回傳值說明： Promise<ChatMsgType[]> 類型

範例：

// 获取 0 ～ 19 条消息
const historyData = await watchCore.chat.getChatHistory({
  start: 0,
  end: 19,
});
// 返回数据示例，类型为：ChatMsgType[]
[{
  id: '5191c230-c6c4-11ed-8c31-23e8ced55946',
  time: 1679278200247,
  msgSource: 'speak',
  content: '今天天气真好[呲牙][酷]',
  user: {
    userId: '18012345678',
    nick: '小明',
    pic: '头像地址',
  },
}]

七、訊息/評論上牆

7.1 取得聊天室資訊

與使用者、聊天室相關的狀態均儲存在聊天室模組中，並透過 getChatInfo 取得聊天室狀態資訊。

Api 方法： getChatInfo(): ChatModuleInfo

回傳值說明： 聊天室狀態資訊，ChatModuleInfo 類型，詳細類型說明如下

範例：

const chatInfo = watchCore.chat.getChatInfo();
console.log('房间是否被关闭', chatInfo.chatRoomIsClosed);
console.log('当前用户是否被禁言', chatInfo.isShield);

7.2 取得聊天室設定

用於獲取管理後台的聊天室設定資訊。

Api 方法： getChatSetting(): ChatSetting

回傳值說明： 聊天室設定資訊，ChatSetting 型別，詳細型別說明如下

範例：

const setting = watchCore.chat.getChatSetting();
console.log('观看页聊天室开关', setting.watchChatEnabled);
console.log('是否显示翻译功能', setting.chatTranslateEnabled);

7.3 取得聊天歷史訊息

透過 getChatHistory 方法取得頻道下的聊天歷史訊息。

Api 方法： getChatHistory(options?: GetChatHistoryOptions): Promise<ChatMsgType[]>

參數說明：

• options：取得選項，GetChatHistoryOptions 型別，可選傳遞，預設為 {}，詳細型別說明如下

回傳值說明： Promise<ChatMsgType[]> 類型

範例：

// 获取 0 ～ 19 条消息
const historyData = await watchCore.chat.getChatHistory({
  start: 0,
  end: 19,
});
// 返回数据示例，类型为：ChatMsgType[]
[{
  id: '5191c230-c6c4-11ed-8c31-23e8ced55946',
  time: 1679278200247,
  msgSource: 'speak',
  content: '今天天气真好[呲牙][酷]',
  user: {
    userId: '18012345678',
    nick: '小明',
    pic: '头像地址',
  },
}]

7.4 獲取即時的讚數

收到使用者按讚事件後，可透過此方法取得即時按讚數，並透過 ChatEvents.ChatLikeCountChange 事件監聽按讚數的變化。

Api 方法： getRealtimeLikes(): number

範例：

const realtimeLikes = watchCore.chat.getRealtimeLikes();
console.log('实时点赞数：', realtimeLikes);

7.5 傳送按讚數

Api 方法： sendLike(times: number): Promise<number>

參數說明：

• times：點讚數，number 類型，必填

回傳值說明： Promise<number> 類型

7.6 取得表情圖片列表

通過 getEmotionImages 取得標題圖片列表，取得該列表後，使用 id、url 呼叫 ChatModule.sendEmotionImageMsg 發送表情圖片訊息。

Api 方法： getEmotionImages(): Promise<EmotionImageData[]>

回傳值說明： Promise<EmotionImageData[]> 類型

範例：

const emotionImages = await watchCore.chat.getEmotionImages();
// 表情图片列表数据示例：
[{ id: '0', title: '收到', url: 'https://s2.videocc.net/default-img/img-emotion/v1/shoudao.png' }]

// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({
  emotionId: item.id,
  emotionUrl: item.url,
});

7.7 發送文字訊息

用於觀眾進行聊天發言，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendSpeakMsg(options: SendSpeakMsgOptions): Promise<ChatMsgSpeakType>

參數說明：

• options：發言參數，SendSpeakMsgOptions 類型，必傳，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgSpeakType> 類型，詳細類型說明如下

範例：

import { ChatMsgQuoteOriginType, ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';
// 发送的文本
const content = '今天天气真好[呲牙][酷]';
// 被回复的消息
const currentQuoteMsg: ChatMsgSpeakType | undefined = undefined;
// 发送消息
watchCore.chat.sendSpeakMsg({
  content,
  quoteMsg: currentQuoteMsg,
});

7.8 傳送圖片訊息

用於觀眾發送圖片訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendImageMsg(options: SendImageMsgOptions): Promise<ChatMsgImageType>

參數說明：

• options：發送圖片參數，SendImageMsgOptions 類型，必傳，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgImageType> 類型，詳細類型說明如下

範例：

import { uuidV4 } from '@polyv/utils/es/string';
// 图片 id
const imageId = uuidV4();
// 图片地址
const imageUrl = '发送到图片地址，需要带有协议';
// 图片地址
const size = { width: 200, height: 100 };
// 发送图片消息
watchCore.chat.sendImageMsg({ imageId, imageUrl, size });

7.9 發送表情圖片訊息

透過 getEmotionImages 方法取得表情圖片列表後，透過列表項的 id、url 發送表情圖片訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

開發者可透過 getEmotionImages 取得表情圖片列表。

Api 方法： sendEmotionImageMsg(options: SendEmotionImageMsgOptions): Promise<ChatMsgEmotionType>

參數說明：

• options：發送表情圖片參數，SendEmotionImageMsgOptions 類型，必填，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgEmotionType> 類型，詳細類型說明如下

範例：

// 获取表情图片列表
const emotionImages = await watchCore.chat.getEmotionImages();
// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({ emotionId: item.id, emotionUrl: item.url });

7.10 發送系統訊息

用於發送系統訊息到聊天區，請注意該訊息不會發送到伺服器端，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendSystemMsg(content: string): void

參數說明：

• content：訊息內容，string 類型，必填

範例：

watchCore.chat.sendSystemMsg('聊天室已关闭');

7.11 取得超長訊息的完整文字

講師可發送超過 2000 字的文字訊息，該訊息為超長文字訊息（透過 chatMsg.isOverLength === true 判斷），chat 提供訊息文字只會回傳前 500 字的訊息字串，如需展示完整的訊息文字，可呼叫該方法取得。

Api 方法： getFullMessage(id: string): Promise<string>

參數說明：

• id：訊息 id，string 類型，必填

回傳值說明： Promise<string> 類型

範例：

import { ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';

async function getFullMessageText(chatMsg: ChatMsgSpeakType): Promise<string> {
  if (!chatMsg.isOverLength) {
    throw new Error('该消息非超长文本');
  }

  const result = await watchCore.chat.getFullMessage(chatMsg.id);
  console.log('完整的文本', result);
  return result;
}

7.12 獲取聊天室的即時在線人數

透過 getOnlineUserCount 取得即時線上人數，並透過 ChatEvents.OnlineUserCountChange 事件監聽聊天室線上人數的變動。

Api 方法： getOnlineUserCount(): number

回傳值說明： 即時線上人數

範例：

const onlineUserCount = watchCore.chat.getOnlineUserCount();
console.log('当前聊天室在线人数：', onlineUserCount);

// 监听人数改变
watchCore.chat.eventEmitter.on(ChatEvents.OnlineUserCountChange, (data) => {
  console.log('在线人数改变：', data.onlineUserCount);
});

7.13 轉換發言內容

透過 parseSpeakContent 將觀眾發言中的表情、連結轉換為 HTML 元素。

轉換順序：parseLink > removeEmotion > parseEmotion > parseLineBreak

Api 方法： parseSpeakContent(content: string, options?: ParseOptions): string

參數說明：

• content：發言內容，string 類型，必傳

• options：轉換選項，ParseOptions 類型，選填，詳細類型說明如下

回傳值說明： 轉換後的 HTML 字元

範例：

// 转换链接
watchCore.chat.parseSpeakContent('这是我们的官网地址：https://www.polyv.net/', { parseLink: true });
// 转换后的字符串：这是我们的官网地址：<a target="_blank" rel="noopener" href="https://www.polyv.net/">https://www.polyv.net/</a>

// 移除表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { removeEmotion: true });
// 转换后的字符串：今天天气真好

// 转换表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { parseEmotion: true });
// 转换后的字符串：今天天气真好<img src="黄脸表情图片地址" alt="呲牙" class="plv-emotion-img" />

// 将换行符转成 <br />
watchCore.chat.parseSpeakContent('这是一段文字\n这是另一段文字', { parseLineBreak: true });
// 转换后的字符串：这是一段文字<br />这是另一段文字

7.14 取得黃臉表情列表資料

Api 方法： getEmotionFaceList(): EmotionListItem[]

回傳值說明： EmotionListItem[] 類型

7.15 切割聊天訊息中的文字與表情

Api 方法： splitTextAndEmotion(content: string): TextSplitResultItem[]

參數說明：

• content：發言內容，string 類型，必傳

回傳值說明： TextSplitResultItem[] 類型

八、其他

8.1 取得表情圖片列表

透過 getEmotionImages 取得標題圖片列表，取得該列表後，使用 id、url 呼叫 ChatModule.sendEmotionImageMsg 發送表情圖片訊息。

Api 方法： getEmotionImages(): Promise<EmotionImageData[]>

回傳值說明： Promise<EmotionImageData[]> 類型

範例：

const emotionImages = await watchCore.chat.getEmotionImages();
// 表情图片列表数据示例：
[{ id: '0', title: '收到', url: 'https://s2.videocc.net/default-img/img-emotion/v1/shoudao.png' }]

// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({
  emotionId: item.id,
  emotionUrl: item.url,
});

8.2 取得超長訊息的完整文字

講師可發送超過 2000 字的文字訊息，該訊息為超長文字訊息（透過 chatMsg.isOverLength === true 判斷），chat 提供訊息文字只會回傳前 500 字的訊息字串，如需展示完整的訊息文字，可呼叫該方法取得。

Api 方法： getFullMessage(id: string): Promise<string>

參數說明：

• id：訊息 id，string 類型，必填

回傳值說明： Promise<string> 類型

範例：

import { ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';

async function getFullMessageText(chatMsg: ChatMsgSpeakType): Promise<string> {
  if (!chatMsg.isOverLength) {
    throw new Error('该消息非超长文本');
  }

  const result = await watchCore.chat.getFullMessage(chatMsg.id);
  console.log('完整的文本', result);
  return result;
}

8.3 取得聊天室設定

用於獲取管理後台的聊天室設定資訊。

Api 方法： getChatSetting(): ChatSetting

回傳值說明： 聊天室設定資訊，ChatSetting 型別，詳細型別說明如下

範例：

const setting = watchCore.chat.getChatSetting();
console.log('观看页聊天室开关', setting.watchChatEnabled);
console.log('是否显示翻译功能', setting.chatTranslateEnabled);

8.4 轉換發言內容

透過 parseSpeakContent 將觀眾發言中的表情、連結轉換為 HTML 元素。

轉換順序：parseLink > removeEmotion > parseEmotion > parseLineBreak

Api 方法： parseSpeakContent(content: string, options?: ParseOptions): string

參數說明：

• content：發言內容，string 類型，必傳

• options：轉換選項，ParseOptions 類型，選填，詳細類型說明如下

回傳值說明： 轉換後的 HTML 字元

範例：

// 转换链接
watchCore.chat.parseSpeakContent('这是我们的官网地址：https://www.polyv.net/', { parseLink: true });
// 转换后的字符串：这是我们的官网地址：<a target="_blank" rel="noopener" href="https://www.polyv.net/">https://www.polyv.net/</a>

// 移除表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { removeEmotion: true });
// 转换后的字符串：今天天气真好

// 转换表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { parseEmotion: true });
// 转换后的字符串：今天天气真好<img src="黄脸表情图片地址" alt="呲牙" class="plv-emotion-img" />

// 将换行符转成 <br />
watchCore.chat.parseSpeakContent('这是一段文字\n这是另一段文字', { parseLineBreak: true });
// 转换后的字符串：这是一段文字<br />这是另一段文字

8.5 獲取聊天室的即時在線人數

透過 getOnlineUserCount 取得即時線上人數，ChatEvents.OnlineUserCountChange 事件監聽聊天室線上人數的變更。

Api 方法： getOnlineUserCount(): number

回傳值說明： 即時線上人數

範例：

const onlineUserCount = watchCore.chat.getOnlineUserCount();
console.log('当前聊天室在线人数：', onlineUserCount);

// 监听人数改变
watchCore.chat.eventEmitter.on(ChatEvents.OnlineUserCountChange, (data) => {
  console.log('在线人数改变：', data.onlineUserCount);
});