徽章 · Badge

徽章用于反馈与状态场景。下面的官方示例展示原生用法与状态，属性名保持上游 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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

Badge

Badge highlights a status or category at a glance. Use it sparingly: only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.

属性	类型	默认值	说明
variant	'neutral' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'blue' \| 'cyan' \| 'green' \| 'orange' \| 'pink' \| 'purple' \| 'red' \| 'teal' \| 'yellow'	'neutral'	视觉样式变体。语义变体使用实色背景，非语义颜色变体使用浅色背景配彩色文字。
label	ReactNode		徽章文本内容。
icon	ReactNode		可选的前置图标。

使用建议

Every status badge steals attention. Only badge states where the user needs to notice or act: errors, warnings, items requiring follow-up. If no action is needed, plain text is fine.
Use success, warning, and error variants only for system status that demands attention: "Failed", "Degraded", "Action Required". These have bold solid backgrounds designed to stand out.
Use color variants (blue, purple, teal, etc.) for category tags that group or classify items: team names, content types, priority levels.
Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge.
Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.
避免：Apply a "success" badge to every healthy/active/normal item. If all rows show green "Active" badges, none stand out; the badge adds noise, not information. Show only the states that need user attention (errors, warnings, pending actions).
避免：Use badges for metadata. Durations ("6h window"), counts ("12 trigger types"), dates, and descriptions are not statuses or categories; use description text (Text with type="supporting") instead.
避免：Use semantic status variants (success, warning, error, info) for categories or informational content. These are visually loud and should only indicate system state.
避免：Repeat the same badge in every row of a table or list. If the same value appears in most rows, it's not adding information; use plain text for common states and reserve badges for the exceptional ones.
避免：Make badges clickable; they are read-only indicators. Use a button or link if the user needs to take action.

主题 API

{
  "targets": [
    {
      "className": "astryx-badge",
      "visualProps": [
        "variant"
      ]
    }
  ]
}

组件结构

Icon: An optional leading icon that helps identify the badge type at a glance.
Label: The text or number shown inside the badge.