@tencentcloud/chat-uikit-react 2.3.1 → 3.0.0

package/src/components/Chat/Chat.zh-CN.mdx

@@ -0,0 +1,275 @@
+import { Meta, Story, Canvas, Source, ArgTypes, Markdown } from '@storybook/blocks';
+import * as ChatStories from './Chat.stories';
+
+<Meta
+  of={ChatStories}
+  name="文档"
+/>
+
+# Chat 聊天组件
+
+Chat 组件是一个容器组件，是 @tencentcloud/chat-uikit-react 的核心组件之一，提供了主要的聊天界面结构。它作为聊天 UI 元素的包装器，并管理聊天上下文。
+
+**Chat 组件可以单独使用。**
+
+## 特性
+
+- 灵活的布局结构
+- 可自定义的头部、消息列表和输入组件
+- 提供聊天相关的上下文数据
+- 响应式设计和可定制样式
+
+## 核心组件
+
+Chat 组件一般会和 ChatHeader、MessageList、MessageInput 一起使用。
+
+- ChatHeader：聊天头部组件，用于显示聊天标题、用户头像、用户在线状态等信息，也是音视频通话的入口。
+- MessageList：消息列表组件，用于显示聊天消息。
+- MessageInput：消息输入组件，用于输入聊天消息。
+
+## 基础用法
+
+Chat 组件可以单独使用，需要传入 `defaultConversationID` 参数，如果传入了改参数，Chat 组件会自动切换到对应的会话。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import React from 'react';
+import { TUILogin } from '@tencentcloud/tui-core';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react';
+import { Chat, ChatHeader, MessageList, MessageInput } from '@tencentcloud/chat-uikit-react';
+
+const config = {
+  SDKAppID: 0, // Your SDKAppID, number type, Get it from Step 4
+  userID: 'YOUR_USER_ID', // Login UserID, string type,  Get it from Step 5
+  userSig: 'YOUR_USER_SIG', // Your userSig, string type,  Get it from Step 5
+}
+
+TUILogin.login({
+  ...config,
+  useUploadPlugin: true
+}).then(() => {
+}).catch(() => {});
+
+function MyChat() {
+  return (
+    <UIKitProvider language='en-US' theme='light'>
+      <Chat defaultConversationID="YOUR_CONVERSATION_ID">
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+    </UIKitProvider>
+  );
+}
+`}
+/>
+
+## Props 属性说明
+
+<Markdown>
+{`
+| 参数名 | 类型 | 默认值 | 描述 |
+| ------ | ------ | ------ | ------ |
+| defaultConversationID | string | \`undefined\` | 默认会话 ID，如果设置了该值，组件会自动切换到对应的会话 |
+| ChatHeader | React.ComponentType | \`undefined\` | 自定义聊天头部组件，用于替换默认的头部组件 |
+| MessageList | React.ComponentType | \`undefined\` | 自定义消息列表组件，用于替换默认的消息列表 |
+| MessageInput | React.ComponentType | \`undefined\` | 自定义消息输入组件，用于替换默认的输入框 |
+| children | React.ReactNode | \`undefined\` | 子组件，通常包含 ChatHeader、MessageList 和 MessageInput |
+| className | string | \`undefined\` | 自定义类名，用于自定义组件样式 |
+| style | React.CSSProperties | \`undefined\` | 内联样式对象，用于自定义组件样式 |
+`}
+</Markdown>
+
+## 定制化
+
+### 自定义样式
+
+你可以使用 CSS modules 或内联样式来自定义 Chat 组件的外观：
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import classes from './CustomChat.module.scss';
+
+<Chat
+  className={classes.customChat}
+  style={{
+    backgroundColor: '#f5f5f5',
+    padding: '20px',
+    borderRadius: '8px',
+    boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)'
+  }}
+>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+### 自定义组件
+
+你可以提供自定义组件来替换默认组件：
+
+#### 自定义聊天头部
+
+使用 `useChatHeaderProps` 钩子函数来获取聊天头部组件的 props。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatHeaderProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomChatHeader = () => {
+  const {
+    /** 聊天头像 url */
+    avatarUrl: string;
+    /** 聊天标题 */
+    title: string | undefined;
+    /** 用户在线状态 */
+    userStatus: IUserStatus | undefined;
+    /** 当前会话 */
+    conversation: IConversationModel | undefined;
+    /** 是否是系统会话 */
+    system: boolean | undefined;
+  } = useChatHeaderProps();
+
+  return (
+    <div className="custom-header">
+      <h1>{title}</h1>
+      <img src={avatarUrl} alt="头像" />
+      {
+        userStatus?.statusType === 1
+        ? <div>在线</div>
+        : <div>离线</div>
+      }
+    </div>
+  );
+};
+
+<Chat ChatHeader={CustomChatHeader}>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+#### 自定义消息列表
+
+使用 `useChatContext` 钩子函数来获取和消息列表相关的数据。要注意的是 useChatContext 是基于 React Context 的上下文，必须在 Chat 组件内部使用。
+
+messageList 首次回默认返回最新的 15 条消息，如果需要获取更多消息，可以调用 `getMessageList` 方法。
+
+可以使用 `judgeHasMoreMessage` 方法来判断是否还有更多消息。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatContext } from '@tencentcloud/chat-uikit-react';
+
+const CustomMessageList = () => {
+
+  const {
+    messageList,
+    getMessageList,
+    judgeHasMoreMessage,
+  } = useChatContext();
+
+  return (
+    <div className="custom-message-list">
+      {
+        judgeHasMoreMessage() && (
+          <div onClick={getMessageList}>加载更多</div>
+        )
+      }
+      {messageList.map((message) => {
+        const diffKeyToFlush = \`\${message.ID}-\${message.isRevoked}-\${message.isDeleted}-\${message.status}\`;
+        return (
+          <div key={diffKeyToFlush}>
+            <div key={message.nick}>{message.nick}</div>
+            <img src={message.avatar} alt="头像" />
+            {message.type === 'TIMTextElem' && <div>{message.payload.text}</div>}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+<Chat MessageList={CustomMessageList}>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+#### 自定义消息输入
+
+使用 `useMessageInputStore` 钩子函数来获取和消息输入相关的数据。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useMessageInputStore } from '@tencentcloud/chat-uikit-react';
+
+const CustomMessageInput = () => {
+  const {
+    inputValue,
+    setInputValue
+    sendTextMessage,
+  } = useMessageInputStore();
+
+  const handleSendMessage = () => {
+    sendTextMessage({
+      payload: {
+        text: inputValue,
+      },
+    });
+  };
+
+  return (
+    <div className="custom-message-list" style={{ padding: '16px', backgroundColor: '#fff' }}>
+      <input type="text" value={inputValue} onChange={e => setInputValue(e.target.value)} />
+      <button onClick={handleSendMessage}>发送</button>
+    </div>
+  );
+};
+
+<Chat
+  MessageInput={CustomMessageInput}
+>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+## 最佳实践
+
+1. **上下文使用**
+   - 在组件树的高层使用 Chat 组件
+   - 确保在渲染前有有效的会话上下文
+
+2. **组件自定义**
+   - 自定义组件会接收与默认组件相同的 props
+   - 使用提供的 hooks（如 `useChatHeaderProps`、`useChatContext`、`useMessageInputStore`）来访问聊天数据
+
+3. **样式处理**
+   - 使用 CSS modules 进行样式隔离
+   - 通过 `className` 和 `style` 属性应用自定义样式
+   - 遵循应用的设计系统规范
+
+## 相关组件
+
+- [ChatHeader（聊天头部）](?path=/docs/components-chat-chatheader--docs)
+- [MessageList（消息列表）](?path=/docs/components-chat-messagelist--docs)
+- [MessageInput（消息输入）](?path=/docs/components-chat-messageinput--docs)

package/src/components/Chat/index.ts

@@ -1,5 +1 @@
-import Server from './server';
-
-new Server();
 export * from './Chat';
-export * from './hooks/useCreateTUIChatStateContext';

package/src/components/ChatHeader/ChatHeader.stories.tsx

@@ -0,0 +1,129 @@
+/* eslint-disable import/order */
+import type { Meta, StoryObj } from '@storybook/react';
+import { TUICallKit } from '@tencentcloud/call-uikit-react';
+import { ChatHeader } from './ChatHeader';
+import { Chat } from '../Chat';
+import { useChatHeaderState, useUIManagerState } from '../../states';
+import { useEffect } from 'react';
+import { Avatar } from '../Avatar';
+import { startCall } from '../../utils/call';
+
+const meta: Meta<typeof ChatHeader> = {
+  title: 'Components/Chat/ChatHeader',
+  component: ChatHeader,
+  args: {
+    title: 'Chat Header',
+    avatar: 'https://picsum.photos/50',
+    enableUserStatus: true,
+    className: undefined,
+    style: undefined,
+  },
+  argTypes: {
+    title: {
+      control: {
+        type: 'text',
+      },
+    },
+    avatar: {
+      control: {
+        type: 'text',
+      },
+    },
+    enableUserStatus: {
+      control: {
+        type: 'boolean',
+      },
+    },
+    chatHeaderActions: {
+      control: {
+        type: 'object',
+      },
+    },
+  },
+  decorators: [
+    (Story) => {
+      const { conversationList, switchConversation } = useUIManagerState();
+
+      useEffect(() => {
+        if (conversationList?.[0]) {
+          switchConversation(conversationList[0].conversationID);
+        }
+      }, []);
+
+      return (
+        <div style={{ width: '100%' }}>
+          <Story />
+        </div>
+      );
+    },
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ChatHeader>;
+
+export const Default: Story = {
+  render: args => (
+    <div>
+      <Chat>
+        <TUICallKit style={{ position: 'fixed' }} />
+        <ChatHeader {...args} />
+      </Chat>
+    </div>
+  ),
+};
+
+export const CustomAvatar: Story = {
+  args: {
+    chatHeaderActions: ['chatSetting', 'audioCall', 'videoCall'],
+  },
+  render: (args) => {
+    // eslint-disable-next-line @typescript-eslint/no-shadow
+    function CustomAvatar() {
+      return <Avatar image="https://picsum.photos/50" shape="square" size={30} style={{ marginRight: '10px' }} />;
+    }
+    return (
+      <div>
+        <Chat>
+          <ChatHeader
+            title="Custom Avatar"
+            Avatar={CustomAvatar}
+            {...args}
+          />
+        </Chat>
+      </div>
+    );
+  },
+};
+
+export const CustomComplete: Story = {
+  render: () => {
+    const { conversation, title, avatar } = useChatHeaderState();
+
+    // 目前仅支持 C2C
+    const startVideoCall = () => {
+      startCall({
+        callType: 'C2C',
+        callMediaType: 2,
+        userIDList: [conversation?.userProfile?.userID || '1'],
+      });
+    };
+
+    return (
+      <div>
+        <TUICallKit style={{ position: 'fixed' }} />
+        <Chat>
+          <div style={{ display: 'flex', alignItems: 'center', padding: 10 }}>
+            <Avatar
+              image={avatar || 'https://picsum.photos/50'}
+              style={{ marginRight: '10px' }}
+            />
+            <span>{title || 'I am ChatHeader'}</span>
+            <button onClick={startVideoCall}>video call</button>
+          </div>
+        </Chat>
+      </div>
+    );
+  },
+};

package/src/components/ChatHeader/ChatHeader.tsx

@@ -1,50 +1,76 @@
-import React, { PropsWithChildren } from 'react';
-import { Conversation } from '@tencentcloud/chat';
-import { useTUIChatStateContext } from '../../context/ChatStateContext';
-import type { TUIChatHeaderDefaultProps } from './ChatHeaderDefault';
-import { ChatHeaderDefault } from './ChatHeaderDefault';
-
-import './styles/index.scss';
-import { useComponentContext } from '../../context';
-
-interface TUIChatHeaderProps {
-  title?: string;
-  TUIChatHeader?: React.ComponentType<TUIChatHeaderDefaultProps>;
-  conversation?: Conversation;
-  avatar?: React.ReactElement | string;
-  headerOpateIcon?: React.ReactElement | string;
-  enableCall?: boolean;
+import type React from 'react';
+import { useEffect } from 'react';
+import { TUIUserService } from '@tencentcloud/chat-uikit-engine';
+import { useMessageInputState } from 'tuikit-atomicx-react';
+import { useChatHeaderState } from '../../states';
+import ChatHeaderUI from './ChatHeaderUI';
+import type { AvatarProps } from 'tuikit-atomicx-react';
+
+interface ChatHeaderProps {
+  /** Custom title, if not provided, will use conversation info */
+  title?: string | undefined;
+  /** Custom avatar image URL */
+  avatar?: string | undefined;
+  /** Whether to show user status */
+  enableUserStatus?: boolean | undefined;
+  /** Whether to enable chat setting */
+  chatHeaderActions?: Array<'videoCall' | 'audioCall' | 'chatSetting' | 'search'> | undefined;
+  /** Custom avatar component */
+  Avatar?: React.ComponentType<AvatarProps> | undefined;
+  /** Additional class names */
+  className?: string | undefined;
+  /** Additional style */
+  style?: React.CSSProperties | undefined;
+  onSearchClick?: (() => void) | undefined;
 }
 
-function UnMemoizedTUIChatHeader<T extends TUIChatHeaderProps>(
-  props: PropsWithChildren<T>,
-): React.ReactElement {
+const ChatHeader = (props: ChatHeaderProps) => {
   const {
     title,
-    conversation: propsConversation,
-    TUIChatHeader: propTUIChatHeader,
     avatar,
-    headerOpateIcon,
-    enableCall,
+    enableUserStatus = false,
+    chatHeaderActions,
+    Avatar,
+    className,
+    style,
   } = props;
 
-  const { conversation: contextConversation } = useTUIChatStateContext('TUIChatHeader');
-  const { TUIChatHeader: ContextTUIChatHeader } = useComponentContext('TUIChatHeader');
+  const {
+    system,
+    conversation,
+    isGroup,
+    title: exceptedTitle,
+    avatar: exceptedAvatar,
+    userStatus,
+  } = useChatHeaderState();
+
+  const { isPeerTyping } = useMessageInputState();
 
-  const TUIChatHeaderUIComponent = propTUIChatHeader
-    || ContextTUIChatHeader || ChatHeaderDefault;
-  const conversation = propsConversation || contextConversation;
+  useEffect(() => {
+    TUIUserService.switchUserStatus({ displayOnlineStatus: enableUserStatus });
+  }, [enableUserStatus]);
 
   return (
-    <TUIChatHeaderUIComponent
-      title={title}
+    <ChatHeaderUI
+      isGroup={isGroup}
+      title={title || exceptedTitle || ''}
+      avatar={avatar || exceptedAvatar}
+      userStatus={userStatus}
       conversation={conversation}
-      avatar={avatar}
-      opateIcon={headerOpateIcon}
-      enableCall={enableCall}
+      isPeerTyping={isPeerTyping}
+      system={system}
+      enableUserStatus={enableUserStatus}
+      chatHeaderActions={chatHeaderActions}
+      Avatar={Avatar}
+      style={style}
+      className={className}
+      onSearchClick={props.onSearchClick}
     />
   );
-}
+};
+
+export {
+  ChatHeader,
+};
 
-export const ChatHeader = React.memo(UnMemoizedTUIChatHeader) as
-typeof UnMemoizedTUIChatHeader;
+export type { ChatHeaderProps };

package/src/components/ChatHeader/ChatHeader.zh-CN.mdx

@@ -0,0 +1,159 @@
+import { Meta, Story, Canvas, Source, ArgTypes, Markdown, Controls } from '@storybook/blocks';
+import * as ChatHeaderStories from './ChatHeader.stories';
+
+<Meta of={ChatHeaderStories} name="文档" />
+
+# ChatHeader 聊天头部组件
+
+ChatHeader 组件是 @tencentcloud/chat-uikit-react 的核心组件之一。它提供了聊天会话的头部界面，显示聊天标题、用户头像、在线状态等信息，同时也是音视频通话的入口。
+
+## 特性
+
+- 显示会话标题和头像
+- 展示用户在线状态
+- 提供音视频通话入口
+- 支持自定义操作
+- 响应式设计和可定制样式
+
+## 基础用法
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { UIKitProvider } from '@tencentcloud/base-uikit-component-react';
+import { Chat, ChatHeader, MessageList, MessageInput } from '@tencentcloud/chat-uikit-react';
+
+/**
+ * login logic
+ */
+
+function App() {
+  return (
+    <UIKitProvider theme="light" language="en-US">
+      <Chat>
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+    </UIKitProvider>
+  );
+}
+  `}
+/>
+
+<Canvas of={ChatHeaderStories.Default} />
+
+## 组件属性
+
+<Markdown>
+{`
+| 属性 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| title | string | undefined | 会话名称，如果未设置，则使用默认会话信息 |
+| avatar | string | undefined | 会话头像url |
+| enableUserStatus | boolean | true | 是否展示对端用户在线状态，只有 C2C 会话有效 |
+| chatHeaderActions | Array<'videoCall' \\| 'audioCall' \\| 'chatSetting'> | ['videoCall', 'audioCall', 'chatSetting'] | 用于对 ChatHeader 上的功能进行显示隐藏 |
+| Avatar | React.ComponentType<> | undefined | 可传入自定义头像函数 |
+| className | string | undefined | 自定义类名 |
+| style | React.CSSProperties | undefined | 内联样式对象 |
+`}
+</Markdown>
+
+## 定制化
+
+#### 示例1：自定义头像
+
+`Avatar` 属性支持传入 React 组件，下面的例子是使用已有的 `Avatar` 组件自定义头像。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { Avatar } from '@tencentcloud/chat-uikit-react';
+
+function CustomAvatar(props: React.ComponentProps<typeof Avatar>) {
+  console.log('>>> CustomAvatar props', props);
+  return <Avatar className={props.image} image={props.image} size={40} shape="square" />;
+}
+
+<Chat>
+  <ChatHeader
+    Avatar={CustomAvatar}
+  />
+</Chat>
+  `}
+/>
+
+<Canvas of={ChatHeaderStories.CustomAvatar} />
+
+#### 示例2：变更 ChatHeaderAction 功能的显隐和顺序
+
+取消展示 `videoCall` 和 `audioCall` 功能按钮。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+// 默认值：['videoCall', 'audioCall', 'chatSetting']
+
+// 仅展示 chatSetting 按钮
+<ChatHeader
+  chatHeaderActions={['chatSetting']}
+/>
+
+// 调整 chatHeaderActions 的顺序
+<ChatHeader
+  chatHeaderActions={['chatSetting', 'videoCall', 'audioCall']}
+/>
+  `}
+/>
+
+#### 示例3：完全自定义 ChatHeader
+
+<Canvas of={ChatHeaderStories.CustomComplete} />
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatHeaderStore } from '@tencentcloud/chat-uikit-react';
+
+function CustomChatHeader() {
+  const { conversation, title, avatar } = useChatHeaderStore();
+
+  // 需要集成 CallKit
+  const startVideoCall = () => {
+    startCall({
+      callType: conversation.type, // 目前仅支持 C2C
+      callMediaType: 2,
+      userIDList: [conversation?.userProfile?.userID],
+    });
+  };
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', padding: 10 }}>
+      <Avatar
+        image={avatar || 'https://picsum.photos/50'}
+        style={{ marginRight: '10px' }}
+      />
+      <span>{title || 'I am ChatHeader'}</span>
+      <button onClick={startVideoCall}>video call</button>
+    </div>
+  );
+}
+
+<Chat>
+  <CustomChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+  `}
+/>
+
+## 相关组件
+
+- [Chat（聊天）](?path=/docs/components-chat--docs)
+- [Avatar（头像）](?path=/docs/components-avatar--docs)
+- [MessageList（消息列表）](?path=/docs/components-messagelist--docs)
+- [MessageInput（消息输入）](?path=/docs/components-messageinput--docs)