# 应用框架 · AppShell

- 页面: https://jiguang132.com/zh/resources/astryx/docs/app-shell
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

组合应用导航、内容区和响应式布局。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **应用框架 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **应用框架 · 交互示例 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **应用框架 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **应用框架 · 交互示例 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **应用框架 · 交互示例 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **应用框架 · 交互示例 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **应用框架 · 交互示例 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## App Shell

AppShell is the page shell for an application. It provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| children | ReactNode |  | 主内容区域，渲染在 <main> 元素内部。 |
| contentPadding | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 | 0 | 主内容区域的内边距。根据页面主要内容模式设置：4（16px）适用于表单/设置/文本页面，0 适用于仪表盘/地图/表格。可通过 Section 覆盖个别区域。 |
| topNav | ReactNode |  | 顶部导航插槽，通常为 TopNav。 |
| sideNav | ReactNode |  | 侧边导航插槽，通常为 SideNav。 |
| mobileNav | ReactNode |  | 移动端导航配置。接受 false（禁用）、配置对象（调整自动行为）或 ReactNode（完全自定义抽屉）。配置对象为 {hasToggle?, isOpen?, onOpenChange?, content?, breakpoint?: 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'none', defaultIsMobile?}；breakpoint 默认为 'md'，从最近 Theme 的 widthBreakpoints 解析，并在等于断点时切换到较宽布局；'none' 始终使用非移动端布局并忽略 defaultIsMobile。 |
| banner | ReactNode |  | 横幅插槽，用于全局公告，放置在 topNav 上方。 |
| height | 'fill' \| 'auto' | 'fill' | 高度行为：'fill' 使外壳填满视口（100dvh），各区域拥有独立的滚动容器；'auto' 使外壳随内容增长，导航使用 sticky 定位。 |
| variant | 'wash' \| 'surface' \| 'section' \| 'elevated' | 'elevated' | 导航背景样式，控制导航区域与内容之间的对比。'wash' 使用 wash 背景，'surface' 使用 surface 背景，'section' 在导航和内容之间添加分隔线，'elevated' 使用 wash 导航配合凸起的 surface 内容区域和圆角。 |
| xstyle | StyleXStyles |  | 用于布局自定义的 StyleX 样式（外边距、定位、尺寸）。必须是 stylex.create() 的值，不能是 style={{}} 形式的内联样式对象。 |

### 使用建议

- Choose the right height: use "fill" for dashboards with internal scrolling and "auto" for pages that grow with content.
- Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards.
- 避免：Nest one AppShell inside another; it's the outermost layout frame.
- 避免：Use for sub-page layouts; use Layout for content areas within AppShell.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-app-shell",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-app-shell-header",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-app-shell-sidenav",
      "visualProps": [
        "variant"
      ]
    }
  ]
}
```

### 组件结构

- **Page shell**: Outermost application frame that owns page-level navigation, responsive shell behavior, and the main content landmark.
- **Skip link**: First focusable element on the page. Visually hidden until focused, then moves focus to the main content area.
- **Banner**: The banner slot, for system-wide announcements. Renders above the top nav, inside the banner landmark.
- **Top navigation**: The topNav slot, typically TopNav. Below the mobile breakpoint it becomes a compact bar carrying the nav toggle.
- **Side navigation**: The sideNav slot, typically SideNav. Inline above the breakpoint, moved into the mobile drawer below it.
- **Main content**: children, rendered in the main landmark. Scrolls internally when height is fill, and with the page when it is auto.
- **Mobile nav drawer**: Generated below the breakpoint from the nav slots unless mobileNav disables or replaces it. A modal dialog: it traps focus and returns focus to the toggle on close.

## useAppShellMobile

Hook for reading and controlling AppShell mobile navigation state from descendants of AppShell. Use it for custom mobile nav triggers, closing the drawer after route changes, or coordinating AppShell-adjacent mobile experiences with the same breakpoint used by mobile nav.

### Returns

```json
[
  {
    "name": "isMobile",
    "type": "boolean",
    "description": "Whether the current viewport is below the AppShell mobile navigation breakpoint. Use this to synchronize AppShell-adjacent mobile UI with the same breakpoint as mobile nav."
  },
  {
    "name": "isMobileNavOpen",
    "type": "boolean",
    "description": "Whether the AppShell-managed mobile navigation drawer is open."
  },
  {
    "name": "mobileNavId",
    "type": "string | undefined",
    "description": "DOM id of the mobile navigation drawer, set by AppShell. Point aria-controls of a custom toggle at this so screen-reader users know which element the toggle expands. Undefined outside an AppShell that manages the drawer."
  },
  {
    "name": "toggleMobileNav",
    "type": "() => void",
    "description": "Toggle the AppShell-managed mobile navigation drawer. No-ops when mobile nav is disabled."
  },
  {
    "name": "openMobileNav",
    "type": "() => void",
    "description": "Open the AppShell-managed mobile navigation drawer. No-ops when mobile nav is disabled."
  },
  {
    "name": "closeMobileNav",
    "type": "() => void",
    "description": "Close the AppShell-managed mobile navigation drawer."
  },
  {
    "name": "isMobileNavEnabled",
    "type": "boolean",
    "description": "Whether AppShell mobile navigation is enabled and managed by AppShell. False when mobileNav is false, there is no nav content, or a fully custom mobileNav ReactNode owns the drawer."
  },
  {
    "name": "hasAutoToggle",
    "type": "boolean",
    "description": "Whether AppShell auto-toggle behavior is enabled. False when mobileNav hasToggle is set to false; combine with isMobile and isMobileNavEnabled before rendering custom toggles."
  }
]
```

### 使用建议

- Use inside the AppShell tree when building custom mobile navigation controls, route-aware nav items, or UI that should update at the same breakpoint as AppShell mobile nav.
- Prefer MobileNavToggle for the standard hamburger trigger: use this hook when you need custom placement, styling, or extra behavior.
- Call closeMobileNav after a custom mobile nav item changes route so the drawer dismisses cleanly.
- 避免：Use as a general responsive primitive when the UI is not inside AppShell or does not need to align with AppShell mobile nav: use useMediaQuery instead.
- 避免：Assume it throws outside AppShell. The hook returns safe defaults and no-op callbacks when no provider is present.


## 完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

```bash
npm install @heroicons/react@2.2.0
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt