ComponentExample 渲染一个示例组件的实时预览,并在下方展示该示例文件的源码。源码在构建期读取,与预览始终一致。
编写示例
示例放在 app/components/content/examples/ 目录(可以有子目录),文件名即示例名:
app/components/content/examples/
└── AccordionExample.vue
name 传入文件名,支持 PascalCase 或 kebab-case:
<script setup lang="ts">
import type { AccordionItem } from '@nuxt/ui'
const items = [
{
label: 'Icons',
icon: 'i-lucide-smile',
content: 'You have nothing to do, @nuxt/icon will handle it automatically.'
},
{
label: 'Colors',
icon: 'i-lucide-swatch-book',
slot: 'colors' as const,
content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
},
{
label: 'Components',
icon: 'i-lucide-box',
content: 'You can customize components by using the `class` / `ui` props or in your app.config.ts.'
}
] satisfies AccordionItem[]
</script>
<template>
<UAccordion :items="items">
<template #colors="{ item }">
<p class="text-sm pb-3.5 text-primary">
{{ item.content }}
</p>
</template>
</UAccordion>
</template>
:component-example{name="AccordionExample"}
源码展示
高亮与折叠
highlights 高亮指定行,collapse 折叠较长的源码:
::component-example
---
name: AccordionExample
highlights: [2, 9]
collapse: true
---
::
collapse 也可以传入对象,自定义按钮文案与初始状态:
::component-example
---
name: AccordionExample
collapse:
openText: 展开源码
closeText: 收起源码
---
::
只显示预览或源码
source: false只渲染预览preview: false只展示源码,此时代码块显示文件名,可用filename覆盖prettier: true使用 Prettier 格式化源码后再展示
可调参数
options 在预览上方生成参数选择器,选中的值作为 props 传给示例组件。名称以 color 结尾的参数显示色块:
::component-example
---
name: ButtonExample
options:
- name: color
label: color
items: [primary, secondary, neutral]
default: primary
- name: label
label: label
default: Button
---
::
props 传入固定的初始 props,与 options 合并后生效。
仅客户端渲染
示例内部直接使用 window、document、setInterval 等浏览器 API 时,设置 client-only 让预览只在客户端渲染,避免 SSR 阶段报错:
:component-example{name="AccordionExample" client-only}
扩展示例容器
在项目中新建 app/components/content/ComponentExampleExtras.vue,即可在每个示例容器内叠加额外 UI(主题可视化、Playground 按钮等)。layer 默认提供空实现,ComponentCode 也会渲染它。
| Prop | 类型 | 说明 |
|---|---|---|
name | string | name 的原始值 |
camelName | string | 示例名的 camelCase 形式 |
pascalName | string | 示例名的 PascalCase 形式 |
effectiveProps | Record<string, any> | props 与 options 合并后的当前值 |
options | Array<{ name: string, label: string }> | undefined | 原样透传的 options |
wrapperContainer | HTMLElement | null | 示例最外层容器,用于定位浮层 |
componentContainer | HTMLElement | null | 示例组件的渲染容器,用于扫描 DOM |
下例参考 Nuxt UI 的 ComponentThemeVisualizer.vue,在示例上叠加主题可视化:
<script setup lang="ts">
import { camelCase } from 'scule'
defineProps<{
wrapperContainer: HTMLElement | null
componentContainer: HTMLElement | null
}>()
const route = useRoute()
const slug = computed(() => camelCase(route.path.split('/').pop() ?? ''))
</script>
<template>
<LazyComponentThemeVisualizer
:slug="slug"
:container="componentContainer"
:position-container="wrapperContainer"
/>
</template>
扩展组件只在客户端渲染,不影响 SSR 输出。
API
Props
| Prop | Default | Type |
|---|---|---|
name | string | |
iframe | false | boolean | { [key: string]: any; } 是否在 iframe 中渲染组件 |
iframeMobile | false | boolean 是否在移动端尺寸的 iframe 视口中显示组件 |
props | { [key: string]: any; } | |
prettier | false | boolean 是否使用 Prettier 格式化代码 |
collapse | false | boolean | { icon?: string ; name?: string | undefined; openText?: string | undefined; closeText?: string | undefined; open?: boolean | undefined; } | undefined是否折叠代码块 |
preview | true | boolean 是否显示预览
当设置为 |
source | true | boolean 是否显示源代码 |
options | { type?: string | undefined; alias?: string | undefined; name: string; label: string; items?: any[] | undefined; default: any; multiple?: boolean | undefined; }[]链接到组件的可变属性列表 | |
highlights | number[]代码块中需要高亮的行号列表 | |
overflowHidden | boolean 是否在包装器上添加 overflow-hidden | |
clientOnly | false | boolean 是否只在客户端渲染预览组件,适用于依赖 window / setInterval 等浏览器 API 的示例 |
elevated | boolean 是否添加 background-elevated 到 wrapper | |
lang | 'vue' | string |
filename | string覆盖用于代码块的文件名 |
Slots
| Slot | Type |
|---|---|
options | {} |
code | {} |