核心组件

相关源文件

• apps/v4/components/nav-header.tsx
• apps/v4/registry/new-york-v4/ui/button.tsx
• apps/v4/registry/new-york-v4/ui/label.tsx
• apps/v4/registry/new-york-v4/ui/menubar.tsx
• apps/v4/registry/new-york-v4/ui/select.tsx
• apps/v4/registry/new-york-v4/ui/toggle-group.tsx
• apps/v4/registry/new-york-v4/ui/tooltip.tsx
• apps/www/app/(app)/examples/playground/components/model-selector.tsx/examples/playground/components/model-selector.tsx)
• apps/www/content/docs/components/combobox.mdx
• apps/www/content/docs/components/date-picker.mdx
• apps/www/public/r/styles/default/select.json
• apps/www/public/r/styles/new-york-v4/button.json
• apps/www/public/r/styles/new-york-v4/label.json
• apps/www/public/r/styles/new-york-v4/menubar.json
• apps/www/public/r/styles/new-york-v4/select.json
• apps/www/public/r/styles/new-york-v4/toggle-group.json
• apps/www/public/r/styles/new-york-v4/tooltip.json
• apps/www/public/r/styles/new-york/select.json
• apps/www/public/registry/index.json
• apps/www/public/registry/styles/default/command.json
• apps/www/public/registry/styles/new-york/command.json
• apps/www/registry/default/ui/command.tsx
• apps/www/registry/default/ui/scroll-area.tsx
• apps/www/registry/default/ui/select.tsx
• apps/www/registry/new-york/ui/command.tsx
• apps/www/registry/new-york/ui/scroll-area.tsx
• apps/www/registry/new-york/ui/select.tsx

核心组件是 shadcn/ui 组件库的基本 UI 构建块。这些组件提供了诸如按钮、输入框、表单控件和基本反馈机制等基本交互元素，它们构成了更复杂 UI 模式的基础。对于侧边栏和导航菜单等以布局为中心的组件，请参阅 布局组件。对于图表和通知等复杂组件，请参阅 复杂组件。

组件架构

shadcn/ui 中的核心组件遵循一种一致的架构模式，该模式建立在三个关键层之上：用于可访问性和行为的 Radix UI 原始组件、用于样式的 Tailwind CSS 以及用于类型安全的 TypeScript。

来源： apps/www/registry/new-york/ui/select.tsx1-160 apps/www/registry/default/ui/command.tsx1-154 apps/v4/registry/new-york-v4/ui/button.tsx1-60

组件解剖

每个核心组件都遵循一致的结构，并导出多个可以组合在一起的部分。Select 组件就体现了这种模式。

组件部分	目的	Radix 原始组件
选择	根容器	SelectPrimitive.Root
SelectTrigger	可点击的触发按钮	SelectPrimitive.Trigger
SelectContent	下拉内容容器	SelectPrimitive.Content
SelectItem	单个选项	SelectPrimitive.Item
SelectValue	显示选定的值	SelectPrimitive.Value

来源： apps/www/registry/new-york/ui/select.tsx9-159 apps/www/public/r/styles/new-york/select.json1-17

TypeScript 模式

核心组件使用一致的 TypeScript 模式来实现类型安全和正确的 ref 转发。

SelectTrigger 组件演示了这种模式，位于 apps/www/registry/new-york/ui/select.tsx15-33

• 使用 React.forwardRef 进行正确的 ref 转发
• 将 ref 类型设置为 React.ElementRef<typeof SelectPrimitive.Trigger>
• 将 props 类型设置为 React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
• 设置 displayName 以便调试
• 使用 cn() 将 className prop 与默认样式合并

来源： apps/www/registry/new-york/ui/select.tsx15-33 apps/v4/registry/new-york-v4/ui/button.tsx38-57

样式系统

核心组件采用分层样式方法，可实现一致的主题化和自定义。

Button 组件在 apps/v4/registry/new-york-v4/ui/button.tsx7-36 使用 class-variance-authority 来管理变体。

• 基本样式适用于所有变体
• 特定变体的样式，用于 default, destructive, outline, secondary, ghost, link
• 尺寸变体，用于 default, sm, lg, icon
• CSS 变量，例如 bg-primary, text-primary-foreground，用于主题化

来源： apps/v4/registry/new-york-v4/ui/button.tsx7-36 apps/www/registry/new-york/ui/select.tsx21-24

注册表集成

组件库通过注册系统支持多种视觉样式。

Select 组件在 apps/www/public/r/styles/new-york/select.json1-17 定义了：

• 组件名称： "select"
• 依赖项： ["@radix-ui/react-select"]
• 文件路径： "ui/select.tsx"
• 组件类型： "components:ui"

字段	目的	示例
名称	组件标识符	"select"
依赖项	必需的 npm 包	["@radix-ui/react-select"]
registryDependencies	其他必需的组件	["button"]
文件	组件源文件	[{"name": "select.tsx", ...}]

来源： apps/www/public/r/styles/new-york/select.json1-17 apps/www/public/registry/index.json336-345

命令面板模式

Command 组件展示了一个更复杂的核心组件，它结合了多个原始组件。

Command 组件在 apps/www/registry/default/ui/command.tsx11-24 封装了 cmdk 库的原始组件，并用于 apps/www/content/docs/components/combobox.mdx20-115 等复杂模式下的组合框。

来源： apps/www/registry/default/ui/command.tsx11-154 apps/www/content/docs/components/combobox.mdx20-115 apps/www/app/(app)/examples/playground/components/model-selector.tsx95-119

样式变体

The component library supports multiple visual styles through the registry system

风格	位置	目的
默认	apps/www/registry/default/ui/	Original shadcn/ui styling
new-york	apps/www/registry/new-york/ui/	Alternative visual style
new-york-v4	apps/v4/registry/new-york-v4/ui/	Next-generation styling

new-york-v4 风格引入了 data-slot 属性，以增强样式控制。这在 Button 组件的 apps/v4/registry/new-york-v4/ui/button.tsx52 中可见，以及 Select 组件的 apps/v4/registry/new-york-v4/ui/select.tsx12 中也可见。

来源：apps/www/registry/default/ui/select.tsx1-161 apps/www/registry/new-york/ui/select.tsx1-160 apps/v4/registry/new-york-v4/ui/select.tsx1-186