文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>聊天互动（含 UI）>更多特性>添加自定义消息>React

React

最近更新时间：2026-03-04 10:02:01

我的收藏

本页目录：

TUIKit 默认实现了文本、图片、语音、视频、文件等基本消息类型的发送和展示，如果这些消息类型满足不了您的需求，您可以新增自定义消息类型。

基本消息类型

消息类型
显示效果图
文本类消息



图片类消息



语音类消息



视频类消息



文件类消息




自定义消息

如果基本消息类型不能满足您的需求，您可以根据实际业务需求自定义消息。
自定义消息预设样式
显示效果图
超文本类消息

评价类消息

订单类消息



实现步骤

步骤1：思考需要自定义的数据

自定义消息需要传入哪些数据是用户自行决定的，假设我们要开发一个扔骰子（Dice）的自定义消息，示例代码如下所示：
import { useMessageInputState } from '@tencentcloud/chat-uikit-react';

const { sendCustomMessage } = useMessageInputState();

sendCustomMessage({
  payload: {
    data: JSON.stringify({ businessID: 'dice', value: Math.ceil(Math.random() * 6) }), // string 类型
    description: '[骰子]',  // string类型 在会话列表摘要中显示的内容
    extension: '', // string类型 可不填
  },
});
发送自定义消息，更多详情请参考 ChatEngine 接口文档。

步骤2：创建自定义消息组件

创建 CustomMessage.tsx 文件，该组件接收 message 属性，解析 message.payload.data 判断是否是 Dice 消息类型，不匹配时建议回退到内置 <CustomMessage />，否则 IM 内置的自定义消息将不会显示。
import { useMemo } from 'react';
import { CustomMessage } from '@tencentcloud/chat-uikit-react';
import type { MessageModel } from '@tencentcloud/chat-uikit-react';

const DICE_FACES = ['⚀', '⚁', '⚂', '⚃', '⚄', '⚅'];

function CustomMessage({ message }: { message: any }) {
  const diceValue = useMemo<number | null>(() => {
    try {
      const parsed = JSON.parse(message?.payload?.data || '{}');
      return parsed?.businessID === 'dice' ? Number(parsed.value) : null;
    } catch {
      return null;
    }
  }, [message?.payload]);

  if (!diceValue) {
    return <CustomMessage message={message} />;
  }

  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '8px 12px' }}>
      <span style={{ fontSize: 36 }}>{DICE_FACES[diceValue - 1]}</span>
      <span>掷出了 {diceValue}</span>
    </div>
  );
}

export default CustomMessage;

步骤3：注册到 MessageList

通过 messageRenderers prop 传入，key 为 MessageType 枚举值。
import { useMemo } from 'react';
import { Chat, MessageList, MessageInput, MessageType, useMessageInputState } from '@tencentcloud/chat-uikit-react';
import CustomMessage from './CustomMessage';

function ChatView() {
  const { sendCustomMessage } = useMessageInputState();

  const customRenderers = useMemo(() => ({
    [MessageType.CUSTOM]: CustomMessage,
  }), []);

  const handleSendDice = () => {
    sendCustomMessage({
      payload: {
        data: JSON.stringify({ businessID: 'dice', value: Math.ceil(Math.random() * 6) }),
        description: '[骰子]',
        extension: '',
      },
    });
  };

  return (
    <Chat>
      <MessageList messageRenderers={customRenderers} />
      <MessageInput
        actions={['EmojiPicker', 'AttachmentPicker', {
          key: 'DiceButton',
          component: () => <button onClick={handleSendDice}>🎲 掷骰子</button>,
        }]}
      />
    </Chat>
  );
}
中国站
目录