feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,40 @@
+---
+title: 外观设置
+description: 使用可持久化的主题、颜色和紧凑布局偏好完成应用。
+order: 22
+toc:
+  - id: provide-ui-state
+    title: 提供 UI 状态
+  - id: apply-preferences
+    title: 应用偏好
+  - id: add-locales
+    title: 添加词典
+---
+
+## 提供 UI 状态 {#provide-ui-state}
+
+在应用根节点附近挂载 `UiStateProvider`。受控 Provider 可以通过变更处理器持久化每次状态更新。
+
+```tsx
+<UiStateProvider>
+  <AppearanceController />
+  <App />
+  <ThemeToggleButton />
+</UiStateProvider>
+```
+
+## 应用偏好 {#apply-preferences}
+
+渲染一次 `AppearanceController`，使当前状态转换为文档类名和主题变量。`useUiState` 读取或更新单个偏好，`useResolvedTheme` 在解析系统模式后返回最终的亮色或暗色主题。
+
+## 添加词典 {#add-locales}
+
+只有应用使用这些控件时才添加外观词典：
+
+```json
+{
+  "catalogSources": ["@workspace/blocks/appearance/locales/{locale}"]
+}
+```
+
+至此应用外壳已经完成。其他功能也只需添加产品实际使用的 Block 词典。
@@ -0,0 +1,34 @@
+---
+title: 媒体库
+description: 提供存储 Adapter，并加入浏览、上传、文件夹和资源选择能力。
+order: 21
+toc:
+  - id: implement-the-adapter
+    title: 实现 Adapter
+  - id: provide-media
+    title: 提供媒体能力
+  - id: selection-flows
+    title: 选择流程
+---
+
+## 实现 Adapter {#implement-the-adapter}
+
+`MediaAdapter` 是媒体功能完整的持久化边界。通过产品存储服务实现查询、上传、文件夹、更新和删除操作。
+
+## 提供媒体能力 {#provide-media}
+
+在媒体界面外挂载一次 Adapter：
+
+```tsx
+import { MediaLibrary, MediaProvider } from "@workspace/blocks/media"
+
+;<MediaProvider adapter={mediaAdapter} notify={showNotice}>
+  <MediaLibrary />
+</MediaProvider>
+```
+
+可选的 `notify` 回调把操作结果转换为应用的 Toast 或通知。
+
+## 选择流程 {#selection-flows}
+
+单选或多选资源使用 `MediaPickerDialog`。`readMediaDimensions`、`formatMediaFileSize` 和 `defaultMediaReference` 覆盖上传与预览相关的常用展示工作。
@@ -0,0 +1,21 @@
+---
+title: 通知
+description: 接入通知状态，同时避免让 UI 与后端耦合。
+order: 20
+toc:
+  - id: notifications-query
+    title: 通知查询
+---
+
+## 通知查询 {#notifications-query}
+
+通知以 TanStack Query 作为数据边界：
+
+```tsx
+const notifications = useNotifications({
+  queryKey: ["notifications"],
+  queryFn: loadNotifications,
+})
+```
+
+返回结果包含未读数量、乐观已读更新、操作执行、重新请求以及等待和错误状态。`AppLayout` 可以直接通过相同查询选项创建通知 Sheet。