Maofeng
54 lines
2.8 KiB
Plaintext
54 lines
2.8 KiB
Plaintext
---
|
|
title: 概览
|
|
description: 了解 @workspace/ui 的职责、上游基线和本仓库的扩展。
|
|
order: 1
|
|
toc:
|
|
- id: package-role
|
|
title: 包的职责
|
|
- id: source-model
|
|
title: 源码模型
|
|
- id: local-adaptations
|
|
title: 本地适配
|
|
- id: learning-path
|
|
title: 学习路线
|
|
- id: package-boundaries
|
|
title: 包边界
|
|
---
|
|
|
|
## 包的职责 {#package-role}
|
|
|
|
`@workspace/ui` 是整个工作区的视觉基础。它提供可编辑的 React 组件源码、Tailwind CSS 主题变量、响应式与交互 Hooks、统一图标入口，以及组件自身使用的本地化消息。
|
|
|
|
这个包只负责通用界面能力。路由、数据请求、持久化和业务流程仍由应用或领域 package 管理。
|
|
|
|
## 源码模型 {#source-model}
|
|
|
|
组件以 [shadcn/ui Base UI 版本](https://ui.shadcn.com/docs/components/base)和其 [GitHub registry 源码](https://github.com/shadcn-ui/ui/tree/main/apps/v4/registry/bases/base/ui)为基线。与 shadcn/ui 一样，它们不是不可修改的第三方黑盒：源码位于 `packages/ui/src`，可以直接审查、组合和演进。
|
|
|
|
本仓库使用 `base-vega` 风格、CSS 变量、Tailwind CSS v4、Base UI primitives 和 RTL 输出。`components.json` 只控制生成方式；运行时 API 以本仓库源码为准。
|
|
|
|
## 本地适配 {#local-adaptations}
|
|
|
|
本仓库在上游基础上做了这些有意保留的调整：
|
|
|
|
- 使用 `@icones/react` 封装统一的 `components/icon` 入口，不直接依赖 `lucide-react`。
|
|
- `Button` 默认接入指针波纹反馈。
|
|
- 增加 `I18nProvider`，让 Breadcrumb、Calendar、Carousel、Pagination、Sidebar、Toast 等组件使用应用的翻译器。
|
|
- 只发布 `en-US` 和 `zh-Hans` 两套 UI 词典与日历 locale。
|
|
- 增加 mobile、tablet、desktop 三段式断点 Hooks 和根节点 class 同步。
|
|
- 扩展 `PopoverContent` 的自定义锚点、定位方式、连续尾巴和独立滚动视口。
|
|
- 增加 `AnchoredSurface`，并保留消息、气泡、附件和消息滚动器等组合组件。
|
|
|
|
升级 shadcn/ui 组件时不要盲目覆盖这些差异。完整清单见“本仓库适配”。
|
|
|
|
## 学习路线 {#learning-path}
|
|
|
|
先完成“项目配置”，再通过“组件目录”确定入口；浮层和反馈类组件有独立指南。需要 SSR、响应式行为或多语言时，再阅读进阶章节。示例章节展示可直接组合进应用的完整结构。
|
|
|
|
## 包边界 {#package-boundaries}
|
|
|
|
- 使用 `@workspace/ui` 构建按钮、表单、菜单、弹层、列表和反馈等基础界面。
|
|
- 使用 `@workspace/blocks` 组合应用外壳、导航、聊天和通知等完整区域。
|
|
- 使用 `@workspace/media`、`@workspace/search`、`@workspace/lexical` 等 package 承载领域交互。
|
|
- 使用 `@workspace/appearance` 与 `@workspace/preferences` 聚合主题偏好和持久化。
|