组件预览
如何在文档中使用 ComponentPreview 和 ComponentSource 组件
简介
ComponentPreview 和 ComponentSource 组件用于在文档中展示组件示例，提供交互式的预览和代码查看功能。
ComponentPreview
ComponentPreview 组件提供标签页模式，允许用户在预览和代码之间切换。
使用方法
<ComponentPreview name="button-demo" description="按钮示例" />属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
name | string | 必填 | 示例组件的名称，需要在 registry 中注册 |
description | string | 可选 | 示例的描述文字 |
align | "center" | "start" | "end" | "center" | 预览区域的对齐方式 |
className | string | 可选 | 自定义 CSS 类名 |
功能
- 预览标签页: 展示组件的实际渲染效果
- 代码标签页: 显示组件的源代码
- 复制按钮: 一键复制代码到剪贴板
- 在 v0 中打开: 在 v0.dev 中打开组件进行编辑
ComponentSource
ComponentSource 组件同时展示预览和代码，适合需要同时查看两者的场景。
使用方法
<ComponentSource name="button-demo" />属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
name | string | 必填 | 示例组件的名称，需要在 registry 中注册 |
align | "center" | "start" | "end" | "center" | 预览区域的对齐方式 |
className | string | 可选 | 自定义 CSS 类名 |
功能
- 上方预览: 展示组件的实际渲染效果
- 下方代码: 显示组件的源代码
- 复制按钮: 一键复制代码到剪贴板
- 在 v0 中打开: 在 v0.dev 中打开组件进行编辑
添加新示例
要添加新的示例组件，按照以下步骤操作：
创建示例组件
在 registry/new-york/examples/ 目录下创建你的示例组件：
import { Button } from "@/registry/new-york/ui/button"
export default function MyComponentDemo() {
return (
<div className="flex items-center gap-2">
<Button>Click me</Button>
</div>
)
}注册示例
在 registry/registry-examples.ts 中注册你的示例：
export const examples: Registry["items"] = [
// ... 其他示例
{
name: "my-component-demo",
type: "registry:example",
description: "我的组件示例",
registryDependencies: ["button"],
files: [
{
path: "examples/my-component-demo.tsx",
type: "registry:example",
},
],
},
]最佳实践
- 清晰的命名: 使用描述性的名称，如
button-size、card-with-form等 - 添加描述: 为每个示例添加有意义的描述文字
- 保持简洁: 示例代码应该聚焦于展示特定功能，避免过于复杂
- 合理对齐: 根据组件特性选择合适的对齐方式
- 依赖声明: 确保在 registry 中正确声明所有依赖
技术实现
- 动态加载: 使用 React.lazy 实现组件的按需加载
- 代码获取: 从
/r/*.json文件动态获取源代码 - 代码高亮: 使用 fumadocs-ui 的 CodeBlock 组件
- 标签页: 使用 fumadocs-ui 的 Tabs 组件