文档
添加一个区块

添加一个区块

为区块库贡献组件。

我们邀请社区成员为区块库做出贡献。与其他开发者分享您的组件和区块，帮助构建一个高质量、可复用的组件库。

我们期待看到各种类型的区块：应用、营销、产品等等。

设置您的工作区

Fork 仓库

git clone https://github.com/shadcn-ui/ui.git

创建新分支

git checkout -b username/my-new-block

安装依赖

pnpm install

启动开发服务器

pnpm www:dev

添加一个区块

一个区块可以是一个单独的组件（例如，ui 组件的变体）或一个复杂的组件（例如，一个仪表盘），包含多个组件、Hook 和工具函数。

创建一个新区块

在 apps/www/registry/new-york/blocks 目录中创建一个新文件夹。确保文件夹以 kebab-case 命名，并且位于 new-york 下。

apps
└── www
    └── registry
        └── new-york
            └── blocks
                └── dashboard-01

添加您的区块文件

将您的文件添加到区块文件夹中。这是一个包含页面、组件、Hook 和工具函数的区块示例。

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 的注册中心模式。

apps/www/registry/registry-blocks.tsx
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"],
  },
]

确保您添加了 name、description、type、registryDependencies、dependencies、files 和 categories。我们将在模式文档中更详细地介绍这些（即将推出）。

运行构建脚本

pnpm registry:build

查看您的区块

构建脚本完成后，您可以在 https://127.0.0.1:3333/blocks/[CATEGORY] 或全屏预览 https://127.0.0.1:3333/view/styles/new-york/dashboard-01 查看您的区块。

Block preview

构建您的区块

您现在可以通过编辑区块文件夹中的文件并在浏览器中查看更改来构建您的区块。

如果您添加更多文件，请确保将它们添加到区块定义中的 files 数组中。

发布您的区块

准备好发布您的区块后，您可以向主仓库提交拉取请求。

运行构建脚本

pnpm registry:build

捕获屏幕截图

pnpm registry:capture

提交拉取请求

提交您的更改并向主仓库提交拉取请求。

您的区块将被审核和合并。合并后，它将被发布到网站，并可以通过 CLI 安装。

分类

categories 属性用于在注册中心中组织您的区块。

添加一个分类

如果您需要添加新分类，可以通过将其添加到 apps/www/registry/registry-categories.ts 中的 registryCategories 数组中来完成。

apps/www/registry/registry-categories.ts
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"
在 v0 中打开Figma