---
title: 概览
description: 使用可选区域和可持久化配置构建应用级布局。
order: 1
toc:
  - id: role
    title: 包的职责
  - id: regions
    title: 布局区域
  - id: config
    title: 配置与 Hook
---

## 包的职责 {#role}

`@workspace/layout` 提供路由无关的 `AppLayout`。它通过 CSS Grid 组合应用 Header、Navigation Rail、Sidebar、内容区、Aside 和 Footer，并根据实际可见区域自动计算有效网格。包不创建导航数据，不限制路由器，也不持久化用户偏好。

在应用全局样式中导入 Tailwind 源：

```css
@import "@workspace/layout/globals.css";
```

## 布局区域 {#regions}

```tsx
import { AppLayout } from "@workspace/layout"

export function Application() {
  return (
    <AppLayout
      header={AppHeader}
      rail={ActivityRail}
      sidebar={NavigationSidebar}
      aside={AssistantPanel}
      footer={StatusBar}
      defaultLayout={{ asideOpen: true }}
    >
      <RouterOutlet />
    </AppLayout>
  )
}
```

`children` 是唯一必需的内容区。Sidebar 可以折叠，Aside 适合 AI、文档和检查器等辅助功能。Header 可以从 Rail、Sidebar 或内容区开始；Footer 可以从 Sidebar 或内容区开始。缺少前置区域时，起始位置会自动向内容区内移。

## 配置与 Hook {#config}

`layout` 接收 `Partial<LayoutConfig>`。提供它时使用受控模式；否则 `AppLayout` 通过 `defaultLayout` 初始化内部状态。区域组件可以调用 `useLayoutConfig`：

```tsx
import { useLayoutConfig } from "@workspace/layout"

export function AppHeader() {
  const { layout, toggleAside, toggleSidebar } = useLayoutConfig()

  return (
    <nav>
      <button onClick={toggleSidebar}>Sidebar</button>
      <button onClick={toggleAside}>Assistant</button>
      <output>{layout.headerStart}</output>
    </nav>
  )
}
```

临时隐藏或禁用区域只影响当前有效布局，不会覆盖 `LayoutConfig` 中保存的原始偏好，因此配置可以安全接入 `@workspace/preferences`。