[RFC] New Component - Conversations

[YumoImer]

Summary

Conversations 组件用于管理、查看会话列表

Motivation

在传统 IM 应用、AI Agent 对话类应用中，会话列表是必不可少的组件，用于给用户提供管理、查看会话的交互。一些例子：

最基础的会话列表组件具备如下功能：

• 管理：编辑会话名称、删除会话
• 查看：滚动加载

API

ConversationProps

export type GroupType = string;

/**
 * @desc 会话数据
 * @descEN Conversation data
 */
export interface ConversationProps extends Record<string, any> {
  /**
   * @desc 唯一标识
   * @descEN Unique identifier
   */
  key: string;

  /**
   * @desc 会话名称
   * @descEN Conversation name
   */
  label?: React.ReactNode;

  /**
   * @desc 会话时间戳
   * @descEN Conversation timestamp
   */
  timestamp?: number;

  /**
   * @desc 会话分组类型，与 {@link ConversationsProps.groupable} 联动
   * @descEN Conversation type
   */
  group?: GroupType;

  /**
   * @desc 会话图标
   * @descEN conversation icon
   */
  icon?: React.ReactNode;

  /**
   * @desc 是否禁用
   * @descEN Whether to disable
   */
  disabled?: boolean;
};

ConversationsProps

/**
 * @desc 会话列表组件参数
 * @descEN Props for the conversation list component
 */
export interface ConversationsProps extends BaseProps, React.HTMLAttributes<HTMLUListElement> {

  /**
   * @desc 会话列表数据源
   * @descEN Data source for the conversation list
   */
  data?: ConversationProps[];

  /**
   * @desc 当前选中的值
   * @descEN Currently selected value
   */
  activeKey?: ConversationProps['key'];

  /**
   * @desc 默认选中值
   * @descEN Default selected value
   */
  defaultActiveKey?: ConversationProps['key'];

  /** 
   * @desc 选中变更回调
   * @descEN Callback for selection change
   */
  onActiveChange?: (value: ConversationProps['key'], preValue: ConversationProps['key']) => void;

  /**
   * @desc 会话操作菜单
   * @descEN Operation menu for conversations
   */
  menu?: MenuProps | ((value: ConversationProps) => MenuProps);

  /**
   * @desc 是否支持分组, 开启后默认按 {@link ConversationProps.group} 字段分组
   * @descEN If grouping is supported, it defaults to the {@link ConversationProps.group} field
   */
  groupable?: boolean | {
    /**
     * @desc 分组排序函数
     * @descEN Group sorter
     */
    sort?: (a: GroupType, b: GroupType) => number;
    /**
     * @desc 语义化自定义渲染
     * @descEN Semantic custom rendering
     */
    components?: Partial<Record<'title', React.ComponentType<{ group: GroupType }>>>;
  };

  /** 
   * @desc 语义化结构 style
   * @descEN Semantic structure styles
   */
  styles?: Partial<Record<'list' | 'item', React.CSSProperties>>;

  /** 
   * @desc 语义化结构 className
   * @descEN Semantic structure class names
   */
  classNames?: Partial<Record<'list' | 'item', string>>;
};

Basic Example

基础使用

import { Conversations } from '@ant-design/x';

export default () => (
  <Conversations
    data={[
      {
        key: 'demo1',
        label: '示例会话1',
        timestamp: 1722321645932,
        pinned: true,
      },
      {
        key: 'demo2',
        label: '示例会话2',
        timestamp: 1722321645934
      },
    ]}
  />
);

受控模式

import { useState } from 'react';
import { Conversations } from '@ant-design/x';

export default () => {
    const [activeKey, setActiveKey] = useState();

    return (
        <Conversations
            activeKey={activeKey}
            onActiveChange={(v) => setActiveKey(v)}
            data={[
              {
                key: 'demo1',
                label: '示例会话1',
                timestamp: 1722321645932
              },
              {
                key: 'demo2',
                label: '示例会话2',
                timestamp: 1722321645934
              },
            ]}
       />
    );
};

使用 groupable 属性开启分组

import React from 'react';
import type { ConversationProps } from '@ant-design/x';
import { Conversations } from '@ant-design/x';

const data: ConversationProps[] = [
  {
    key: 'demo1',
    label: 'What is Ant Design X ?',
    timestamp: 794620800,
    group: 'pinned',
  },
  {
    key: 'demo2',
    label: <div>Getting Started: <a target="_blank" href='https://ant-design.antgroup.com/index-cn' rel="noreferrer">Ant Design !</a></div>,
    timestamp: 794620900,
    group: 'pinned',
  },
  {
    key: 'demo4',
    label: 'In Docker, use 🐑 Ollama and initialize',
    timestamp: 794621100,
  },
  {
    key: 'demo5',
    label: 'Expired, please go to the recycle bin to check',
    timestamp: 794621200,
  },
];

const App = () => (
  <Conversations
    groupable
    defaultActiveKey="demo1"
    data={data}
  />
);

export default App;

配置操作菜单

import { Conversations } from '@ant-design/x';

export default () => {

    return (
        <Conversations
            menu={{
               items: [
                   {
                      label: '重命名',
                      key: 'mod',
                  },
                  {
                      label: '删除',
                      key: 'delete',
                  },
               ],
               onClick: () => {}
            }}
            data={[
              {
                key: 'demo1',
                label: '示例会话1',
                timestamp: 1722321645932
              },
              {
                key: 'demo2',
                label: '示例会话2',
                timestamp: 1722321645934
              },
            ]}
       />
    );
};

[ONLY-yours]

要不要加入 star 的逻辑？ star 的默认放在最上层

[YumoImer]

感觉可以有，在ItemProps里加个置顶属性？

[zombieJ]

• dataSource 直接叫 data 吧，过去叫 dataSource 是希望有 request 能力，但是实际上都得业务封装，并没有 source 的能力。
• 一般输入数组件才会有 value，展示组件一般叫 activeKey
• isSortByTime 改名 sorter，支持默认的 ChatList.SORT_BY_TIME
• components 一般定义式 Record<ComponentName, React.ComponentType> 不是一个 render props

[ONLY-yours]

data 的每个 ChatListItemProps 应该除了这三个外，还支持任意 key value 对的塞入，用户总是喜欢自定义塞各种属性进去

[ONLY-yours]

isSortByTime 这个 感觉可以升级为 sort 么？过滤方式让用户自己处理如何

[YumoImer]

这里我写的时候还真犹豫了下，sortType?: 'timestamp' | 'xxx' 但感觉目前只有timestamp ，考虑扩展的话可以按type这种来

[YumoImer]

Resolved.

同上：isSortByTime?: boolean 改为 sorter?: SorterType

[afc163]

不要用 isXxx 的语法，这样这个属性永远只能是 boolean。

参考 antd 用 xxxable 的命名风格，一开始可以只支持 boolean，后续可扩展为对象以支持更多功能 xxxable: { ... }.

[afc163]

如果语义是会话的话，这个组件叫 Conversations 会不会更好？

[YumoImer]

复数用 S 或者 List 感觉要统一下，这块一会商量下。

或者叫 Session 更加简短一些，一会发个投票。