141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
|
# Layout
|
|||
|
|
|
|||
|
|
`@workspace/layout` 提供路由无关的应用级布局。`AppLayout` 以内容区为核心，并按需组合 Header、Navigation Rail、Sidebar、Aside 和 Footer。
|
|||
|
|
|
|||
|
|
## 安装样式源
|
|||
|
|
|
|||
|
|
在应用的全局样式中导入：
|
|||
|
|
|
|||
|
|
```css
|
|||
|
|
@import "@workspace/layout/globals.css";
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 布局模型
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
+-------------------------------------+
|
|||
|
|
| header | headerStart="rail"
|
|||
|
|
+------+---------+---------+----------+
|
|||
|
|
| | header | headerStart="sidebar"
|
|||
|
|
| +---------+---------+----------+
|
|||
|
|
| | | header | headerStart="content"
|
|||
|
|
| | +---------+----------+
|
|||
|
|
| | | | |
|
|||
|
|
| rail | sidebar | content | |
|
|||
|
|
| | +---------+ aside |
|
|||
|
|
| | | footer | | footerStart="content"
|
|||
|
|
| +---------+---------+ |
|
|||
|
|
| | footer | | footerStart="sidebar"
|
|||
|
|
+------+-------------------+----------+
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图中的多个 Header 和 Footer 表示可选位置，不会同时渲染。`children` 是唯一必需的内容区，其他区域均为可选 slot：
|
|||
|
|
|
|||
|
|
- `rail`：最外侧的一级导航，类似 Activity Bar。
|
|||
|
|
- `sidebar`：当前一级导航下的导航或工作区上下文。
|
|||
|
|
- `aside`：AI、文档、检查器等内容辅助区域。
|
|||
|
|
- `header`：右边界始终包含有效的 `aside`。
|
|||
|
|
- `footer`：始终属于中心工作区，不会延伸到 `rail` 或 `aside` 下方。
|
|||
|
|
|
|||
|
|
## 基本用法
|
|||
|
|
|
|||
|
|
Slot 可以接收已经创建的 React 节点，也可以接收无必需属性的组件定义。组件定义在 `AppLayout` 的 Provider 内创建，因此可以调用 `useLayoutConfig`。
|
|||
|
|
|
|||
|
|
```tsx
|
|||
|
|
import { AppLayout } from "@workspace/layout"
|
|||
|
|
|
|||
|
|
export function Application() {
|
|||
|
|
return (
|
|||
|
|
<AppLayout
|
|||
|
|
header={AppHeader}
|
|||
|
|
rail={ActivityRail}
|
|||
|
|
sidebar={<NavigationSidebar groups={navigationGroups} />}
|
|||
|
|
aside={AssistantPanel}
|
|||
|
|
footer={StatusBar}
|
|||
|
|
defaultLayout={{
|
|||
|
|
asideOpen: true,
|
|||
|
|
footerStart: "sidebar",
|
|||
|
|
headerStart: "sidebar",
|
|||
|
|
}}
|
|||
|
|
>
|
|||
|
|
<RouterOutlet />
|
|||
|
|
</AppLayout>
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## LayoutConfig
|
|||
|
|
|
|||
|
|
`LayoutConfig` 是扁平、可序列化的完整快照；`layout` 和 `defaultLayout` 接收 `Partial<LayoutConfig>`。
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
interface LayoutConfig {
|
|||
|
|
asideEnabled: boolean
|
|||
|
|
asideOpen: boolean
|
|||
|
|
footerStart: "sidebar" | "content"
|
|||
|
|
headerStart: "rail" | "sidebar" | "content"
|
|||
|
|
sidebarCollapsible: boolean
|
|||
|
|
sidebarOpen: boolean
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
默认值：
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
const defaultLayoutConfig = {
|
|||
|
|
asideEnabled: true,
|
|||
|
|
asideOpen: false,
|
|||
|
|
footerStart: "content",
|
|||
|
|
headerStart: "rail",
|
|||
|
|
sidebarCollapsible: true,
|
|||
|
|
sidebarOpen: true,
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 提供 `layout` 时采用受控模式，交互后通过 `onLayoutChange` 返回完整快照。
|
|||
|
|
- 未提供 `layout` 时采用非受控模式，以 `defaultLayout` 或默认配置初始化。
|
|||
|
|
- 区域暂时不可用只影响有效布局，不会覆盖配置中保存的用户偏好。
|
|||
|
|
|
|||
|
|
## useLayoutConfig
|
|||
|
|
|
|||
|
|
区域组件可以读取布局状态并触发布局更新：
|
|||
|
|
|
|||
|
|
```tsx
|
|||
|
|
import { useLayoutConfig } from "@workspace/layout"
|
|||
|
|
|
|||
|
|
export function AppHeader() {
|
|||
|
|
const {
|
|||
|
|
layout,
|
|||
|
|
setAsideOpen,
|
|||
|
|
setSidebarOpen,
|
|||
|
|
toggleAside,
|
|||
|
|
toggleSidebar,
|
|||
|
|
updateLayout,
|
|||
|
|
} = useLayoutConfig()
|
|||
|
|
|
|||
|
|
// Render application controls.
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Hook 必须在 `AppLayout` 子树内调用。`updateLayout` 接收局部配置或根据当前完整配置生成局部配置的函数。
|
|||
|
|
|
|||
|
|
## 自动内移
|
|||
|
|
|
|||
|
|
`headerStart` 和 `footerStart` 表示期望位置。布局会根据当前实际可见的区域计算有效位置，但不会改写原配置：
|
|||
|
|
|
|||
|
|
- `headerStart="rail"` 表示全局 Header；没有 Rail 时从第一个实际存在的区域开始。
|
|||
|
|
- 只有 Rail 与 Sidebar 同时可见时，`headerStart="sidebar"` 和 `footerStart="sidebar"` 才会生效。
|
|||
|
|
- 其他情况下，`"sidebar"` 自动内移为 `"content"`。
|
|||
|
|
- Aside 始终贯穿中心工作区高度，不参与 Footer 范围。
|
|||
|
|
|
|||
|
|
## 尺寸
|
|||
|
|
|
|||
|
|
可以通过 CSS 自定义属性调整三个辅助列：
|
|||
|
|
|
|||
|
|
```css
|
|||
|
|
.application-layout {
|
|||
|
|
--layout-rail-width: 4rem;
|
|||
|
|
--layout-sidebar-width: 18rem;
|
|||
|
|
--layout-aside-width: 22rem;
|
|||
|
|
}
|
|||
|
|
```
|