1.1 多模态 AI 带来的新需求#

在日常使用 AI 的过程中，你可能已经习惯了这样的交互：

• 一段 Markdown 文本流式返回
• 其中夹杂代码、列表、表格、图片、公式、提示块（admonition）等
• 回复内容还可能随着上下文不断追加，用户一边阅读、一边选择、一边复制代码

这与传统「一次性输出完整 HTML」完全不同：

• 内容是流式的（Streaming）：分段到达，需要增量渲染
• 结构是富文本的（Rich Text）：需要细粒度的语义化渲染，而不仅仅是 innerHTML
• 交互是实时的：用户正在选择、滚动、聚焦输入框时，渲染不能打断体验

1.2 现有方案的局限#

在调研过程中可以发现几个典型方案：

• react-markdown：专为 React 设计
• markstream-vue：专为 Vue 设计

它们在各自生态内非常好用，但有两个现实问题：

• 强框架绑定：React 项目用 React 方案，Vue 项目用 Vue 方案，每套都有自己的插件体系和扩展方式
• 缺乏通用性：如果你既维护 React 应用，又维护 Vue 应用，甚至还有一部分原生页面，就不得不在多个渲染方案之间来回切换

一个自然的发问是：

有没有一个「跨框架」的 Markdown 渲染器？
不管是 Vue、React、Angular、Svelte，甚至纯 HTML，都能用同一套渲染内核？

1.3 原生 JS 的瓶颈#

既然想做「跨框架」，直觉上最通用的方案是：

• 用 原生 JS 写一个 Markdown 渲染器
• 输入 AST / 文本，输出 HTML DOM

但在 AI 的流式场景下，单纯操作原生 DOM 很容易踩坑：

• 需要自己实现 DOM diff，否则每次更新都全量重绘，性能和能耗都会吃不消
• 更致命的是：
  • 全量重绘意味着原来的 DOM 被替换
  • 用户此时的光标、选区、滚动位置都可能被打断
  • 在流式响应过程中，用户几乎无法稳定选择/复制已生成内容

这类问题，在很多「简单粗暴的流式渲染 demo」里都很常见。

1.4 Web Components + Lit 的破局思路#

wc-renderer-markdown 选择了一条折中却优雅的路线：

• 使用 Web Components 作为跨框架的基础组件模型
• 使用 Lit 提供的声明式模板和高效 diff，不再手写 DOM 操作

这样带来几个非常重要的收益：

• 跨框架复用：

  • 只要浏览器支持 Web Components（Custom Elements + Shadow DOM），就能在任何框架中使用
  • 无论是 Vue、React、Angular、Svelte，还是纯 HTML，都可以直接引用 <wc-markdown>

• 渲染稳定性：

  • Lit 内置高效的 diff 过程
  • 在流式追加内容时，只会对必要的节点做最小更新
  • 已经渲染的部分尽可能稳定，避免光标丢失、选区闪烁

• 开发体验：

  • 使用 lit-html 模板语法书写组件，而不是手写 document.createElement
  • 利用响应式属性和状态系统，组件逻辑更清晰

可以把它理解成：

「用 Web Components 做跨框架 UI 的壳，用 Lit 做高效渲染的核。」

3.1 统一的 Markdown 节点抽象#

在渲染逻辑进入到具体组件之前，wc-renderer-markdown 先做了一层统一抽象：
所有从 markdown-parser 解析出来的节点，都会被映射到两类基类之一：

• 面向 Markdown AST 的 NodeElement<T extends BaseNode>
• 面向原生 HTML 节点的 HtmlNodeElement<Props>

可以简单理解为：

• NodeElement 负责承载「语义化 Markdown 节点」，暴露 node、props 和 markdownRoot 三个核心属性
• HtmlNodeElement 则面向「原生 HTML / 自定义标签」，只有 props 和 markdownRoot

两者内部都维护了一张静态映射表 components：

• 对于 NodeElement，key 是 Markdown 节点类型（如 heading、paragraph）
• 对于 HtmlNodeElement，key 是 HTML 标签名（如 div、details 或自定义标签）

渲染时，renderComponents / renderComponent 会根据节点类型或标签名，从对应的映射表里找到真正的 Web Component 标签并完成挂载。
这样一来，渲染层只需要「遍历节点并调用渲染函数」，而不必关心每一种节点的具体实现，新的语法或自定义标签也只需要继承这两个基类即可接入整套管线。

3.2 声明式组件注册：@customElement 装饰器#

在 Web Components 中，通常需要手动调用：

1
customElements.define('wc-heading', HeadingElement)

在 wc-renderer-markdown 里，希望做到两件事：

1. 统一组件前缀，避免全局命名冲突
2. 自动维护「Markdown 节点类型 → Web Component 标签」的映射表，从而可以根据 AST 动态渲染组件树

因此基于 lit/decorators.js 的 customElement 实现了一个增强版装饰器：

1
import { unsafeStatic } from 'lit/static-html.js';
2
import { config } from '@/config';
3
import { customElement as _customElement } from 'lit/decorators.js';
4
import NodeElement from '@/node/NodeElement';
5
import HtmlNodeElement from '@/node/HtmlNodeElement';
6

7
export function customElement (name: string, elementName?: string) {
8
  elementName = elementName ?? name.replace(/_/g, '-');
9
  if (!/^[a-z-]+$/.test(elementName)) {
10
    throw new Error(`elementName must only contain lowercase letters and hyphens, got: ${elementName}`);
11
  }
12

13
  const realName = `${config.componentPrefix}-${elementName}`;
14
  return <T extends CustomElementConstructor> (target: T) => {
15
    if (target.prototype instanceof HtmlNodeElement) {
16
      HtmlNodeElement.components[name] = unsafeStatic(realName);
17
    } else {
18
      NodeElement.components[name] = unsafeStatic(realName);
19
    }
20
    return _customElement(realName)(target);
21
  };
22
}

这个装饰器做了几件事：

• 自动补全前缀：

  • 项目通过 config.componentPrefix 统一定义组件前缀，例如 wc
  • 只要写 @customElement('heading')，真实注册的标签就是 <wc-heading>

• 自动维护 Node → Tag 映射：

  • 如果组件继承自 NodeElement，则将 NodeElement.components[name] 指向对应标签名
  • 如果组件继承自 HtmlNodeElement，则存入 HtmlNodeElement.components

这样，在定义组件时，开发者只需要关注「这个组件对应哪种 Markdown 节点」即可：

1
@customElement('heading') // 注册为 <wc-heading>，并映射 markdown 节点类型 "heading"
2
export default class extends NodeElement<HeadingNode> {
3
  // ...
4
}

在渲染时，则通过 renderComponents 动态计算组件标签：

1
export function renderComponent (node: ParsedNode, props: object) {
2
  const tag = computeTag(node);
3
  if (node.loading) {
4
    const loadingTag = unsafeStatic(`${config.componentPrefix}-loading`);
5
    return staticHtml`<${loadingTag}/>`;
6
  }
7
  return staticHtml`<${tag} .node="${node}" .renderComponents="${renderComponents}" .renderComponent="${renderComponent}" .props="${props}"/>`;
8
}

computeTag 内部会根据 node.type 在 NodeElement.components 中查找对应的 Web Component 标签。
如果未注册，会 fallback 到一个默认的文本组件，并在控制台给出 tag not register 的警告，方便调试。

从使用体验上，你只需要做两件事：

1. 在 markdown-parser 中定义新的节点类型
2. 在 wc 包中写一个对应的 NodeElement 实现，并用 @customElement('your_node_type') 标注

就能在整个渲染管线中无缝接入新的 Markdown 语法。

3.3 从 AST 到 UI：<wc-markdown> 的渲染流程#

核心入口组件 MarkdownElement 的职责非常清晰：

1. 接收外部传入的 content（Markdown 字符串）
2. 使用 stream-markdown-parser 将其解析为 AST
3. 调用 renderComponents(nodes) 将 AST 转换为组件树
4. 处理一些 UX 相关的能力（例如自动滚动到底部）

简化后的渲染逻辑如下：

1
@customElement('markdown')
2
export default class MarkdownElement extends LitElement {
3
  static styles = [cssvar, style];
4

5
  @property({ attribute: 'content' })
6
  content?: string = '';
7

8
  @property({ attribute: 'dark', reflect: true, type: Boolean })
9
  dark = false;
10

11
  @property({ attribute: 'auto-scroll-2-end', reflect: true, type: Boolean })
12
  autoScroll2End = false;
13

14
  render () {
15
    const md = getMarkdown();
16
    const nodes = parseMarkdownToStructure(this.content, md);
17
    return html`
18
      <div class="box">${renderComponents(nodes)}</div>
19
      ${this.autoScroll2End ? html`<span/>` : null}
20
    `;
21
  }
22
}

关于这套渲染流程，有几个细节值得注意：

• 解析与渲染解耦：

  • getMarkdown / parseMarkdownToStructure 来自 stream-markdown-parser
  • wc-renderer-markdown 只关心「如何根据 AST 渲染 Lit 组件」

• 上下文传递：

  • 通过 @provide + markdownRootContext 将 MarkdownElement 作为上下文提供给所有子节点
  • 子组件通过 @consume 获取当前的 Markdown 根节点实例（如在 NodeElement、HtmlNodeElement 中）
  • 这为后续实现诸如「节点间联动」「外部控制滚动/高亮某一段」打下基础

• 流式渲染友好：

  • 当 content 属性不断更新追加内容时，Lit 会对模板进行增量 diff
  • 已渲染部分不会被整体替换，从而保证了选区和光标的稳定性

3.4 Shadow DOM + CSS 变量：构建可主题化的 Markdown UI#

Markdown 渲染器的另一个常见痛点是：样式很容易被全局 CSS 污染。

• 页面全局有一份 p { margin: 0 }，可能会影响 Markdown 段落
• 外部的 code、pre 样式可能与 Markdown 渲染器的预期冲突

在 wc-renderer-markdown 里，借助 Web Components 的 Shadow DOM 能力，将每个组件的样式和结构封装在一起：

• 每个 Markdown 元素组件都有自己的 index.lit.css：
  • 如代码块组件 CodeBlock、提示块 Admonition、表格 Table 等
  • 外部样式无法直接影响内部结构

在此基础上，通过 CSS Variables（自定义属性） 把主题能力暴露出来：

• 每个组件可以定义自己的 var.lit.css，声明一组可配置变量
• 这些变量在 packages/wc/src/markdown/var.ts 中被聚合：

1
import AdmonitionCssVar from '@/components/Admonition/var.lit.css';
2
// ...
3

4
export default [
5
  AdmonitionCssVar,
6
  ...
7
] as CSSResult[];

然后在 MarkdownElement 中统一挂载：

1
@customElement('markdown')
2
export default class MarkdownElement extends LitElement {
3
  static styles = [cssvar, style];
4
  // ...
5
}

每个具体组件内部，则通过 :host 和 :host([dark]) 等选择器实现主题切换，例如在 Admonition 的 var.lit.css 中：

1
:host {
2
  --admonition-bg: #f8f8f8;
3
}
4
:host([dark]) {
5
  --admonition-bg: #0b1220; /* 暗黑模式自动适配 */
6
}

搭配 <wc-markdown dark> 这一属性，就可以在整个 Markdown 渲染树内统一切换暗色主题。

这种方式的优点是：

• 样式隔离：Shadow DOM 隔离内部实现，避免被外部 CSS 意外影响
• 主题可配置：通过 CSS 变量向外暴露可调节参数，用户可以在全局层面覆写
• 暗黑模式友好：[dark] 属性 + CSS 变量，使得暗色主题的维护成本大幅降低

3.5 框架适配层：在 React / Vue 里像用原生组件一样用它#

虽然 Web Components 理论上可以直接在任何框架中使用，但在实际落地时，仍然存在几个细节问题：

• Props / Attributes 的映射规则不同
• 事件机制不完全一致
• 在 React / Vue 世界中，我们更希望以「组件」的方式导入和使用

因此 wc-renderer-markdown 为 React / Vue 提供了友好的封装。

1
import React from 'react';
2
import { createComponent } from '@lit/react';
3
import MarkdownElement, { config } from 'wc-renderer-markdown';
4

5
const Markdown = createComponent<MarkdownElement>({
6
  tagName: `${config.componentPrefix}-markdown`,
7
  elementClass: MarkdownElement,
8
  react: React,
9
  displayName: 'Markdown',
10
});
11

12
export default Markdown;

1
import Markdown from 'wc-renderer-markdown-react'
2
<Markdown content={markdown} />

1
import { defineComponent, h } from 'vue-demi';
2
import { config } from 'wc-renderer-markdown';
3

4
const Markdown = defineComponent({
5
  name: 'Markdown',
6
  props: {
7
    content: String,
8
    dark: Boolean,
9
    autoScroll2End: Boolean,
10
  },
11
  setup (props, { attrs, slots }) {
12
    return () => h(
13
      `${config.componentPrefix}-markdown`,
14
      {
15
        ...attrs,
16
        ...props,
17
      },
18
      slots.default?.(),
19
    );
20
  },
21
});
22

23
export default Markdown;

1
<template>
2
  <Markdown :content="markdown" />
3
</template>
4

5
<script setup lang="ts">
6
import { ref } from 'vue'
7
import Markdown from 'wc-renderer-markdown-vue'
8

9
const markdown = ref(`# Welcome to WC Markdown Renderer`)
10
</script>