feat(docs): add bilingual package documentation site
This commit is contained in:
Maofeng
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: 添加响应式行为
|
||||
description: 当 CSS 无法表达行为变化时，使用共享的断点和交互 Hooks。
|
||||
order: 20
|
||||
toc:
|
||||
- id: breakpoints
|
||||
title: 断点
|
||||
- id: server-rendering
|
||||
title: 服务端渲染
|
||||
- id: ripple
|
||||
title: 波纹交互
|
||||
---
|
||||
|
||||
## 断点 {#breakpoints}
|
||||
|
||||
```tsx
|
||||
import { useBreakpoint, useIsMobile } from "@workspace/ui/hooks/use-breakpoint"
|
||||
|
||||
const breakpoint = useBreakpoint()
|
||||
const isMobile = useIsMobile()
|
||||
```
|
||||
|
||||
视觉变化优先使用 CSS 响应式变体。只有组件行为或挂载内容必须变化时才使用这些 Hooks。
|
||||
|
||||
## 服务端渲染 {#server-rendering}
|
||||
|
||||
断点 Store 使用确定的桌面端服务端快照。当应用需要 CSS 与行为断点在水合前保持一致时，可用 `getBreakpointInitializationScript` 提前设置匹配的根节点类名。
|
||||
|
||||
## 波纹交互 {#ripple}
|
||||
|
||||
`useRipple` 返回一个 ref 回调，为交互元素加入指针反馈。元素应创建定位上下文，使生成的覆盖层使用正确边界。
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: UI 本地化
|
||||
description: 只加载当前语言所需的 UI 词典和日历 locale。
|
||||
order: 21
|
||||
toc:
|
||||
- id: catalog-source
|
||||
title: 词典来源
|
||||
- id: direct-imports
|
||||
title: 直接导入
|
||||
- id: supported-locales
|
||||
title: 支持的语言
|
||||
---
|
||||
|
||||
## 词典来源 {#catalog-source}
|
||||
|
||||
在应用国际化配置中加入 UI 词典来源：
|
||||
|
||||
```json
|
||||
{
|
||||
"catalogSources": ["@workspace/ui/locales/{locale}"]
|
||||
}
|
||||
```
|
||||
|
||||
locales 根入口只包含元数据和类型，不会导入所有语言的词典。
|
||||
|
||||
## 直接导入 {#direct-imports}
|
||||
|
||||
```ts
|
||||
import { calendarLocale, messages } from "@workspace/ui/locales/zh-Hans"
|
||||
```
|
||||
|
||||
每个语言入口还会导出对应的 `react-day-picker` locale。
|
||||
|
||||
## 支持的语言 {#supported-locales}
|
||||
|
||||
UI 词典支持简体中文（`zh-Hans`）和美式英语（`en-US`）。
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: 组合表单
|
||||
description: 组合 Field、Input 和 Button，同时让领域状态继续由应用管理。
|
||||
order: 30
|
||||
toc:
|
||||
- id: create-the-form
|
||||
title: 创建表单
|
||||
- id: validation
|
||||
title: 表单验证
|
||||
- id: styling
|
||||
title: 样式
|
||||
---
|
||||
|
||||
## 创建表单 {#create-the-form}
|
||||
|
||||
```tsx
|
||||
import { Button } from "@workspace/ui/components/button"
|
||||
import { Field, FieldError, FieldLabel } from "@workspace/ui/components/field"
|
||||
import { Input } from "@workspace/ui/components/input"
|
||||
|
||||
;<form onSubmit={saveProfile}>
|
||||
<Field>
|
||||
<FieldLabel htmlFor="display-name">显示名称</FieldLabel>
|
||||
<Input id="display-name" name="displayName" />
|
||||
<FieldError>{errors.displayName}</FieldError>
|
||||
</Field>
|
||||
<Button type="submit">保存资料</Button>
|
||||
</form>
|
||||
```
|
||||
|
||||
## 表单验证 {#validation}
|
||||
|
||||
UI 包负责渲染验证状态，但不会指定表单库或 Schema。请在应用边界连接原生表单数据、React 状态或表单框架。
|
||||
|
||||
## 样式 {#styling}
|
||||
|
||||
受支持的语义变化使用组件变体，局部布局使用 `className`。需要合并条件类名或消费者覆盖时，使用 `@workspace/ui/lib/utils` 中的 `cn`。
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: 选择组件
|
||||
description: 按职责选择基础组件，而不是导入一个庞大的统一组件入口。
|
||||
order: 11
|
||||
toc:
|
||||
- id: forms
|
||||
title: 表单与输入
|
||||
- id: overlays
|
||||
title: 浮层与菜单
|
||||
- id: content
|
||||
title: 内容与反馈
|
||||
- id: icons
|
||||
title: 图标
|
||||
---
|
||||
|
||||
## 表单与输入 {#forms}
|
||||
|
||||
普通表单可使用 `Button`、`Input`、`Textarea`、`Field` 和 `Label`。选择类输入可加入 `Checkbox`、`RadioGroup`、`Switch` 或 `Slider`；更丰富的选择场景可使用 `Select`、`Combobox`、`Command` 或 `Calendar`。
|
||||
|
||||
## 浮层与菜单 {#overlays}
|
||||
|
||||
`Dialog`、`AlertDialog`、`Sheet` 和 `Drawer` 用于模态界面。`Popover`、`HoverCard` 和 `Tooltip` 用于锚定式信息展示，菜单模块则覆盖上下文菜单、下拉菜单、菜单栏和导航模式。
|
||||
|
||||
## 内容与反馈 {#content}
|
||||
|
||||
卡片、列表项、表格、图表、进度条、骨架屏、加载器、空状态、消息和 Toast 构成通用展示词汇。Accordion、Collapsible、Tabs、Carousel 和 Pagination 用于组织更大规模的内容。
|
||||
|
||||
## 图标 {#icons}
|
||||
|
||||
从 `@workspace/ui/components/icon` 导入具名图标。该模块统一了 `@icones/react` 的图标词汇，使应用和各个包使用同一图标来源。
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: 项目配置
|
||||
description: 导入全局样式，并从显式组件子路径开始使用。
|
||||
order: 10
|
||||
toc:
|
||||
- id: import-styles
|
||||
title: 导入样式
|
||||
- id: import-a-component
|
||||
title: 导入组件
|
||||
- id: entry-points
|
||||
title: 包入口
|
||||
---
|
||||
|
||||
## 导入样式 {#import-styles}
|
||||
|
||||
在应用入口中导入一次全局样式：
|
||||
|
||||
```ts
|
||||
import "@workspace/ui/globals.css"
|
||||
```
|
||||
|
||||
它提供组件所需的共享 Tailwind 层、设计变量、字体配置和工具类。
|
||||
|
||||
## 导入组件 {#import-a-component}
|
||||
|
||||
```tsx
|
||||
import { Button } from "@workspace/ui/components/button"
|
||||
|
||||
export function SaveButton() {
|
||||
return <Button>保存</Button>
|
||||
}
|
||||
```
|
||||
|
||||
## 包入口 {#entry-points}
|
||||
|
||||
- `@workspace/ui/components/*` 导出单个组件模块。
|
||||
- `@workspace/ui/hooks/*` 导出可复用的交互和媒体查询状态。
|
||||
- `@workspace/ui/lib/utils` 导出共享的类名组合工具。
|
||||
- `@workspace/ui/locales/*` 导出指定语言的词典。
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: 概览
|
||||
description: 了解 UI 包的定位，以及显式入口如何支持组件组合。
|
||||
order: 1
|
||||
toc:
|
||||
- id: package-role
|
||||
title: 包的职责
|
||||
- id: tutorial-map
|
||||
title: 教程路线
|
||||
- id: ui-or-blocks
|
||||
title: UI 还是 Blocks
|
||||
---
|
||||
|
||||
## 包的职责 {#package-role}
|
||||
|
||||
`@workspace/ui` 包含可复用的 React 基础组件、复合控件、Hooks、图标、样式和本地化词典。它是应用与上层功能包共享的视觉基础。
|
||||
|
||||
## 教程路线 {#tutorial-map}
|
||||
|
||||
本教程会安装样式、介绍组件子路径、通过组合构建一个小型表单、添加响应式行为，并接入本地化词典。
|
||||
|
||||
## UI 还是 Blocks {#ui-or-blocks}
|
||||
|
||||
当应用自己拥有业务流程时使用 UI 组件。当界面还需要导航、媒体存储、搜索适配器或通知查询等完整功能契约时，使用 `@workspace/blocks`。
|
||||
Reference in New Issue
Block a user