介绍

流式友好、可扩展的 Markdown 渲染组件。对齐 @ant-design/x-markdown@2.0.0 的核心能力：公式、代码高亮、Mermaid、流式语法与自定义组件映射。

何时使用

• 在对话气泡、消息等场景中渲染 Markdown 内容
• 需要流式输出时配合 streaming 与 useStreaming
• 需要自定义标题、代码块、Mermaid 等节点时使用 components 映射

更细的页面：

• 代码示例与完整 API
• 插件：Latex、HighlightCode、Mermaid、自定义 transform
• 主题 light / dark
• 流式语法
• 组件映射总览

代码演示

基本用法

# Hello World ### Welcome to XMarkdown! - Item 1 - Item 2 - Item 3 ```js const a = 1; ```

Hello World

Welcome to XMarkdown!

• Item 1
• Item 2
• Item 3

const a = 1;

基本用法

通过 content 传入 Markdown 字符串即可渲染。

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

import { computed, ref } from 'vue';
import { Flex, Input, theme } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import '@ant-design-x-vue/x-markdown/themes/light.css';
import '@ant-design-x-vue/x-markdown/themes/dark.css';
import { isDarkColor } from '../_shared/playground-shell';

const { token } = theme.useToken();
const markdownClass = computed(() => (
  isDarkColor(token.value.colorBgContainer) ? 'x-markdown-dark' : 'x-markdown-light'
));

const content = ref(`# Hello World

### Welcome to XMarkdown!

- Item 1
- Item 2
- Item 3

\`\`\`js
const a = 1;
\`\`\`
`);

defineRender(() => (
  <Flex vertical gap={16}>
    <Input.TextArea v-model:value={content.value} rows={8} />
    <div style={{
      border: `1px solid ${token.value.colorBorderSecondary}`,
      borderRadius: '4px',
      padding: '16px',
      minHeight: '120px',
    }}>
      <XMarkdown className={markdownClass.value} content={content.value} />
    </div>
  </Flex>
));
</script>

隐藏源代码

自定义组件映射

# Custom Blue Title ## Normal H2 Paragraph with **bold** and *italic*.

Custom Blue Title

Normal H2

Paragraph with bold and italic.

自定义组件映射

通过 components 将 HTML 标签映射为自定义 Vue 组件，可接收 domNode、streamStatus、children 等 props。

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

import { computed, ref, h } from 'vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import type { ComponentProps } from '@ant-design-x-vue/x-markdown';
import { Flex, Input, theme } from 'ant-design-vue';

const { token } = theme.useToken();
const wrapStyle = computed(() => ({
  border: `1px solid ${token.value.colorBorderSecondary}`,
  borderRadius: '4px',
  padding: '16px',
  minHeight: '100px',
}));

const CustomH1 = (props: ComponentProps) => {
  return h('h1', { style: { color: '#1890ff' }, ...props }, props.children);
};

const components = {
  h1: CustomH1,
};

const content = ref(`# Custom Blue Title

## Normal H2

Paragraph with **bold** and *italic*.
`);

defineRender(() => (
  <Flex vertical gap={16}>
    <Input.TextArea v-model:value={content.value} rows={6} />
    <div style={wrapStyle.value}>
      <XMarkdown content={content.value} components={components} />
    </div>
  </Flex>
));
</script>

隐藏源代码

流式渲染

Status: idle

流式渲染

使用 streaming 标识流式状态，配合 useStreaming 处理内容与状态。

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

import { computed, ref } from 'vue';
import { XMarkdown, useStreaming } from '@ant-design-x-vue/x-markdown';
import { Button, Flex, Space, theme } from 'ant-design-vue';

const { token } = theme.useToken();
const wrapStyle = computed(() => ({
  border: `1px solid ${token.value.colorBorderSecondary}`,
  borderRadius: '4px',
  padding: '16px',
  minHeight: '120px',
}));

const fullContent = `# Streaming Demo

Content appears **progressively**.

- Step 1
- Step 2
- Step 3
`;

const content = ref('');
const streaming = ref(false);
const { status, displayedContent } = useStreaming({
  content,
  streaming,
  onComplete: () => console.log('stream complete'),
});

const startStream = () => {
  content.value = '';
  streaming.value = true;
  let i = 0;
  const timer = setInterval(() => {
    if (i < fullContent.length) {
      content.value = fullContent.slice(0, i + 3);
      i += 3;
    } else {
      streaming.value = false;
      clearInterval(timer);
    }
  }, 50);
};

defineRender(() => (
  <Flex vertical gap={16}>
    <Space>
      <Button type="primary" onClick={startStream}>
        Start streaming
      </Button>
      <span>Status: {status.value}</span>
    </Space>
    <div style={wrapStyle.value}>
      <XMarkdown content={displayedContent.value} streaming={streaming.value} />
    </div>
  </Flex>
));
</script>

隐藏源代码

API

完整表格（含 children、paragraphTag、openLinksInNewTab、dompurifyConfig、rootClassName、style 等）见 代码示例 · API。此处列出常用字段：

XMarkdownProps

属性	说明	类型	默认值
content	Markdown 内容	string	-
children	content 的别名	string	-
streaming	流式配置。布尔值表示是否仍在输出；对象支持 hasNextChunk、enableAnimation、animationConfig、incompleteMarkdownComponentMap	boolean | StreamingOption	-
components	将标签名映射为自定义 Vue 组件（如 h1、pre、code、mermaid、think）	Record<string, Component>	-
paragraphTag	段落 HTML 标签，避免自定义块级组件嵌套非法	string	'p'
plugins	插件列表，在解析前对 content 执行 transform	any[]	-
config	marked 解析配置	MarkedConfig	-
openLinksInNewTab	给所有链接加 target="_blank"	boolean	false
dompurifyConfig	DOMPurify 消毒配置	DOMPurify.Config	-
className	根节点类名	string	-
rootClassName	className 的别名	string	-
style	根节点内联样式	CSSProperties	-

StreamingOption / AnimationConfig

字段	说明	默认
hasNextChunk	后面还有 chunk。未闭合语法先不按完整 Markdown 解析	false
enableAnimation	文本淡入	false
animationConfig.fadeDuration	淡入时长（毫秒）	200
animationConfig.easing	缓动	'ease-in-out'
incompleteMarkdownComponentMap	未完成语法要用的组件名（token 为 link / image / html / emphasis / list / table）	{}

ComponentProps（自定义组件入参）

属性	说明	类型
domNode	解析后的 DOM 节点信息（name、attribs、children）	DOMNode
streamStatus	自定义标签尚未闭合时为 'loading'，闭合后为 'done'。code 可读 data-state	'loading' | 'done'
block	仅 code：data-block="true" 时为块级代码	boolean
children	子内容（VNode 或文本）	VNode[] | string
其余	标准 HTML 属性及 data-* 等	Record<string, any>

useStreaming

用于配合流式内容的组合式函数。

参数	说明	类型
content	内容 ref	Ref<string>
streaming	是否流式中 ref（可选）	Ref<boolean>
onComplete	流式结束回调	() => void

返回值	说明	类型
displayedContent	当前展示内容	Ref<string>
status	状态：idle | streaming | complete | error	Ref<StreamStatus>
isStreaming	是否流式中	Ref<boolean>

导出

• XMarkdown - 主组件
• AnimationText - 文本淡入组件（streaming.enableAnimation）
• useStreaming - 流式组合式函数
• parseMarkdown(content, config?) - 解析 Markdown 为 HTML
• htmlToVNode(html, options?) - 将 HTML 转为 VNode（支持 components、streamStatus）