# 横幅提示 · Banner

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

横幅提示用于反馈与状态场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```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，不把示例状态名称当成组件属性。

## Banner

Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| status * | 'info' \| 'warning' \| 'error' \| 'success' |  | 状态类型，控制图标和颜色。 |
| title * | ReactNode |  | 显示在头部的标题文本或 ReactNode。 |
| description | ReactNode |  | 渲染在头部标题下方的描述文本。 |
| icon | ReactNode |  | 覆盖默认的状态图标。 |
| isDismissable | boolean | false | 横幅是否可被用户关闭。 |
| onDismiss | () => void |  | 点击关闭按钮时调用；无论是否提供此回调，横幅都会自动隐藏。 |
| dismissLabel | string |  | 关闭按钮的无障碍名称和可见工具提示（请传入已翻译的字符串）。字符串标题默认生成“关闭 <标题>”；富文本标题请设置此属性。 |
| endContent | ReactNode |  | 渲染在头部区域末端对齐的操作内容，通常是按钮或链接。头部过窄时会整体换行到文本下方，自成一行。 |
| container | 'card' \| 'section' | 'card' | 视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。 |
| elevation | 'none' \| 'low' \| 'med' \| 'high' | 'none' | 静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。 |
| children | ReactNode |  | 渲染在彩色头部下方卡片背景区域的内容。默认位于展开/折叠开关之后，除非设置 collapsible={false}。 |
| collapsible | boolean \| {defaultIsOpen?: boolean; isOpen?: boolean; onOpenChange?: (isOpen: boolean) => void} | true | 内容区域（children）是否位于头部的展开/折叠开关之后。默认开启，且初始为折叠状态。false 表示关闭：内容始终可见且没有开关。{defaultIsOpen: true} 表示初始展开；{isOpen, onOpenChange} 为受控模式。与 Collapsible 使用同一套 CollapsibleConfig。 |
| xstyle | StyleXStyles |  | 用于布局自定义的 StyleX 样式（外边距、定位、尺寸）。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。 |

### 使用建议

- Pick a status that matches the message: info for updates, warning for caution, error for problems, success for confirmations.
- Use the card container inside page content and the section container for full-width messages that span the entire page.
- Make info and success banners dismissable. Keep error banners visible until the user fixes the issue.
- Keep titles short and scannable: "Payment failed" not "There was a problem processing your most recent payment."
- 避免：Use Banner for short-lived messages that disappear on their own; use Toast instead.
- 避免：Stack multiple banners with the same status; combine related messages into one banner.
- Banner 的 status 仅控制颜色和图标，不创建实时区域。异步结果应在实际的状态转换处理函数中调用 useAnnounce。仅当可见 Banner 需要作为持久语义镜像时显式添加 role="status"；只有真正紧急、需要打断当前朗读的内容才使用 role="alert"。
- 避免：不要只依赖 status 的颜色或图标传达含义；请在标题文本中明确说明状态，因为屏幕阅读器会忽略这个装饰性图标。

### Announce an async outcome from its transition handler

```tsx
import {useState} from 'react';
import {Banner} from '@astryxdesign/core/Banner';
import {Button} from '@astryxdesign/core/Button';
import {useAnnounce} from '@astryxdesign/core/hooks';

function SaveSettings() {
  const announce = useAnnounce();
  const [result, setResult] = useState<'success' | 'error' | null>(null);

  async function handleSave() {
    try {
      await saveSettings();
      setResult('success');
      announce('Settings saved');
    } catch {
      setResult('error');
      announce('Settings could not be saved');
    }
  }

  return (
    <>
      <Button label="Save settings" onClick={handleSave} />
      {result != null ? (
        <Banner
          status={result}
          title={result === 'success' ? 'Settings saved' : 'Save failed'}
        />
      ) : null}
    </>
  );
}
```

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-banner-frame",
      "visualProps": [
        "container",
        "elevation"
      ]
    },
    {
      "className": "astryx-banner",
      "visualProps": [
        "container",
        "status"
      ]
    },
    {
      "className": "astryx-banner-icon",
      "visualProps": [
        "status"
      ]
    },
    {
      "className": "astryx-banner-description"
    },
    {
      "className": "astryx-banner-content",
      "visualProps": [
        "container",
        "status"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_banner-radius",
      "description": "Border radius of the card container (header, content area and the elevated root silhouette)",
      "default": "var(--radius-container)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_banner-radius"
      ]
    }
  ]
}
```

### 组件结构

- **Banner frame**: Outer frame that groups the status surface and optional content surface. It carries whole-banner elevation and, for elevated card banners, the radius that shapes that silhouette.
- **Status surface**: The primary painted surface. It communicates status and contains the icon, title, description, actions, and controls.
- **Icon**: Automatically set based on the status (info, warning, error, success).
- **Title**: The main message. Always required.
- **Description**: Additional detail below the title.
- **Action button**: A button for the user to act on the message, like "Review" or "Retry".
- **Dismiss button**: Lets the user close the banner. Enabled by setting isDismissable.
- **Content surface**: Secondary surface for extra detail below the status surface, like a list of errors. Sits behind an expand/collapse toggle by default; set collapsible={false} to keep it visible.

---

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