安装
用 shadcn CLI 把组件装进你自己的项目
本站的每个组件都是一个 shadcn registry 项：/r/<组件名>.json。
shadcn CLI 读它，把源码写进你的项目，并装好依赖的组件、npm 包和主题。
安装组件
npx shadcn@latest add https://docs.linasan.cn/r/button.json第一次装本站任何一个组件时，CLI 会同时装上 theme：它把组件包的颜色、圆角、阴影、动画 token 写进你的全局 CSS。
也可以先单独装主题：
npx shadcn@latest add https://docs.linasan.cn/r/theme.json用短名安装（可选）
在 components.json 里登记本站为一个命名空间：
{
"registries": {
"@linasan": "https://docs.linasan.cn/r/{name}.json"
}
}之后就能这样装：
npx shadcn@latest add @linasan/data-table @linasan/schema-form装了什么
| 内容 | 放在哪 |
|---|---|
基础组件（components/ui/*） | components.json 的 aliases.ui，通常是 components/ui/ |
其他组件（data-table/、form/、upload/……） | aliases.components 下保持原来的目录，如 components/data-table/data-table.tsx |
cn | 你项目自己的 lib/utils.ts（shadcn 的 utils） |
其余小函数（formatBytes、formatNumber……） | lib/linasan-utils.ts |
| 主题 token | 你的全局 CSS（components.json 的 tailwind.css） |
源码里的导入都写成 @/components/...、@/lib/...，CLI 会按你 components.json 里的别名改写。
全部项
每个组件文件都是一项，依赖会自动带上。文档页没有单独介绍的内部部件（如 header-filters、cell-types）也可以按名字单独安装。
| 名字 | 安装到 | 说明 |
|---|---|---|
advanced-table | @components/advanced-table/advanced-table.tsx | 高级表格：多级表头、固定首尾列（滚动后边缘出现阴影）、单击排序 / Shift 追加次级排序、 |
cell-types | @components/advanced-table/cell-types.tsx | |
column-settings-panel | @components/advanced-table/column-settings-panel.tsx | 列设置面板：勾选显示、拖拽排序、图钉固定到左侧；主列和操作列始终显示 |
editable-cell | @components/advanced-table/editable-cell.tsx | 单元格编辑：悬停出现铅笔，单击进入编辑；Enter 保存、Esc 取消、Tab 到下一格； |
header-filters | @components/advanced-table/header-filters.tsx | |
selection-bar | @components/advanced-table/selection-bar.tsx | 选中提示栏：勾选后出现在表格上方，只作用于选中行；可附带选中项的汇总 |
table-tools | @components/advanced-table/table-tools.tsx | 工具栏选项：刷新 · 行高 · 列设置 · 全屏。排在业务操作之后，用竖线隔开；悬停显示名称 |
virtual-table | @components/advanced-table/virtual-table.tsx | 虚拟滚动表格：只渲染可见区域；行高固定；快速拖动时先画占位行，停下后补齐内容； |
auth-layout | @components/auth/auth-layout.tsx | 登录 / 注册 / 找回密码的居中卡片布局（HeroUI 风格）： |
brand-icons | @components/auth/brand-icons.tsx | |
password-input | @components/auth/password-input.tsx | 密码框：右侧显示 / 隐藏切换 |
chart-points | @components/charts/chart-points.ts | |
sparkline | @components/charts/sparkline.tsx | 迷你折线 |
trend-chart | @components/charts/trend-chart.tsx | 资源趋势折线图：主序列实线 + 面积，次序列虚线 |
columns | @components/data-grid/columns.tsx | |
data-grid | @components/data-grid/data-grid.tsx | |
grid-toolbar | @components/data-grid/grid-toolbar.tsx | |
data-grid-types | @components/data-grid/types.ts | |
use-data-grid | @components/data-grid/use-data-grid.tsx | |
data-table | @components/data-table/data-table.tsx | 通用表格：网格线、表头 38 / 行 42（紧凑 32 / 34），右侧操作列固定 |
search-form | @components/data-table/search-form.tsx | 筛选区：默认显示 3 个最常用条件，其余收进“展开”；搜索、重置、展开统一放最右侧 |
table-action | @components/data-table/table-action.tsx | 表格操作列 / 一组操作按钮：提示、气泡确认、加载与禁用、按条件显示、权限过滤、 |
table-card | @components/data-table/table-card.tsx | 表格卡片外壳 |
data-table-types | @components/data-table/types.tsx | |
check-list | @components/display/check-list.tsx | 逐项检查列表（连接测试） |
code-block | @components/display/code-block.tsx | |
copy-button | @components/display/copy-button.tsx | 图标复制按钮；复制后 2 秒内显示“已复制” |
file-icon | @components/display/file-icon.tsx | |
file-preview | @components/display/file-preview.tsx | The preview area of a file: fills its parent (a flex column) |
html-frame | @components/display/html-frame.tsx | Renders untrusted HTML (协议、富文本) in a sandboxed iframe: no scripts, |
kv-list | @components/display/kv-list.tsx | |
stat-card | @components/display/stat-card.tsx | 指标卡：标签 + 大数字 + 说明。可点击（与筛选联动时高亮描边） |
status-dot | @components/display/status-dot.tsx | |
stepper | @components/display/stepper.tsx | 步骤条：圆形序号 + 文案 + 连线；完成的步骤显示对勾 |
timeline | @components/display/timeline.tsx | |
doc-page | @components/docs/doc-page.tsx | 组件文档页：分类 + 衬线大标题 + 导语 |
error-view | @components/error/error-view.tsx | 错误页：大号衬线状态码 + 标题 + 说明 + 操作 + 附加信息；背景为淡出的网格 |
callout | @components/feedback/callout.tsx | 提示块 / 横幅 |
confirm-dialog | @components/feedback/confirm-dialog.tsx | 确认弹窗（弹窗规范 v1 · S 440）：图标 + 问句标题 + 后果说明 + 可选附加区 + 操作区 |
empty-state | @components/feedback/empty-state.tsx | 空状态：图标块 + 标题 + 说明 + 下一步操作 |
popconfirm | @components/feedback/popconfirm.tsx | 气泡确认（弹窗规范 v1）：锚定在触发按钮旁，宽 260、圆角 10 |
result-dialog | @components/feedback/result-dialog.tsx | 结果弹窗：耗时操作（测试连接、批量导入）结束后单独成窗，居中排版 |
choice-chips | @components/form/choice-chips.tsx | 胶囊多选（岗位、角色、水印内容、生效范围） |
color-swatches | @components/form/color-swatches.tsx | 色块选择（主题色、文件夹颜色标记） |
combobox | @components/form/combobox.tsx | |
date-picker | @components/form/date-picker.tsx | 日期选择：外观同输入框，点开是日历 |
date-range-picker | @components/form/date-range-picker.tsx | 日期区间：两个月并排，先点开始再点结束，悬停预览区间；左侧是快捷区间 |
icon-picker | @components/form/icon-picker.tsx | 图标选择（菜单图标、文件类型图标） |
icon-select | @components/form/icon-select.tsx | |
logo-select | @components/form/logo-select.tsx | Logo 选择：左侧预览，右侧在「图标」与「图片」之间切换 |
number-input | @components/form/number-input.tsx | |
secret-input | @components/form/secret-input.tsx | A write-only secret (API key, client secret…). Once one is saved it shows |
svg-icon | @components/form/svg-icon.tsx | 把存储的 SVG 图标值变成和 lucide 图标同样用法的组件（渲染前再净化一次） |
tag-input | @components/form/tag-input.tsx | 标签输入：回车添加、退格删除最后一个（扩展名、标签） |
crop-core | @components/image-crop/crop-core.ts | |
image-crop-dialog | @components/image-crop/image-crop-dialog.tsx | |
image-cropper | @components/image-crop/image-cropper.tsx | 裁剪舞台：拖动裁剪框和手柄，框外拖动图片，滚轮与双指缩放 |
app-layout | @components/layout/app-layout.tsx | |
app-settings-dialog | @components/layout/app-settings-dialog.tsx | 应用配置：左边主题、导航菜单，右边工具栏；改动立即生效 |
command-menu | @components/layout/command-menu.tsx | 全局搜索弹窗（⌘K）：范围切换（全部 / 页面 / 操作），无结果时引导去数据中搜索 |
layout-text | @components/layout/layout-text.tsx | |
notifications-popover | @components/layout/notifications-popover.tsx | 通知中心（顶栏铃铛） |
page-tabs | @components/layout/page-tabs.tsx | 页签栏：顶栏下方列出打开过的页面。放不下时两端出现翻页按钮， |
sidebar | @components/layout/sidebar.tsx | 侧边栏：标准 / 浮动 / 内嵌 / 双栏 / 混合（双栏时品牌标记移到左侧图标栏，混合时在顶栏） |
tenant-switcher | @components/layout/tenant-switcher.tsx | 切换租户 |
theme-menu | @components/layout/theme-menu.tsx | 主题切换菜单（顶栏太阳 / 月亮图标） |
top-nav | @components/layout/top-nav.tsx | 水平 / 混合布局的顶栏：品牌 | 菜单（放不下的收进「更多」）…… 搜索、外观、通知、头像 |
topbar | @components/layout/topbar.tsx | 顶栏：侧边栏开关 | 面包屑 …… 搜索、租户、外观、主题、通知、头像 |
layout-types | @components/layout/types.tsx | |
user-menu | @components/layout/user-menu.tsx | 头像菜单 |
page-header | @components/page/page-header.tsx | 页面标题区：标题 24 常规字重 + 说明，页面级操作放右侧 |
setting-row | @components/page/setting-row.tsx | |
qr-code | @components/qrcode/qr-code.tsx | |
qr-share | @components/qrcode/qr-share.tsx | |
resource-input | @components/resource-picker/resource-input.tsx | 输入框形态：超出时折叠为 +N |
resource-picker | @components/resource-picker/resource-picker.tsx | |
field-components | @components/schema-form/field-components.tsx | |
resolve-field | @components/schema-form/resolve-field.ts | 算出一个字段此刻的状态：联动、规则、控件属性 |
run-rules | @components/schema-form/run-rules.ts | 依次跑规则，返回第一条错误。同步规则全部同步返回；遇到 async 规则后， |
schema-form-array | @components/schema-form/schema-form-array.tsx | 表单数组：表头是子字段的标签，一行一组控件，行尾删除，底部添加 |
schema-form-context | @components/schema-form/schema-form-context.ts | |
schema-form-dialog | @components/schema-form/schema-form-dialog.tsx | |
schema-form-item | @components/schema-form/schema-form-item.tsx | 一个表单项。`bare` 时只有控件和错误（数组表格的单元格） |
schema-form-nodes | @components/schema-form/schema-form-nodes.tsx | 按 schema 渲染一串表单项：字段、数组、分组、分割线 |
schema-form | @components/schema-form/schema-form.tsx | |
schema-search-form | @components/schema-form/schema-search-form.tsx | 列表页的筛选区：按 schema 渲染，受控（`values` 通常是页面的 draft，筛选标签、表头筛选改了它，这里跟着变） |
schema-form-types | @components/schema-form/types.tsx | |
use-auto-label-width | @components/schema-form/use-auto-label-width.ts | 水平布局 `labelWidth: 'auto'`：量出所有可见标签的自然宽度，取最大的写进 |
use-collapsed-fields | @components/schema-form/use-collapsed-fields.ts | 查询表单收起时藏哪些顶层项：按栅格当前的列数排，前 `rows` 行装得下的留下， |
use-schema-form | @components/schema-form/use-schema-form.tsx | |
tree-check-state | @components/tree/tree-check-state.tsx | |
tree-check | @components/tree/tree-check.tsx | 菜单权限树（弹窗内）：工具栏（展开 / 折叠 / 全选 / 全不选 / 已选计数）+ 带类型标签的勾选树 |
accordion | @ui/accordion.tsx | 折叠面板：`type="single"` 一次只展开一项（`collapsible` 允许全收起），`type="multiple"` 可同时展开 |
avatar | @ui/avatar.tsx | 头像：无图片时显示首字，32/28/24/64 尺寸 |
badge | @ui/badge.tsx | |
breadcrumb | @ui/breadcrumb.tsx | |
button | @ui/button.tsx | |
calendar | @ui/calendar.tsx | 日历：周一开头，今天带下划点，选中为主色实心，区间中间为浅主色 |
card | @ui/card.tsx | |
checkbox | @ui/checkbox.tsx | |
collapsible | @ui/collapsible.tsx | |
command | @ui/command.tsx | |
context-menu | @ui/context-menu.tsx | |
dialog | @ui/dialog.tsx | 弹窗根节点。受控与非受控都支持；busy / dirty 只拦截“关闭”，不影响打开 |
dropdown-menu | @ui/dropdown-menu.tsx | |
field | @ui/field.tsx | 表单项：标签 + 控件 + 说明 / 错误 |
hover-card | @ui/hover-card.tsx | 悬停卡片：鼠标停在人名、链接、编号上时浮出的资料卡，比 Tooltip 能放更多内容（头像、统计、按钮） |
input-otp | @ui/input-otp.tsx | |
input | @ui/input.tsx | |
kbd | @ui/kbd.tsx | |
label | @ui/label.tsx | |
menu-specimen | @ui/menu-specimen.tsx | |
menu-styles | @ui/menu-styles.ts | |
popover | @ui/popover.tsx | |
progress | @ui/progress.tsx | 进度条：高 4 / 6，失败变红 |
radio-group | @ui/radio-group.tsx | |
scroll-area | @ui/scroll-area.tsx | 滚动区域：细滚动条、无轨道，悬停或滚动时才浮现，各系统外观一致 |
segmented | @ui/segmented.tsx | |
select | @ui/select.tsx | |
separator | @ui/separator.tsx | |
sheet | @ui/sheet.tsx | |
skeleton | @ui/skeleton.tsx | |
slider | @ui/slider.tsx | |
sonner | @ui/sonner.tsx | |
spinner | @ui/spinner.tsx | |
switch | @ui/switch.tsx | |
table | @ui/table.tsx | 网格表格：细边框、列间竖线、表头 38 / 行 42（紧凑 32 / 34） |
tabs | @ui/tabs.tsx | |
textarea | @ui/textarea.tsx | |
tooltip | @ui/tooltip.tsx | 便捷 Tooltip |
avatar-upload | @components/upload/avatar-upload.tsx | 头像上传：裁剪为正方形，小于 2 MB |
image-wall | @components/upload/image-wall.tsx | 图片墙：首张为封面，上传中与失败在格子内显示 |
upload-task-panel | @components/upload/upload-task-panel.tsx | 全局上传任务面板：离开当前页面后继续上传，固定在右下角；可收起为胶囊 |
upload | @components/upload/upload.tsx | |
use-upload-queue | @components/upload/use-upload-queue.tsx | 上传队列：同时 3 个并发，其余排队；失败可就地重试。传入 `uploader` 时真实上传 |
use-virtual-list | @components/virtual/use-virtual-list.tsx | Headless virtual list on TanStack Virtual: renders only the rows in view plus |
watermark | @components/watermark/watermark.tsx | |
tree | @lib/tree.ts | |
linasan-utils | @lib/linasan-utils.ts | |
theme | CSS | @linasan/ui 的设计 token（颜色、圆角、阴影、动画）和工具类 |
文档站的地址
本页的命令都指向文档站自己的地址，它在构建时由 DOCS_URL 给出（本地开发是 dev 地址）。
生成的 registry 里组件之间的引用、各页面的安装命令都用它，所以部署后命令可以直接复制使用。
随系统一起部署时，文档站和后台由同一个 nginx 提供，地址是 PUBLIC_URL/docs/（Docker 镜像和 bun run deploy build 会自动构建，见 deploy/README.md）。
单独构建：
DOCS_URL=https://ui.example.com DOCS_BASE=/ bun run --filter @linasan/docs buildDOCS_BASE 是站点所在的路径，默认 /docs，用独立域名时设为 /。产物在 apps/frontend/docs/out/，是纯静态文件，交给任意静态服务器即可。