我们邀请社区为区块库贡献力量。与其他开发者分享你的组件和区块,并帮助建立一个高质量、可重用组件的库。
我们希望看到各种类型的区块:应用程序、市场营销、产品等。
设置您的工作区
分叉仓库
git clone https://github.com/shadcn-ui/ui.git
创建新分支
git checkout -b username/my-new-block
安装依赖
pnpm install
启动开发服务器
pnpm www:dev
添加区块
一个区块可以是一个单一的组件(例如,ui 组件的一个变体),也可以是一个包含多个组件、钩子和实用工具的复杂组件(例如,一个仪表盘)。
创建一个新区块
在 apps/www/registry/new-york/blocks
目录下创建一个新文件夹。确保文件夹名称采用 kebab-case 格式,并且位于 new-york
下。
apps
└── www
└── registry
└── new-york
└── blocks
└── dashboard-01
注意:构建脚本将负责为 default
样式构建区块。
添加您的区块文件
将您的文件添加到区块文件夹。以下是一个包含页面、组件、钩子和实用工具的区块示例。
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
注意:您不需要为每次更改都运行此脚本。您只需在更新区块定义时运行它。
查看您的区块
构建脚本完成后,您可以在 https://:3333/blocks/[CATEGORY]
查看您的区块,或在 https://:3333/view/styles/new-york/dashboard-01
查看全屏预览。


构建您的区块
您现在可以通过编辑区块文件夹中的文件并在浏览器中查看更改来构建您的区块。
如果您添加了更多文件,请务必将它们添加到区块定义中的 files
数组中。
发布您的区块
一旦您准备好发布您的区块,您可以向主仓库提交一个拉取请求。
运行构建脚本
pnpm registry:build
截取屏幕截图
pnpm registry:capture
注意:如果您之前运行过截屏脚本,您可能需要删除 apps/www/public/r/styles/new-york
中现有的屏幕截图(亮色和暗色),然后再次运行脚本。
提交拉取请求
提交您的更改并向主仓库提交拉取请求。
您的区块将经过审查并合并。一旦合并,它将被发布到网站,并通过 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"