组件添加与基本使用

本页目的： 用 shadcn add 把常用组件装进来，理解依赖如何自动解析，并掌握 v4 / Base UI 的新用法范式。全部基于本机实测（macOS arm64， shadcn CLI 4.20.1）。

上一篇：环境与初始化；下一篇：进阶使用。

1. add 基本用法

# 添加一个或多个组件（用环境篇 §2 装的本地固定版 CLI，不用 dlx @latest）
pnpm shadcn add button
pnpm shadcn add card dialog table tabs

选项	作用
`-y, --yes`	跳过确认提示
`-o, --overwrite`	覆盖已有文件（默认相同文件跳过）
`--all`	添加全部组件
`-p, --path <path>`	指定落盘路径
`--dry-run`	预览变更不写盘
`--diff [path]`	查看与 registry 的差异（取代旧 `diff` 命令）

实测输出（shadcn 4.20.1，别名已按环境篇 §3 映射到 src/）：

- Checking registry.        ✔
- Updating files.
✔ Created 4 files:
  - src/components/ui/card.tsx
  - src/components/ui/table.tsx
  - src/components/ui/tabs.tsx
  - src/components/ui/dialog.tsx
ℹ Skipped 1 file: (files might be identical, use --overwrite to overwrite)
  - src/components/ui/button.tsx

组件直接写入 src/components/ui/ —— 前提是已按环境与初始化第 3 节在根 tsconfig.json 也配好 @/* paths（否则会落到项目根字面 @/）。

2. 依赖如何自动解析

add 背后两层依赖：

registry 组件依赖（registryDependencies）：加 field 会连带装 label、separator；加 dialog 连带 button——实测一次 add 一组，依赖组件也被自动创建
npm 依赖（dependencies）：如 sonner 组件会安装 sonner 包；实测主题相关组件还会带进 next-themes（深浅色切换）

因此不必手工预装基元依赖——registry item 里声明了什么，CLI 装什么。

3. 常用组件清单（实测可用）

组件	用途	关键依赖/连带
`button`	按钮（init 自带）	`@base-ui/react/button` + CVA
`card`	卡片容器	—
`dialog`	模态对话框	`button` + `@base-ui/react/dialog`
`field`	表单字段（v4 表单核心）	`label` + `separator`
`input`	输入框	—
`label`	标签	—
`tabs`	标签页	`@base-ui/react/tabs`
`table`	表格	—（纯 HTML `<table>` 元素 + cn）
`badge`	徽标/标签	`merge-props` + `use-render`（Base UI 工具）
`sonner`	toast 通知	`sonner` npm 包

v4 registry 中 form 项是空 stub（files 为空），真实表单组件是 field （基于 Base UI Field）——表单请 add field。

4. v4 / Base UI 新用法范式

v4（style=base-nova）组件基于 Base UI，写法与旧版 Radix 有两大不同：

4.1 render prop 取代 asChild

旧版 Radix：<DialogTrigger asChild><Button/></DialogTrigger>。 Base UI 没有 asChild，用 render prop 注入元素（实测 dialog.tsx 内部 Dialog.Close render={<Button variant="outline" />}）：

<Dialog>
  <DialogTrigger render={<Button variant="secondary" />}>
    Open dialog
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>标题</DialogTitle>
      <DialogDescription>描述</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>

（实测：直接传 asChild 会类型报错，Base UI 没有这个 prop。）

示例放哪： 上面的整段代码直接替换 src/App.tsx 即可（组件 import 自 @/components/ui/…），保存后 pnpm dev 打开 http://localhost:5173 就能点开对话框看效果。前置：先 pnpm shadcn add dialog（自动连带 button）把组件装进项目。

4.2 Field 组合子组件，而非标签/错误 prop

Base UI 的 Field 是一组子组件（field.tsx 导出 Field / FieldLabel / FieldContent / FieldError / FieldDescription ...），不是 <Field label="..." error="..."> 那种 props 式 API：

<Field>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <FieldContent>
    <Input id="email" type="email" />
  </FieldContent>
  <FieldError>邮箱格式不正确</FieldError>
</Field>

4.3 cn() 与 CVA

@/lib/utils 的 cn()（4.20 起由 cn 包提供 —— utils.ts 仅一行 export { cn } from "cn"；类名合并 + 去重覆盖逻辑封装在包内）
组件变体用 class-variance-authority（CVA）：buttonVariants 导出 variant / size 两个维度，改样式 = 改 base/variants 字符串

5. 定制入门

方式	做法
改源码	组件就在 `src/components/ui/`，直接编辑（这就是 shadcn 的哲学：代码归你所有）
改变体	在 CVA 的 `variants` 里加/改 `variant`、`size`
改主题	动 `src/index.css` 的 oklch 变量（见进阶使用）
组合使用	`cn(buttonVariants({ variant: "outline" }), "自定义类")`

6. 参考链接

资源	链接
组件列表	https://ui.shadcn.com/docs/components
组件自定义	https://ui.shadcn.com/docs/components/customization
Base UI	https://base-ui.com/

→ 下一站：进阶使用

Backlinks (3)

flowchart LR
  n0["AI"]
  n1["Database"]
  n2["Dev Tools"]
  n3["Emoji"]
  n4["Frontend"]
  n5["Game Dev"]
  n6["Collection"]
  n7["Languages"]
  n8["Maps"]
  n9["Media"]
  n10["Monitor"]
  n11["Study Materials"]
  n12["Plans"]
  n13["Storage"]
  n14["对象存储基本用法（Bucket / Object / 常用操作）"]
  n15["挂载 Bucket 为本地文件系统（FUSE Mount）"]
  n16["对象存储签名 URL（Signed URL）原理与实战"]
  n17["对象存储供应商对比（S3 / R2 / OSS / Supabase / MinIO）"]
  n18["Prototypes"]
  n19["Research"]
  n20["Better Auth 源码阅读指南"]
  n21["DuckDB 环境与基本使用"]
  n22["DuckDB 实战研究"]
  n23["DuckDB 模拟数据"]
  n24["PostgreSQL 数据用 DuckDB 加速查询"]
  n25["HK 角色阅读"]
  n26["HK 台词阅读"]
  n27["Hollow Knight 英语主题"]
  n28["HK 物品阅读"]
  n29["HK 地点阅读"]
  n30["HK 世界观 / Lore 阅读"]
  n31["英语学习 Dashboard"]
  n32["English Scraps Archive"]
  n33["English Scraps 使用指南"]
  n34["Jellyfin 源码阅读指南"]
  n35["Lux 资料整理"]
  n36["Nest Commander 学习资料"]
  n37["NestJS 源码阅读指南"]
  n38["Protomaps 自建底图研究"]
  n39["自制 PMTiles 地图（最简单例子）"]
  n40["MapLibre 集成 Protomaps"]
  n41["PMTiles 格式与工具链"]
  n42["上海地区底图项目"]
  n43["Redash 源码阅读指南"]
  n44["Rust 学习计划"]
  n45["shadcn/ui 进阶使用"]
  n46["shadcn/ui 组件添加与基本使用"]
  n47["shadcn/ui 实用研究（从环境到基本使用）"]
  n48["shadcn/ui 环境与初始化"]
  n49["TRIP 项目核心原理与代码阅读指南"]
  n1 --> n22
  n1 --> n24
  n4 --> n47
  n6 --> n0
  n6 --> n1
  n6 --> n2
  n6 --> n3
  n6 --> n4
  n6 --> n5
  n6 --> n7
  n6 --> n8
  n6 --> n9
  n6 --> n10
  n6 --> n11
  n6 --> n12
  n6 --> n13
  n6 --> n19
  n14 --> n16
  n14 --> n17
  n14 --> n18
  n15 --> n14
  n15 --> n16
  n15 --> n17
  n16 --> n18
  n17 --> n14
  n17 --> n16
  n17 --> n18
  n18 --> n14
  n18 --> n15
  n18 --> n16
  n18 --> n17
  n18 --> n38
  n19 --> n20
  n19 --> n22
  n19 --> n31
  n19 --> n34
  n19 --> n35
  n19 --> n36
  n19 --> n37
  n19 --> n38
  n19 --> n43
  n19 --> n44
  n19 --> n47
  n19 --> n49
  n21 --> n23
  n22 --> n1
  n22 --> n19
  n22 --> n21
  n22 --> n23
  n22 --> n24
  n23 --> n21
  n23 --> n24
  n24 --> n22
  n24 --> n23
  n27 --> n25
  n27 --> n26
  n27 --> n28
  n27 --> n29
  n27 --> n30
  n27 --> n33
  n31 --> n27
  n31 --> n32
  n31 --> n33
  n33 --> n31
  n33 --> n32
  n38 --> n8
  n38 --> n39
  n38 --> n40
  n38 --> n41
  n38 --> n42
  n39 --> n41
  n40 --> n18
  n40 --> n42
  n41 --> n39
  n41 --> n42
  n42 --> n40
  n42 --> n41
  n45 --> n46
  n46 --> n45
  n46 --> n48
  n47 --> n4
  n47 --> n19
  n47 --> n45
  n47 --> n46
  n47 --> n48
  n48 --> n46
  click n0 "../../../../collection/ai/" "AI"
  click n1 "../../../../collection/database/" "Database"
  click n2 "../../../../collection/dev-tools/" "Dev Tools"
  click n3 "../../../../collection/emoji/" "Emoji"
  click n4 "../../../../collection/frontend/" "Frontend"
  click n5 "../../../../collection/game-dev/" "Game Dev"
  click n6 "../../../../collection/" "Collection"
  click n7 "../../../../collection/languages/" "Languages"
  click n8 "../../../../collection/maps/" "Maps"
  click n9 "../../../../collection/media/" "Media"
  click n10 "../../../../collection/monitor/" "Monitor"
  click n11 "../../../../collection/reading/" "Study Materials"
  click n12 "../../../../collection/scraps/plans/" "Plans"
  click n13 "../../../../collection/storage/" "Storage"
  click n14 "../../../../knowledge/infrastructure/cloud/object-storage/basic-usage/" "对象存储基本用法（Bucket / Object / 常用操作）"
  click n15 "../../../../knowledge/infrastructure/cloud/object-storage/mount-bucket/" "挂载 Bucket 为本地文件系统（FUSE Mount）"
  click n16 "../../../../knowledge/infrastructure/cloud/object-storage/signed-url/" "对象存储签名 URL（Signed URL）原理与实战"
  click n17 "../../../../knowledge/infrastructure/cloud/object-storage/vendors-comparison/" "对象存储供应商对比（S3 / R2 / OSS / Supabase / MinIO）"
  click n18 "../../../../prototypes/" "Prototypes"
  click n19 "../../../" "Research"
  click n20 "../../better-auth/" "Better Auth 源码阅读指南"
  click n21 "../../duckdb/basic-usage/" "DuckDB 环境与基本使用"
  click n22 "../../duckdb/" "DuckDB 实战研究"
  click n23 "../../duckdb/mock-data/" "DuckDB 模拟数据"
  click n24 "../../duckdb/postgresql-acceleration/" "PostgreSQL 数据用 DuckDB 加速查询"
  click n25 "../../english/hollow-knight/characters/" "HK 角色阅读"
  click n26 "../../english/hollow-knight/dialogues/" "HK 台词阅读"
  click n27 "../../english/hollow-knight/" "Hollow Knight 英语主题"
  click n28 "../../english/hollow-knight/items/" "HK 物品阅读"
  click n29 "../../english/hollow-knight/locations/" "HK 地点阅读"
  click n30 "../../english/hollow-knight/lore/" "HK 世界观 / Lore 阅读"
  click n31 "../../english/" "英语学习 Dashboard"
  click n32 "../../english/scraps/archive/" "English Scraps Archive"
  click n33 "../../english/scraps/" "English Scraps 使用指南"
  click n34 "../../jellyfin/" "Jellyfin 源码阅读指南"
  click n35 "../../lux/" "Lux 资料整理"
  click n36 "../../nest-commander/" "Nest Commander 学习资料"
  click n37 "../../nestjs/" "NestJS 源码阅读指南"
  click n38 "../../protomaps/" "Protomaps 自建底图研究"
  click n39 "../../protomaps/make-own-map/" "自制 PMTiles 地图（最简单例子）"
  click n40 "../../protomaps/maplibre/" "MapLibre 集成 Protomaps"
  click n41 "../../protomaps/pmtiles/" "PMTiles 格式与工具链"
  click n42 "../../protomaps/shanghai-map/" "上海地区底图项目"
  click n43 "../../redash/" "Redash 源码阅读指南"
  click n44 "../../rust/" "Rust 学习计划"
  click n45 "../advanced/" "shadcn/ui 进阶使用"
  click n46 "./" "shadcn/ui 组件添加与基本使用"
  click n47 "../" "shadcn/ui 实用研究（从环境到基本使用）"
  click n48 "../setup/" "shadcn/ui 环境与初始化"
  click n49 "../../trip/" "TRIP 项目核心原理与代码阅读指南"

Links (2)