添加一个区块
为区块库贡献组件。
我们邀请社区为区块库做贡献。与其他开发者分享您的组件和区块,帮助构建一个高质量、可复用的组件库。
我们希望看到各种类型的区块:应用程序、营销、产品等等。
设置您的工作区
Fork 仓库
git clone https://github.com/shadcn-ui/ui.git
创建新分支
git checkout -b username/my-new-block
安装依赖
pnpm install
启动开发服务器
pnpm www:dev
添加一个区块
一个区块可以是一个单独的组件(例如,UI 组件的变体),也可以是一个复杂的组件(例如,一个仪表盘),包含多个组件、hooks 和 utils。
创建一个新区块
在 apps/www/registry/new-york/blocks
目录下创建一个新文件夹。确保文件夹以 kebab-case 命名,并在 new-york
下。
apps
└── www
└── registry
└── new-york
└── blocks
└── dashboard-01
注意: 构建脚本将负责为 default
样式构建区块。
添加您的区块文件
将您的文件添加到区块文件夹中。这是一个包含页面、组件、hooks 和 utils 的区块示例。
dashboard-01
└── page.tsx
└── components
└── hello-world.tsx
└── example-card.tsx
└── hooks
└── use-hello-world.ts
└── lib
└── format-date.ts
注意: 您可以从一个文件开始,稍后添加更多文件。
将您的区块添加到注册表
将您的区块定义添加到 registry-blocks.tsx
要将您的区块添加到注册表,您需要将您的区块定义添加到 registry-blocks.ts
。
这遵循注册表模式,地址为 https://ui.shadcn.org.cn/schema/registry-item.json。
export const blocks = [
// ...
{
name: "dashboard-01",
author: "shadcn (https://ui.shadcn.org.cn)",
title: "Dashboard",
description: "A simple dashboard with a hello world component.",
type: "registry:block",
registryDependencies: ["input", "button", "card"],
dependencies: ["zod"],
files: [
{
path: "blocks/dashboard-01/page.tsx",
type: "registry:page",
target: "app/dashboard/page.tsx",
},
{
path: "blocks/dashboard-01/components/hello-world.tsx",
type: "registry:component",
},
{
path: "blocks/dashboard-01/components/example-card.tsx",
type: "registry:component",
},
{
path: "blocks/dashboard-01/hooks/use-hello-world.ts",
type: "registry:hook",
},
{
path: "blocks/dashboard-01/lib/format-date.ts",
type: "registry:lib",
},
],
categories: ["dashboard"],
},
]
请确保添加名称、描述、类型、registryDependencies、dependencies、files 和 categories。我们将在模式文档(即将推出)中详细介绍这些内容。
运行构建脚本
pnpm registry:build
注意: 您无需为每次更改都运行此脚本。您只需在更新区块定义时运行它。
查看您的区块
构建脚本完成后,您可以在 http://localhost:3333/blocks/[CATEGORY]
查看您的区块,或在 http://localhost:3333/view/styles/new-york/dashboard-01
查看全屏预览。

构建您的区块
现在,您可以通过编辑区块文件夹中的文件并在浏览器中查看更改来构建您的区块。
如果您添加更多文件,请确保将它们添加到区块定义中的 files
数组中。
发布您的区块
当您准备好发布您的区块时,您可以向主仓库提交 pull request。
运行构建脚本
pnpm registry:build
捕获屏幕截图
pnpm registry:capture
注意: 如果您之前运行过捕获脚本,您可能需要删除 apps/www/public/r/styles/new-york
中现有的屏幕截图(浅色和深色),然后再次运行脚本。
提交 pull request
提交您的更改并向主仓库提交 pull request。
您的区块将被审核和合并。合并后,它将被发布到网站,并可以通过 CLI 安装。
分类
categories
属性用于在注册表中组织您的区块。
添加分类
如果您需要添加新分类,可以通过将其添加到 apps/www/registry/registry-categories.ts
中的 registryCategories
数组中来完成。
export const registryCategories = [
// ...
{
name: "Input",
slug: "input",
hidden: false,
},
]
准则
以下是为区块库贡献内容时应遵循的一些准则。
- 以下属性是区块定义所必需的:
name
、description
、type
、files
和categories
。 - 请确保在
registryDependencies
中列出所有注册表依赖项。注册表依赖项是注册表中组件的名称,例如input
、button
、card
等。 - 请确保在
dependencies
中列出所有依赖项。依赖项是注册表中软件包的名称,例如zod
、sonner
等。 - 如果您的区块有页面(可选),它应该是
files
数组中的第一个条目,并且应该具有target
属性。这有助于 CLI 将页面放置在基于文件的路由的正确位置。 - 导入应始终使用
@/registry
路径。 例如:import { Input } from "@/registry/new-york/input"