组件块

相关源文件

• apps/www/app/(app)/blocks/layout.tsx/blocks/layout.tsx)
• apps/www/app/(app)/charts/layout.tsx/charts/layout.tsx)
• apps/www/app/(app)/colors/layout.tsx/colors/layout.tsx)
• apps/www/app/(app)/og/geist-regular-otf.json/og/geist-regular-otf.json)
• apps/www/app/(app)/og/geist-semibold-otf.json/og/geist-semibold-otf.json)
• apps/www/app/(app)/og/geistmono-regular-otf.json/og/geistmono-regular-otf.json)
• apps/www/app/(app)/og/route.tsx/og/route.tsx)
• apps/www/content/docs/blocks.mdx
• apps/www/public/images/block-preview-dark.png
• apps/www/public/images/block-preview-light.png

组件 Blocks 提供预先构建好的、可组合的 UI 部分，开发者可以直接复制代码到他们的应用程序中。与单个组件（参见 核心组件）不同，Blocks 代表完整的 UI 模式，例如仪表板、表单、登陆页面部分或应用程序布局，它们将多个组件、hooks 和工具组合成功能单元。

有关支持 Blocks 的底层组件注册系统的信息，请参阅 组件注册系统。有关安装 Blocks 时使用的 CLI 命令的详细信息，请参阅 组件管理。

Block 系统架构

Blocks 系统作为组件注册的扩展，提供更大、更复杂的 UI 组合，同时保持与单个组件相同的复制粘贴理念。

Block 注册表和构建管道

来源: apps/www/app/(app)/blocks/layout.tsx1-74 apps/www/content/docs/blocks.mdx89-151

Block 文件结构和类型

来源: apps/www/content/docs/blocks.mdx67-86 apps/www/content/docs/blocks.mdx110-132

Block 定义 Schema

Blocks 在 registry-blocks.ts 文件中定义，遵循结构化的 schema，该 schema 指定了元数据、依赖项和文件映射。

注册表 Block 结构

每个 Block 定义包含以下属性

属性	类型	描述
名称	字符串	Block 的唯一标识符
作者	字符串	Block 作者信息
title	字符串	Block 的显示标题
description	字符串	Block 用途的简要描述
类型	"registry:block"	固定的类型标识符
registryDependencies	string[]	所需的 shadcn/ui 组件
dependencies	string[]	必需的外部 npm 包
files	FileDefinition[]	Block 中包含的文件数组
categories	string[]	用于组织分类

文件定义 Schema

Block 中的每个文件包含

来源: apps/www/content/docs/blocks.mdx99-138 apps/www/content/docs/blocks.mdx234-238

Block 类别和组织

类别管理

Blocks 类别在 registry-categories.ts 中定义，并控制 Blocks 在浏览界面中的组织方式

类别属性

每个类别定义包含

• name: 类别的显示名称
• slug: 适合 URL 的标识符
• hidden: 是否从导航中隐藏

来源: apps/www/content/docs/blocks.mdx216-227

开发工作流

添加新的 Block

Block 开发过程遵循以下步骤

Block 文件组织

Blocks 在 apps/www/registry/new-york/blocks 内遵循一致的目录结构

dashboard-01/
├── page.tsx                 # Main page component (registry:page)
├── components/              # UI components (registry:component)
│   ├── hello-world.tsx
│   └── example-card.tsx
├── hooks/                   # Custom hooks (registry:hook)
│   └── use-hello-world.ts
└── lib/                     # Utility functions (registry:lib)
    └── format-date.ts

来源: apps/www/content/docs/blocks.mdx46-86

构建和预览系统

注册表构建流程

命令 pnpm registry:build 处理 Block 定义并生成必要的元数据和资源

1. Schema 验证：根据注册表 schema 验证 Block 定义
2. 元数据生成：为每个 Block 创建 JSON 文件
3. 交叉引用构建：链接依赖项和类别
4. 索引生成：更新注册表索引

截图捕获系统

命令 pnpm registry:capture 生成视觉预览

1. 预览页面渲染：独立渲染每个 Block
2. 截图生成：捕获浅色和深色模式的图像
3. 资源优化：处理用于 Web 交付的图像
4. 元数据更新：将截图链接到 Block 定义

预览 URL

Blocks 可以通过以下方式预览

• 类别视图：http://:3333/blocks/[CATEGORY]
• 全屏：http://:3333/view/styles/new-york/[BLOCK_NAME]

来源: apps/www/content/docs/blocks.mdx141-170 apps/www/content/docs/blocks.mdx186-201

用户界面组件

BlocksLayout 组件

位于 apps/www/app/(app)/blocks/layout.tsx44-74 中的 BlocksLayout 组件提供了 Blocks 浏览体验的主要结构

• 页面头部：显示标题、描述和操作按钮
• 导航集成：包含用于分类过滤的 BlocksNav
• 内容容器：渲染子组件并提供适当的间距

导航和浏览

Blocks 界面包含

• 浏览 Blocks 按钮：链接到主 Blocks 网格（href="#blocks"）
• 添加 Block 按钮：链接到贡献文档（href="/docs/blocks"）
• 类别导航：由 BlocksNav 组件提供支持，用于过滤
• 响应式布局：使用容器包装类实现适当的间距

来源: apps/www/app/(app)/blocks/layout.tsx16-73

与 CLI 系统的集成

Blocks 集成了 shadcn CLI 进行安装

CLI 系统可以通过以下方式安装 Blocks

1. 从注册表中获取 Block 元数据
2. 安装所需的 registryDependencies (shadcn/ui 组件)
3. 安装外部 dependencies (npm 包)
4. 将 Block 文件复制到相应的项目位置
5. 在指定的情况下，使用 target 路径进行文件路由

来源: apps/www/content/docs/blocks.mdx175-207 apps/www/content/docs/blocks.mdx110-132