By name: x-markdown version: 2.8.0 description: 当任务涉及 @ant-design/x-markdown 的 Markdown 渲染、流式输出、自定义组件映射、插件、主题或聊天富内容展示时使用。
🎯 技能定位
本技能专注解决一个问题：如何用 @ant-design/x-markdown 正确、稳定地渲染 Markdown 内容。
覆盖范围包括：
- 基础渲染与包职责边界
- LLM 流式输出与不完整语法处理
- 自定义组件映射与聊天富内容渲染
- 插件、主题与安全默认配置
目录导航
📦 包职责边界
| 层级 | 包名 | 职责 |
|---|---|---|
| UI层 | @ant-design/x |
聊天 UI、Bubble、Sender、交互组件 |
| 数据层 | @ant-design/x-sdk |
Provider、请求、流式数据流、状态管理 |
| 渲染层 | @ant-design/x-markdown |
Markdown 解析、流式渲染、插件、主题、自定义渲染 |
⚠️
x-markdown不是聊天状态管理工具。它负责把已有消息内容渲染出来，不负责请求和消息流本身。
🚀 快速决策指南
| 当你需要... | 优先阅读 | 典型结果 |
|---|---|---|
| 用最小配置渲染 Markdown | CORE.md | 用 XMarkdown 渲染基础内容 |
| 渲染 LLM 流式输出 | STREAMING.md | 正确处理 hasNextChunk、占位符、尾部指示器 |
| 把标签映射到业务组件 | EXTENSIONS.md | 为自定义标签、代码块、富内容组件建立稳定映射 |
| 增加插件或主题定制 | EXTENSIONS.md | 完成插件导入、主题类名接入、最小 CSS 覆盖 |
| 查看属性细节和默认值 | API.md | 获取 XMarkdown 与 streaming 的完整属性表 |
🛠 推荐工作流
- 先看 CORE.md，先让基础渲染跑通。
- 只有在内容是分块到达时，才继续看 STREAMING.md。
- 只有在需要自定义标签、插件、主题时，才继续看 EXTENSIONS.md。
- 属性名与默认值以 API.md 为准，不要凭记忆猜。
最小使用示例
import { XMarkdown } from '@ant-design/x-markdown';
export default () => <XMarkdown content="# Hello" />;
🚨 开发规则
components映射尽量保持稳定，不要在每次渲染时创建新的内联组件对象。- 最后一块内容必须设置
streaming.hasNextChunk = false，否则不完整占位内容不会被刷新成最终结果。 - 谨慎处理原始 HTML。如果只想保留文本展示，优先使用
escapeRawHtml。 - 如果必须渲染 HTML，请显式审查
dompurifyConfig，不要依赖模糊默认行为。 - 主题覆盖尽量最小化。先继承
x-markdown-light或x-markdown-dark，只改必要变量。 - 如果自定义组件依赖完整语法，再在
streamStatus === 'done'时执行昂贵逻辑。
🤝 技能协作
| 场景 | 推荐技能组合 | 原因 |
|---|---|---|
| 聊天中的富文本回答 | x-chat-provider → x-request → use-x-chat → x-markdown |
前三者负责数据流，x-markdown 负责最终内容渲染 |
| 内置 Provider + Markdown 回复 | x-request → use-x-chat → x-markdown |
请求配置与渲染职责分离 |
| 独立的 Markdown 页面或文档视图 | x-markdown |
不需要聊天状态管理 |
边界规则
- 适配接口格式，用
x-chat-provider - 配置传输、认证、重试、流分隔，用
x-request - 管理 React 聊天状态，用
use-x-chat - 处理 Markdown 解析、流式恢复和富组件渲染，用
x-markdown
🔗 参考资源
- CORE.md - 包职责、安装与起步、安全默认值、常见渲染模式
- STREAMING.md - 分块渲染、不完整语法恢复、loading/done 行为
- EXTENSIONS.md - 组件映射、插件、主题、自定义标签建议
- API.md - 从官方
x-markdown文档生成的 API 参考