68 lines
3.2 KiB
Plaintext
68 lines
3.2 KiB
Plaintext
|
---
|
||
|
|
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 下手动检查交互。
|