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,45 @@
+---
+title: 应用外壳
+description: 组装共享 Header、Sidebar、面包屑、聊天和通知界面。
+order: 11
+toc:
+  - id: render-app-layout
+    title: 渲染 AppLayout
+  - id: layout-inputs
+    title: 布局输入
+  - id: optional-preset
+    title: 可选预设
+---
+
+## 渲染 AppLayout {#render-app-layout}
+
+`AppLayout` 是本教程其余部分的集成点：
+
+```tsx
+import { AppLayout } from "@workspace/blocks/layout"
+
+export function WorkspaceLayout() {
+  return (
+    <AppLayout
+      navigationGroups={navigationGroups}
+      notifications={{
+        queryKey: ["notifications"],
+        queryFn: loadNotifications,
+      }}
+      chatThreads={chatThreads}
+    >
+      <Outlet />
+    </AppLayout>
+  )
+}
+```
+
+## 布局输入 {#layout-inputs}
+
+应用外壳组合了 `AppSidebar`、`AppBreadcrumb`、`AppQueryIndicator`、`UserMenu`、通知 Sheet 和聊天线程。产品需要更多全局控件时可传入 `headerActions`。
+
+路由内容仍作为布局的 `children`，因此该包不会限制应用使用的路由器。
+
+## 可选预设 {#optional-preset}
+
+`@workspace/blocks/layouts/vega` 提供可选的视觉外壳。它位于独立入口，因此标准布局不会包含预设专属代码。
@@ -0,0 +1,40 @@
+---
+title: 安装
+description: 添加教程所需的包、样式和 Providers。
+order: 10
+toc:
+  - id: add-the-package
+    title: 添加包
+  - id: import-styles
+    title: 导入样式
+  - id: application-providers
+    title: 应用 Providers
+---
+
+## 添加包 {#add-the-package}
+
+在使用方应用中添加工作区依赖：
+
+```json
+{
+  "dependencies": {
+    "@workspace/blocks": "workspace:*"
+  }
+}
+```
+
+Blocks 使用 `@workspace/ui`、React Query 和工作区国际化运行时。工作区包管理器会为本地应用解析这些依赖。
+
+## 导入样式 {#import-styles}
+
+在应用入口导入一次 Block 样式：
+
+```ts
+import "@workspace/blocks/globals.css"
+```
+
+功能模块应始终从显式子路径导入。例如，导入 `@workspace/blocks/media` 不会把聊天功能加入同一个模块图。
+
+## 应用 Providers {#application-providers}
+
+完整应用外壳要求上层已经提供 React Query 和国际化。在路由树之前加入这些 Providers，然后继续应用外壳章节。
@@ -0,0 +1,46 @@
+---
+title: 导航
+description: 统一定义导航分组，并将其连接到桌面和移动端界面。
+order: 12
+toc:
+  - id: define-groups
+    title: 定义分组
+  - id: provide-navigation
+    title: 提供导航
+  - id: route-state
+    title: 路由状态
+---
+
+## 定义分组 {#define-groups}
+
+从类型安全的 `NavigationGroup` 开始。导航项可以是直接路由，也可以是嵌套导航分支。
+
+```ts
+import type { NavigationGroup } from "@workspace/blocks/navigation"
+
+export const navigationGroups: NavigationGroup[] = [
+  {
+    id: "workspace",
+    label: "工作区",
+    items: [
+      { id: "dashboard", label: "仪表盘", to: "/dashboard" },
+      { id: "media", label: "媒体", to: "/media" },
+    ],
+  },
+]
+```
+
+## 提供导航 {#provide-navigation}
+
+`AppLayout` 已经挂载 Provider 和响应式导航界面。自定义外壳可以直接组合它们：
+
+```tsx
+<NavigationProvider groups={navigationGroups}>
+  <PrimaryNavigation groups={navigationGroups} />
+  <MobileNavigationSheet groups={navigationGroups} />
+</NavigationProvider>
+```
+
+## 路由状态 {#route-state}
+
+标准路由模型使用 `resolveNavigationRouteState`。使用自定义路由的应用可以提供 `GetNavigationRouteState` 实现，同时复用相同导航 UI。