docs(layout): document app layout composition

2026-09-30 01:30:56 +08:00
parent ffda0b9099
commit 57d006a39b
10 changed files with 573 additions and 0 deletions
@@ -0,0 +1,40 @@
+---
+title: 配置与有效布局
+description: 管理受控配置、持久化偏好和区域自动内移。
+order: 20
+toc:
+  - id: controlled
+    title: 受控与非受控
+  - id: effective
+    title: 有效布局
+  - id: persistence
+    title: 持久化
+---
+
+## 受控与非受控 {#controlled}
+
+未提供 `layout` 时，`AppLayout` 使用内部状态：
+
+```tsx
+<AppLayout defaultLayout={{ sidebarOpen: false }} sidebar={NavigationSidebar}>
+  <RouterOutlet />
+</AppLayout>
+```
+
+提供 `layout` 后，调用方必须在 `onLayoutChange` 中保存新快照：
+
+```tsx
+<AppLayout layout={layout} onLayoutChange={setLayout} aside={AssistantPanel}>
+  <RouterOutlet />
+</AppLayout>
+```
+
+## 有效布局 {#effective}
+
+配置保存用户意图，有效布局负责当前渲染。例如 `asideOpen` 可以为 `true`，但没有 Aside slot 或 `asideEnabled` 为 `false` 时不会渲染 Aside。`sidebarCollapsible` 为 `false` 时，即使保存的 `sidebarOpen` 为 `false`，Sidebar 也会保持显示。
+
+Header 和 Footer 的起始位置遵循同样原则。只有 Rail 与 Sidebar 同时可见时，`"sidebar"` 才会生效；否则自动内移到 `"content"`。
+
+## 持久化 {#persistence}
+
+有效布局不会反向修改配置，因此临时缺少某个区域不会清除用户偏好。应用可以在 `onLayoutChange` 中把完整 `LayoutConfig` 写入 `@workspace/preferences`，并在加载时通过 `layout` 传回。