Conversations 管理对话

用于承载用户侧发送的历史对话列表。

何时使用

• 需要对多个会话进行管理
• 查看历史会话列表

代码演示

基本

• Help Me Write
• AI Coding
• Create Image
• Deep Search

基本

基础用法。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsBasicV2' });

import {
  CodeOutlined,
  FileImageOutlined,
  FileSearchOutlined,
} from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { Flex, Switch, theme } from 'ant-design-vue';
import { computed, ref } from 'vue';

const { token } = theme.useToken();
const deepSearchChecked = ref(false);

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

const items = computed<ConversationsProps['items']>(() => [
  {
    key: 'write',
    label: 'Help Me Write',
    icon: <CodeOutlined />,
  },
  {
    key: 'coding',
    label: 'AI Coding',
    icon: <CodeOutlined />,
  },
  {
    key: 'createImage',
    label: 'Create Image',
    icon: <FileImageOutlined />,
  },
  {
    key: 'deepSearch',
    disabled: !deepSearchChecked.value,
    label: (
      <Flex gap="small" align="center">
        Deep Search
        <Switch
          size="small"
          checked={deepSearchChecked.value}
          onChange={(val: boolean) => (deepSearchChecked.value = val)}
        />
      </Flex>
    ),
    icon: <FileSearchOutlined />,
  },
]);

defineRender(() => (
  <Conversations items={items.value} defaultActiveKey="write" style={style.value} />
));
</script>

隐藏源代码

受控模式

• Help Me Write
• AI Coding
• Create Image
• Deep Search

受控模式

使用 activeKey、onActiveChange 属性，控制当前选中的会话。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsControlledModeV2' });

import {
  CodeOutlined,
  FileImageOutlined,
  FileSearchOutlined,
} from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { Button, Flex, theme } from 'ant-design-vue';
import { computed, ref } from 'vue';

const items: ConversationsProps['items'] = [
  {
    key: 'write',
    label: 'Help Me Write',
    icon: <CodeOutlined />,
  },
  {
    key: 'coding',
    label: 'AI Coding',
    icon: <CodeOutlined />,
  },
  {
    key: 'createImage',
    label: 'Create Image',
    icon: <FileImageOutlined />,
  },
  {
    key: 'deepSearch',
    label: 'Deep Search',
    icon: <FileSearchOutlined />,
  },
];

const activeKey = ref('write');
const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

defineRender(() => (
  <Flex vertical gap="small" align="flex-start">
    <Conversations
      activeKey={activeKey.value}
      onActiveChange={(v) => {
        activeKey.value = v;
      }}
      items={items}
      style={style.value}
    />
    <Flex gap="small">
      <Button onClick={() => { activeKey.value = 'write'; }}>Active First</Button>
      <Button onClick={() => { activeKey.value = 'deepSearch'; }}>Active Last</Button>
    </Flex>
  </Flex>
));
</script>

隐藏源代码

分组展示

• Today
  • This's Conversation Item 1, you can click me!
  • Conversation Item 2
  • Conversation Item 3
• Yesterday
  • Conversation Item 4
  • Conversation Item 5
  • Conversation Item 6

分组展示

使用 groupable 属性开启分组，开启后默认按 Conversation.group 字段分组。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsGroupV2' });

import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { theme } from 'ant-design-vue';
import { computed } from 'vue';

const items: ConversationsProps['items'] = Array.from({ length: 6 }).map((_, index) => ({
  key: `item${index + 1}`,
  label:
    index === 0
      ? "This's Conversation Item 1, you can click me!"
      : `Conversation Item ${index + 1}`,
  group: index < 3 ? 'Today' : 'Yesterday',
}));

const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

defineRender(() => (
  <Conversations items={items} defaultActiveKey="item1" style={style.value} groupable />
));
</script>

隐藏源代码

分组可折叠

• Today(3)
• Yesterday(3)

分组可折叠

配置 collapsible 属性为分组开启可折叠功能。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsGroupCollapsibleV2' });

import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { theme } from 'ant-design-vue';
import { computed } from 'vue';

const items: ConversationsProps['items'] = Array.from({ length: 6 }).map((_, index) => ({
  key: `item${index + 1}`,
  label:
    index === 0
      ? "This's Conversation Item 1, you can click me!"
      : `Conversation Item ${index + 1}`,
  disabled: index === 3,
  group: index < 3 ? 'Today' : 'Yesterday',
}));

const groupable: ConversationsProps['groupable'] = {
  label: (group, { groupInfo }) => (
    <>
      {group}({groupInfo.data.length})
    </>
  ),
  collapsible: true,
};

const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

defineRender(() => (
  <Conversations items={items} defaultActiveKey="item1" style={style.value} groupable={groupable} />
));
</script>

隐藏源代码

受控的分组可折叠

• Today
  • Conversation Item 1
  • Conversation Item 4
  • Conversation Item 7
• Yesterday
• Historical chats

受控的分组可折叠

受控的分组可折叠。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsControlledCollapsibleV2' });

import { FieldTimeOutlined } from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { Flex, theme } from 'ant-design-vue';
import { computed, ref } from 'vue';

const groupName = ['Today', 'Yesterday', 'Historical chats'];
const items: ConversationsProps['items'] = Array.from({ length: 9 }).map((_, index) => ({
  key: `item${index + 1}`,
  label: `Conversation Item ${index + 1}`,
  group: groupName[index % 3],
}));

const expandedKeys = ref(['Yesterday']);
const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

defineRender(() => {
  const groupable: ConversationsProps['groupable'] = {
    label: (group) => (
      <Flex gap="small">
        <FieldTimeOutlined />
        {group}
      </Flex>
    ),
    collapsible: (group) => group !== 'Today',
    expandedKeys: expandedKeys.value,
    onExpand: (keys) => { expandedKeys.value = keys; },
  };

  return (
    <Conversations items={items} defaultActiveKey="item1" style={style.value} groupable={groupable} />
  );
});
</script>

隐藏源代码

会话操作

自定义操作

• Conversation Item 1
• Conversation Item 2
• Conversation Item 3
• Conversation Item 4

自定义操作

自定义菜单入口。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsMenuTriggerV2' });

import {
  DeleteOutlined,
  EditOutlined,
  PlusSquareOutlined,
  ShareAltOutlined,
  StopOutlined,
} from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import type { MenuProps } from 'ant-design-vue';
import { theme } from 'ant-design-vue';
import { computed } from 'vue';

const items: ConversationsProps['items'] = Array.from({ length: 4 }).map((_, index) => ({
  key: `item${index + 1}`,
  label: `Conversation Item ${index + 1}`,
  disabled: index === 3,
}));

const menuItems: MenuProps['items'] = [
  {
    label: 'Rename',
    key: 'Rename',
    icon: <EditOutlined />,
  },
  {
    label: 'Share',
    key: 'Share',
    icon: <ShareAltOutlined />,
  },
  {
    type: 'divider',
  },
  {
    label: 'Archive',
    key: 'Archive',
    icon: <StopOutlined />,
    disabled: true,
  },
  {
    label: 'Delete Chat',
    key: 'deleteChat',
    icon: <DeleteOutlined />,
    danger: true,
  },
];

const menuConfig: ConversationsProps['menu'] = (conversation) => ({
  trigger:
    conversation.key === 'item2' ? (
      <ShareAltOutlined
        onClick={(e: MouseEvent) => {
          e.stopPropagation();
          console.log(`Share ${conversation.key}`);
        }}
      />
    ) : (
      <PlusSquareOutlined
        onClick={(e: MouseEvent) => {
          e.stopPropagation();
        }}
      />
    ),
  items: conversation.key !== 'item2' ? menuItems : [],
  onClick: (itemInfo) => {
    console.log(`Click ${conversation.key}-${itemInfo.key}`);
    itemInfo.domEvent.stopPropagation();
  },
});

const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

defineRender(() => (
  <Conversations defaultActiveKey="item1" menu={menuConfig} items={items} style={style.value} />
));
</script>

隐藏源代码

新对话

• Help Me Write
• AI Coding
• Create Image
• Deep Search
• Today
  • Conversation Item 1

新对话

通过 creation 属性配置新建对话按钮。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsNewChatV2' });

import {
  CodeOutlined,
  FileImageOutlined,
  FileSearchOutlined,
} from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { theme } from 'ant-design-vue';
import { ref, computed } from 'vue';

const agentItems: ConversationsProps['items'] = [
  {
    key: 'write',
    label: 'Help Me Write',
    icon: <CodeOutlined />,
  },
  {
    key: 'coding',
    label: 'AI Coding',
    icon: <CodeOutlined />,
  },
  {
    key: 'createImage',
    label: 'Create Image',
    icon: <FileImageOutlined />,
  },
  {
    key: 'deepSearch',
    label: 'Deep Search',
    icon: <FileSearchOutlined />,
  },
  {
    type: 'divider',
  },
];

const historicalItems = ref<ConversationsProps['items']>([
  {
    key: 'item1',
    label: 'Conversation Item 1',
    group: 'Today',
  },
]);

const items = computed(() => [...agentItems!, ...historicalItems.value!]);

const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

const newChatClick = () => {
  historicalItems.value = [
    ...historicalItems.value!,
    {
      key: `item${historicalItems.value!.length + 1}`,
      label: `Conversation Item ${historicalItems.value!.length + 1}`,
      group: 'Today',
    },
  ];
};

defineRender(() => (
  <Conversations
    creation={{ onClick: newChatClick }}
    items={items.value}
    defaultActiveKey="write"
    style={style.value}
    groupable
  />
));
</script>

隐藏源代码

自定义新对话

• Help Me Write
• AI Coding
• Create Image
• Deep Search
• Today
  • Conversation Item 1

自定义新对话

自定义新对话按钮的图标、文案和对齐方式。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsCustomNewChatV2' });

import {
  AppstoreAddOutlined,
  CodeOutlined,
  FileImageOutlined,
  FileSearchOutlined,
} from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { theme } from 'ant-design-vue';
import { ref, computed } from 'vue';

const agentItems: ConversationsProps['items'] = [
  {
    key: 'write',
    label: 'Help Me Write',
    icon: <CodeOutlined />,
  },
  {
    key: 'coding',
    label: 'AI Coding',
    icon: <CodeOutlined />,
  },
  {
    key: 'createImage',
    label: 'Create Image',
    icon: <FileImageOutlined />,
  },
  {
    key: 'deepSearch',
    label: 'Deep Search',
    icon: <FileSearchOutlined />,
  },
  {
    type: 'divider',
  },
];

const historicalItems = ref<ConversationsProps['items']>([
  {
    key: 'item1',
    label: 'Conversation Item 1',
    group: 'Today',
  },
]);

const items = computed(() => [...agentItems!, ...historicalItems.value!]);

const { token } = theme.useToken();

const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

const newChatClick = () => {
  historicalItems.value = [
    ...historicalItems.value!,
    {
      key: `item${historicalItems.value!.length + 1}`,
      label: `Conversation Item ${historicalItems.value!.length + 1}`,
      group: 'Today',
    },
  ];
};

defineRender(() => (
  <Conversations
    creation={{
      label: 'Create a new chat',
      align: 'start',
      icon: <AppstoreAddOutlined />,
      onClick: newChatClick,
    }}
    items={items.value}
    defaultActiveKey="write"
    style={style.value}
    groupable
  />
));
</script>

隐藏源代码

快捷键

Switch sessions with Alt/⌥ + number, and create a chat with Win/⌘ + K.

• Help Me Write
• AI Coding
• Create Image
• Deep Search
• Today
  • Conversation Item 1

快捷键

使用 shortcutKeys 切换会话，或触发新建对话。也可以在 XProvider 的 conversations.shortcutKeys 里配置全局快捷键。

<script setup lang="tsx">
defineOptions({ name: 'AXConversationsShortcutKeysV2' });

import {
  CodeOutlined,
  FileImageOutlined,
  FileSearchOutlined,
} from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations } from 'ant-design-x-vue';
import { Tag, theme, Typography } from 'ant-design-vue';
import { computed, ref } from 'vue';

// KeyboardEvent.keyCode. K is 75, matching @ant-design/x Conversations demos.
const KeyK = 75;

const agentItems: ConversationsProps['items'] = [
  { key: 'write', label: 'Help Me Write', icon: <CodeOutlined /> },
  { key: 'coding', label: 'AI Coding', icon: <CodeOutlined /> },
  { key: 'createImage', label: 'Create Image', icon: <FileImageOutlined /> },
  { key: 'deepSearch', label: 'Deep Search', icon: <FileSearchOutlined /> },
];

const historicalItems = ref<ConversationsProps['items']>([
  { key: 'item1', label: 'Conversation Item 1', group: 'Today' },
]);

const items = computed(() => [...agentItems, ...(historicalItems.value || [])]);

const { token } = theme.useToken();
const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

const newChatClick = () => {
  const next = (historicalItems.value?.length || 0) + 1;
  historicalItems.value = [
    ...(historicalItems.value || []),
    {
      key: `item${next}`,
      label: `Conversation Item ${next}`,
      group: 'Today',
    },
  ];
};

defineRender(() => (
  <>
    <Typography.Paragraph>
      Switch sessions with <Tag>Alt/⌥</Tag> + <Tag>number</Tag>, and create a
      chat with <Tag>Win/⌘</Tag> + <Tag>K</Tag>.
    </Typography.Paragraph>
    <Conversations
      creation={{ onClick: newChatClick }}
      items={items.value}
      defaultActiveKey="write"
      style={style.value}
      groupable
      shortcutKeys={{
        creation: ['Meta', KeyK],
        items: ['Alt', 'number'],
      }}
    />
  </>
));
</script>

隐藏源代码

滚动加载

API

ConversationsProps

属性	说明	类型	默认值	版本
activeKey	当前选中的值	string	-	-
defaultActiveKey	默认选中值	string	-	-
items	会话列表数据源	ItemType[]	-	-
onActiveChange	选中变更回调	(value: string) => void	-	-
menu	会话操作菜单	MenuProps | ((value: ConversationItemType) => MenuProps)	-	-
groupable	是否支持分组, 开启后默认按 Conversation.group 字段分组	boolean | GroupableProps	-	-
creation	新建对话按钮的配置	CreationProps	-	v2
shortcutKeys	快捷键。creation 触发新建，items 按顺序选中会话。修饰键为 'Ctrl' | 'Alt' | 'Meta' | 'Shift'，最后一个键是 KeyboardEvent.keyCode 或 'number'（数字键 1–9）	{ creation?: ShortcutKeys; items?: ShortcutKeys | ShortcutKeys[] }	-	v2
styles	语义化结构 style	Record<'root' | 'creation' | 'group' | 'item', CSSProperties>	-	-
classNames	语义化结构 className	Record<'root' | 'creation' | 'group' | 'item', string>	-	-
rootClassName	根节点类名	string	-	-

ItemType

ItemType = ConversationItemType | DividerItemType

ConversationItemType (Conversation)

属性	说明	类型	默认值	版本
key	唯一标识	string	-	-
label	会话名称	VNode | string	-	-
group	会话分组类型，与 ConversationsProps.groupable 联动	string	-	-
icon	会话图标	VNode	-	-
disabled	是否禁用	boolean	-	-

DividerItemType

属性	说明	类型	默认值	版本
type	固定值 'divider'	'divider'	-	v2
key	唯一标识	string	-	v2
dashed	是否虚线	boolean	-	v2

GroupableProps

属性	说明	类型	默认值	版本
label	自定义分组标签渲染	VNode | string | ((group: string, info: { groupInfo }) => VNode)	-	-
collapsible	是否可折叠	boolean | ((group: string) => boolean)	-	v2
defaultExpandedKeys	初始化展开的分组	string[]	-	v2
expandedKeys	当前展开的分组（受控）	string[]	-	v2
onExpand	展开分组变化回调	(expandedKeys: string[]) => void	-	v2

CreationProps

属性	说明	类型	默认值	版本
label	按钮文案。函数入参包含 shortcutKeyInfo 和 components.CreationLabel	VNode | string | ((info) => VNode)	语言包，英文 New chat	v2
icon	按钮图标	VNode | (() => VNode)	PlusOutlined	v2
align	对齐方式	'start' | 'center' | 'end'	'center'	v2
disabled	是否禁用	boolean	false	v2
onClick	点击回调	(event?: MouseEvent) => void	-	v2

MenuProps

继承 antdv MenuProps 属性。

属性	说明	类型	默认值	版本
trigger	自定义 menu 触发器	VNode | ((conversation: ConversationItemType, info: { originNode: VNode }) => VNode)	-	-
getPopupContainer	菜单渲染父节点	(triggerNode: HTMLElement) => HTMLElement	-	-

Semantic DOM

• Help Me Write
• AI Coding
• Create Image
• Deep Search
• Today
  • Conversation Item 1
  • Conversation Item 2

• root

  管理对话根节点

• item

  管理对话子节点

• creation

  创建对话

• group

  管理对话分组

主题变量（Design Token）

Token	说明	类型	默认值
creationBgColor	新会话按钮背景颜色	string	rgba(primaryColor, 0.15)
creationBorderColor	新会话按钮边框颜色	string	rgba(primaryColor, 0.22)
creationHoverColor	新会话按钮悬浮态背景颜色	string	rgba(primaryColor, 0.25)
shortcutKeyTextColor	快捷键标识字体颜色	string	rgba(primaryColor, 0.65)

贡献者

贡献者

正在加载贡献者信息...