---
title: 本仓库适配
description: 记录相对 shadcn/ui Base UI 源码必须保留的实现差异与升级步骤。
order: 22
toc:
  - id: baseline
    title: 上游基线
  - id: icons-and-ripple
    title: 图标与波纹
  - id: localization
    title: 本地化
  - id: popover
    title: Popover 扩展
  - id: select
    title: Select 修正
  - id: upgrade-checklist
    title: 升级清单
---

## 上游基线 {#baseline}

本地组件最初来自 shadcn/ui 的 Base UI registry，配置风格为 `base-vega`。上游可参考 [组件文档](https://ui.shadcn.com/docs/components/base)和 [GitHub 源码目录](https://github.com/shadcn-ui/ui/tree/main/apps/v4/registry/bases/base/ui)，但上游当前版本不等于本仓库锁定的实现。

判断行为时按以下优先级：本地源码、本文档、本地 `components.json`，最后才是上游最新示例。

## 图标与波纹 {#icons-and-ripple}

`components/icon.tsx` 把 Lucide 图标名映射到 `@icones/react` 组件，并保留一批与上游同名的导出。已有组件已改为从该入口导入。CLI 新增或更新的源码如果出现 `lucide-react`，应转换到这个入口。

`Button` 合并传入 ref 与 `useRippleRef`。修改 Button 时必须保留 `relative` 定位、波纹 ref 合并和 disabled 行为。

## 本地化 {#localization}

Breadcrumb、Calendar、Carousel、Dialog、Pagination、Sheet、Sidebar、Spinner 与 Toast 等组件已移除部分硬编码英文，改用 `components/i18n.tsx` 中的消息描述符。更新这些文件时要检查 aria-label、sr-only 文本和默认说明，不能只比较可见 UI。

词典对外只发布 `en-US` 和 `zh-Hans`。新增消息时要同步：

1. `uiMessages` 描述符。
2. `uiMessageIds` 类型列表。
3. 两个 locale 的 `messages`。
4. 使用该消息的组件。

## Popover 扩展 {#popover}

本地 `PopoverContent` 比上游包装层多出：

- `anchor` 与 `positionMethod` 转发。
- `showArrow`，支持 `AnchoredSurface` 配置对象。
- `viewportClassName`，把可滚动内容与必须 overflow-visible 的外层表面分开。
- 按锚点尺寸计算的默认 side offset 与连续曲线尾巴。
- `createPopoverHandle` 与 `PopoverHandle` 导出。

不要用上游文件整体替换它。特别要测试长内容滚动、四个 side、碰撞翻转、窄触发器和 RTL。

## Select 修正 {#select}

`SelectTrigger` 把 `ChevronDownIcon` 作为 `SelectPrimitive.Icon` 的 child 渲染，而不是把图标组件交给 `render`。这是为当前 Base UI 与 Icones 组合保留的修正。升级 Select 时要确认 trigger 只出现一个图标，并验证 SSR 与 hydration。

## 升级清单 {#upgrade-checklist}

1. 先查看 shadcn 文档与对应 registry 源码的提交差异，不直接执行覆盖。
2. 通过 CLI 生成到临时分支或逐文件暂存，保留本地 public exports。
3. 将直接图标依赖迁回 `components/icon`。
4. 恢复翻译消息、逻辑方向 utility 与本地 theme class。
5. 对 Button、Popover、Select、Calendar、Toast 和 Sidebar 做重点回归。
6. 运行 UI typecheck、全仓 lint/format，再构建实际消费应用。
7. 在 light、dark、LTR、RTL、mobile、tablet、desktop 下手动检查交互。