x-components

🎯 技能定位

本技能涵盖 @ant-design/x 中的所有 UI 组件——这是一个基于 RICH 交互范式构建 AI 驱动聊天界面的 React 组件库。

涵盖组件选择、API 用法、组合模式和常见反模式。

前置条件：本技能仅处理 UI。有关数据流和流式传输，请参阅 use-x-chat、x-chat-provider、x-request 技能。

目录

• 📦 软件包概览
• 🗂️ 组件分组
• 🚀 快速入门决策指南
• 🛠 推荐工作流
• 🚨 开发规则
• 🤝 技能协作
• 🔗 参考资源

📦 软件包概览

软件包	职责
@ant-design/x	本技能中的所有 UI 组件
@ant-design/x-sdk	数据提供程序、请求、流式传输状态——不在本技能范围内
@ant-design/x-markdown	Bubble 内的 Markdown 渲染——参见 x-markdown 技能

npm install @ant-design/x

@ant-design/x 扩展自 antd。如果使用 ConfigProvider，请将其替换为 XProvider。

🗂️ 组件分组

基于 RICH 交互范式：

阶段	组件
通用	Bubble、Bubble.List、Conversations、Notification
唤醒	Welcome、Prompts
表达	Sender、Attachments、Suggestion
确认	Think、ThoughtChain
反馈	Actions、FileCard、Sources、CodeHighlighter、Mermaid、Folder
全局	XProvider

🚀 快速入门决策指南

如果你需要……	首先阅读
渲染聊天消息气泡	COMPONENTS.md → Bubble
构建聊天输入框	COMPONENTS.md → Sender
列出并切换对话	COMPONENTS.md → Conversations
展示 AI 思考过程	COMPONENTS.md → ThoughtChain / Think
在消息下方添加操作按钮	COMPONENTS.md → Actions
构建欢迎页／入门引导页	COMPONENTS.md → Welcome + Prompts
在输入框中展示文件附件	COMPONENTS.md → Attachments
展示来源引用	COMPONENTS.md → Sources
添加快捷命令建议	COMPONENTS.md → Suggestion
展示分层文件／文件夹树	COMPONENTS.md → Folder
接入完整聊天页面	PATTERNS.md
查询特定属性	API.md

🛠 推荐工作流

1. 针对各个交互阶段，从 COMPONENTS.md 中选择组件。
2. 使用 PATTERNS.md 了解如何将组件组合成完整页面。
3. 使用 XProvider 包裹应用根节点（替代 antd 的 ConfigProvider），以配置语言区域、主题和快捷键。
4. 使用 API.md 查找准确的属性名称——不要猜测。

最简完整页面示例

import { XProvider, Welcome, Prompts, Bubble, Sender } from '@ant-design/x';

export default () => (
  <XProvider>
    <Welcome title="Hello!" description="How can I help you?" />
    <Prompts
      items={[{ key: '1', label: 'What can you do?' }]}
      onItemClick={(info) => console.log(info.data.label)}
    />
    <Bubble.List items={[{ key: '1', content: 'Hello World', placement: 'end' }]} />
    <Sender onSubmit={(msg) => console.log(msg)} />
  </XProvider>
);

🚨 开发规则

• 始终在应用根节点使用 XProvider — 它取代 antd 的 ConfigProvider，并启用语言区域、方向和 x 专属快捷键。
• 在循环中使用 Bubble.List，而不是 Bubble — Bubble.List 可处理滚动锚定、自动滚动和基于角色的布局；手动映射 Bubble 会丢失这些功能。
• 保持 Bubble 和 Bubble.List 的 components 属性稳定 — 内联创建对象会导致重新渲染并重置输入动画。
• 流式传输期间设置 streaming={true}，在最后一个数据块设置 streaming={false} — 一直保持为 true 会导致完成状态异常。
• ThoughtChain 与 Think：多步骤工具／Agent 调用链使用 ThoughtChain；可折叠的单块推理展示使用 Think。
• Actions.Copy、Actions.Feedback、Actions.Audio 是预设子组件 — 优先使用它们，而不是自行构建等效组件。
• Sender 的 onSubmit 与 onChange：点击发送按钮或按 Enter 键时会触发 onSubmit；每次按键时都会触发 onChange — 不要混淆两者。
• 切勿在 Bubble 的 content 字符串中渲染 Mermaid 或 CodeHighlighter — 请改用 contentRender 或 components 映射。

🤝 技能协作

场景	技能组合
完整的 AI 聊天应用	x-chat-provider → x-request → use-x-chat → x-components → x-markdown
仅构建 UI 结构	仅使用 x-components
气泡回复中的 Markdown	x-components + x-markdown
仅处理流式数据流	use-x-chat + x-request

🔗 参考资源

• COMPONENTS.md — 逐个介绍组件的指南，包含用法、关键属性和示例
• PATTERNS.md — 整页组合模式和集成方案
• API.md — 根据官方组件文档自动生成的属性参考 — 涵盖全部 17 个组件

官方文档

• Ant Design X 概览
• Bubble
• Sender
• Conversations
• ThoughtChain
• Actions
• Welcome
• Prompts
• Attachments
• Sources
• Suggestion
• Think
• Folder
• XProvider