# 徽章 · Badge

- 页面: https://jiguang132.com/zh/resources/astryx/docs/badge
- 资源: 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**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## 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

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

---

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