x-markdown

🎯 技能定位

此技能专注于一项工作：使用 @ant-design/x-markdown 正确、稳定地渲染 Markdown。

涵盖内容：

• 基础渲染与包的职责边界
• 大模型流式输出与不完整语法处理
• 为丰富的聊天或数据展示区块自定义组件映射
• 插件、主题与安全的默认渲染设置

目录

• 📦 包的职责边界
• 🚀 快速入门决策指南
• 🛠 推荐工作流
• 🚨 开发规则
• 🤝 技能协作
• 🔗 参考资源

📦 包的职责边界

层级	包	职责
UI 层	@ant-design/x	聊天 UI、气泡列表、发送者、丰富的交互组件
数据层	@ant-design/x-sdk	提供程序、请求、流式数据流、状态管理
渲染层	@ant-design/x-markdown	Markdown 解析、流式渲染、插件、主题、自定义渲染器

⚠️ x-markdown 不是聊天状态工具。只有在 @ant-design/x 和 @ant-design/x-sdk 已经生成消息数据后，才使用它来渲染内容。

🚀 快速入门决策指南

如果你需要……	请先阅读	常见结果
以最精简的配置渲染 Markdown	CORE.md	XMarkdown 使用基本样式渲染可信内容
渲染大模型流式数据块	STREAMING.md	正确设置 hasNextChunk、占位符、尾部指示器和加载状态
将标签替换为业务组件	EXTENSIONS.md	为自定义标签和代码区块配置稳定的 components 映射
添加插件或覆盖主题	EXTENSIONS.md	插件导入、主题类配置、精简的 CSS 覆盖
查看属性详情和默认值	API.md	XMarkdown 和流式选项的完整属性表

🛠 推荐工作流

1. 从 CORE.md 开始，先让基本渲染正常运行。
2. 仅当内容以数据块形式逐段到达时，才添加 STREAMING.md。
3. 需要自定义标签、插件、语法区块或主题时，添加 EXTENSIONS.md。
4. 使用 API.md 确认属性名称和默认值，不要凭猜测。

最简配置提醒

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

export default () => <XMarkdown content="# Hello" />;

🚨 开发规则

• 优先使用稳定的 components 对象。不要在每次渲染时都创建新的内联组件映射。
• 最后一个数据块应使用 streaming.hasNextChunk = false，否则不完整的占位符不会刷新为最终内容。
• 谨慎处理原始 HTML。若应将原始 HTML 保留为可见文本，请优先使用 escapeRawHtml。
• 如果必须渲染原始 HTML，请明确并精简地配置 dompurifyConfig。
• 尽量少覆盖主题。以 x-markdown-light 或 x-markdown-dark 为基础，只覆盖所需变量。
• 如果自定义组件依赖完整语法，请根据 streamStatus === 'done' 进行分支处理。

🤝 技能协作

场景	推荐的技能组合	原因
聊天中的丰富助手回复	x-chat-provider → x-request → use-x-chat → x-markdown	提供程序和请求负责处理数据流，x-markdown 负责最终渲染
使用内置提供程序并返回 Markdown 回复	x-request → use-x-chat → x-markdown	将请求配置与渲染职责分开
独立的 Markdown 页面或文档查看器	仅使用 x-markdown	无需聊天数据流

职责边界规则

• 调整 API 格式时使用 x-chat-provider。
• 配置传输、身份验证、重试或流式分隔符时使用 x-request。
• 在 React 中管理聊天状态时使用 use-x-chat。
• 内容本身需要 Markdown 解析、流式恢复或丰富的组件渲染时使用 x-markdown。

🔗 参考资源

• CORE.md - 包边界、安装/设置、安全默认值、常见渲染模式
• STREAMING.md - 分块渲染、不完整语法恢复、加载与完成状态的行为
• EXTENSIONS.md - 组件、插件、主题、自定义标签指南
• API.md - 根据官方 x-markdown 文档生成的 API 参考

官方文档

• XMarkdown 简介
• XMarkdown 示例
• XMarkdown 流式传输
• XMarkdown 组件
• XMarkdown 插件
• XMarkdown 主题