横幅提示 Banner — Astryx v0.7.1 文档

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

横幅提示 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
横幅提示 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
横幅提示 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
横幅提示 · 浮动 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
横幅提示 · 样式变化 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
横幅提示 · 状态 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
横幅提示 · 交互示例 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

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

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

{
  "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.

横幅提示

横幅提示 · Banner