DemoPreview 预览组件

在 Markdown 文档中嵌入可运行的组件演示：上半部分实时渲染组件，下半部分展示对应源码。支持目录引入、文件引入、内联代码三种方式，源码面板自动继承主题代码块视觉（光束边框、语法高亮、折叠）。

特性

三种引入方式 — 目录引入、文件引入、内联代码
源码面板复用主题样式 — 自动继承光束边框、语法高亮、折叠等代码块视觉
多文件 Tab 切换 — 目录模式下多个文件以标签页展示
样式隔离 — 运行预览区使用 not-prose 隔离，demo 组件原样展示不受文档样式干扰
零配置启用 — 随主题自动注册，Markdown 中直接使用 <DemoPreview>

目录引入

适合多文件组成的完整 Demo。指定一个目录，目录内的 index.vue 作为运行组件，其余文件作为源码以 Tab 展示。

<DemoPreview dir="demos/alert" />

dir 路径相对项目根（VitePress 启动目录）
目录必须包含 index.vue
目录内所有文件按 index.vue 优先、字母序排列

文件引入

引入单个 .vue 文件作为演示。

<DemoPreview src="./MyButton.vue" />

src 路径相对当前 Markdown 文件

内联代码

直接在 Markdown 中编写 Vue 代码，用 <DemoPreview> 标签包起来，无需创建文件。代码会被提取为虚拟模块编译运行（不生成磁盘临时文件）。

<DemoPreview>
<script setup>
  import { ref } from 'vue'
  const count = ref(0)
</script>
<button @click="count++">点击 {{ count }} 次</button>
</DemoPreview>

写法约定

<DemoPreview> 标签内的代码需遵循以下缩进规则：

顶层标签顶格写：<script setup>、</script>、根元素（如 <button>）不要缩进
标签内部代码正常缩进：import、const 等按 Vue SFC 惯例缩进

错误写法（会导致源码缩进错乱）：

<DemoPreview>
  <script setup>
  import { ref } from 'vue'
  const count = ref(0)
  </script>
  <button @click="count++">{{ count }}</button>
</DemoPreview>

正确写法：

<DemoPreview>
<script setup>
  import { ref } from 'vue'
  const count = ref(0)
</script>
<button @click="count++">{{ count }}</button>
</DemoPreview>

实际效果

以下是一个文件引入的实际渲染（内联代码效果请访问测试页）：

工作原理

DemoPreview 由三部分协作：

Markdown 插件（fxDemoPreviewPlugin）— 在编译期识别三种写法，统一改写为 <DemoPreview> 组件调用，自动注入演示组件的 import 语句
Vite 虚拟模块插件（fxDemoVirtualPlugin）— 为内联代码的 import 'virtual:fx-demo/<hash>.vue' 提供 SFC 内容，交 vue 编译（无磁盘临时文件）
预览容器组件（DemoPreview.vue）— 上半用 <ClientOnly> + not-prose 渲染演示组件，下半 PreviewGroup 展示源码

源码展示走 VitePress 原生代码块渲染，因此自动继承主题的代码块视觉（暗色模式光束边框、语法高亮、折叠等）。

注意事项

演示组件在客户端运行（ClientOnly），SSG 阶段显示加载占位
运行预览区使用 not-prose 隔离，不受文档全局样式（vp-doc）影响
内联代码的 <script setup> 会被提取到虚拟模块顶层编译（Vue 不允许标签内嵌 script setup）

DemoPreview 预览组件 ​

特性 ​

目录引入 ​

文件引入 ​

内联代码 ​

写法约定 ​

实际效果 ​

工作原理 ​

注意事项 ​