添加一个块

我们邀请社区为 块库 做出贡献。与其他开发者共享你的组件和块，并帮助构建高质量、可重用组件库。

¥We are inviting the community to contribute to the blocks library. Share your components and blocks with other developers and help build a library of high-quality, reusable components.

我们很乐意看到所有类型的块：应用、营销、产品等。

¥We'd love to see all types of blocks: applications, marketing, products, and more.

设置你的工作区

¥Setup your workspace

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

git checkout -b username/my-new-block

pnpm install

pnpm www:dev

添加一个块

¥Add a block

一个块可以是单个组件（例如，ui 组件的变体）或具有多个组件、钩子和实用程序的复杂组件（例如，仪表板）。

¥A block can be a single component (eg. a variation of a ui component) or a complex component (eg. a dashboard) with multiple components, hooks, and utils.

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

dashboard-01
└── page.tsx
└── components
    └── hello-world.tsx
    └── example-card.tsx
└── hooks
    └── use-hello-world.ts
└── lib
    └── format-date.ts

将你的块添加到注册表

¥Add your block to the registry

将你的块定义添加到 registry-blocks.tsx

¥Add your block definition to registry-blocks.tsx

要将你的块添加到注册表，你需要将你的块定义添加到 registry-blocks.ts。

¥To add your block to the registry, you need to add your block definition to registry-blocks.ts.

这遵循 https://shadcn.nodejs.cn/schema/registry-item.json 中的注册表模式。

¥This follows the registry schema at https://shadcn.nodejs.cn/schema/registry-item.json.

apps/www/registry/registry-blocks.tsx

export const blocks = [
  // ...
  {
    name: "dashboard-01",
    author: "shadcn (https://shadcn.nodejs.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"],
  },
]

Copy

确保添加名称、描述、类型、registryDependencies、依赖、文件和类别。我们将在架构文档（即将推出）中更详细地介绍其中的每一个。

¥Make sure you add a name, description, type, registryDependencies, dependencies, files, and categories. We'll go over each of these in more detail in the schema docs (coming soon).

运行构建脚本

¥Run the build script

pnpm registry:build

Copy

注意：你不需要为每次更改运行此脚本。你只需在更新块定义时运行它。

¥Note: you do not need to run this script for every change. You only need to run it when you update the block definition.

查看你的块

¥View your block

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

¥Once the build script is finished, you can view your block at http://localhost:3333/blocks/[CATEGORY] or a full screen preview at http://localhost:3333/view/styles/new-york/dashboard-01.

构建你的块

¥Build your block

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

¥You can now build your block by editing the files in the block folder and viewing the changes in the browser.

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

¥If you add more files, make sure to add them to the files array in the block definition.

发布你的块

¥Publish your block

准备好发布块后，你可以向主存储库提交拉取请求。

¥Once you're ready to publish your block, you can submit a pull request to the main repository.

pnpm registry:build

pnpm registry:capture

类别

¥Categories

categories 属性用于在注册表中组织块。

¥The categories property is used to organize your block in the registry.

添加一个类别

¥Add a category

如果你需要添加新类别，可以通过将其添加到 apps/www/registry/registry-categories.ts 中的 registryCategories 数组来实现。

¥If you need to add a new category, you can do so by adding it to the registryCategories array in apps/www/registry/registry-categories.ts.

export const registryCategories = [
  // ...
  {
    name: "Input",
    slug: "input",
    hidden: false,
  },
]

指南

¥Guidelines

以下是为块库做贡献时要遵循的一些准则。

¥Here are some guidelines to follow when contributing to the blocks library.

• 块定义需要以下属性：name、description、type、files 和 categories。

  ¥The following properties are required for the block definition: name, description, type, files, and categories.

• 确保列出 registryDependencies 中的所有注册表依赖。注册表依赖是注册表中组件的名称，例如 input、button、card 等。

  ¥Make sure to list all registry dependencies in registryDependencies. A registry dependency is the name of the component in the registry eg. input, button, card, etc.

• 确保列出 dependencies 中的所有依赖。依赖是注册表中包的名称，例如 zod、sonner 等。

  ¥Make sure to list all dependencies in dependencies. A dependency is the name of the package in the registry eg. zod, sonner, etc.

• 如果你的块有一个页面（可选），它应该是 files 数组中的第一个条目，并且应该具有 target 属性。这有助于 CLI 将页面放在正确的位置以进行基于文件的路由。

  ¥If your block has a page (optional), it should be the first entry in the files array and it should have a target property. This helps the CLI place the page in the correct location for file-based routing.

• 导入应始终使用 @/registry 路径。例如 import { Input } from "@/registry/new-york/input"

  ¥Imports should always use the @/registry path. eg. import { Input } from "@/registry/new-york/input"