---
title: "IconChip 图标角标"
description: "承载格式标记、首字母或小图标的色块"
category: Basic
status: beta
since: 0.3.9
tags: [icon, badge, chip, avatar]
syncStatus: reviewed
verified: true
---

## 用法

### 尺寸与色调
:::TuffDemoWrapper{demo="IconChipIconChipDemo" code-lang="vue" description="14 / 18 / 32px 三档、宽标签与圆形"}
---
code: |
  <template>
    <TxIconChip :size="14" tone="red" label="PDF" />
    <TxIconChip :size="14" tone="ink" label="JSON" />
    <TxIconChip :size="18" tone="accent" variant="soft">
      <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
        <path d="M12 2l2.4 7.2L22 12l-7.6 2.8L12 22l-2.4-7.2L2 12l7.6-2.8z" />
      </svg>
    </TxIconChip>
    <TxIconChip :size="32" tone="ink" :font-size="13" label="C" />
    <TxIconChip :size="14" tone="green" shape="circle" />
  </template>
---
:::

### 最佳实践

- 文件类型角标固定 14px，用 `tone` 区分格式（PDF 红、CSV 绿），全站保持一致。
- 四个字母以上的格式（`JSON`、`YAML`）照常传 `label`，角标会变宽；不要调小 `fontSize` 硬塞进方块。
- 首字母方块用 32px 与 `tone="ink"`，它随深浅主题反色，不要写死颜色。
- 状态点用 `TxDotIndicator`，不要把 `TxIconChip` 缩到 6px 充当圆点。
- 没有设计依据时不要覆盖 `radius`，推导出的阶梯就是这套视觉语言。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `size` | `number` | `14` | 边长（px）：14 文件角标、18 图标片、32 首字母方块。 |
| `radius` | `number \| string` | - | 圆角，数字按 px 计；缺省由 `size` 推导，圆形时忽略。 |
| `tone` | `'neutral' \| 'ink' \| 'accent' \| 'green' \| 'orange' \| 'red'` | `'neutral'` | 配色。 |
| `variant` | `'solid' \| 'soft'` | `'solid'` | `solid` 整块填充；`soft` 用同色浅底加 30% 发丝环。 |
| `shape` | `'square' \| 'circle'` | `'square'` | 形状。 |
| `label` | `string` | - | 短文本，如 `PDF`；超过三个字符时角标变宽，默认插槽优先。 |
| `fontSize` | `number` | - | 覆盖推导出的字号。 |
| `ariaLabel` | `string` | - | 设置后为 `role="img"` 并使用该名称；否则 `aria-hidden`。 |

### 插槽

| 名称 | 说明 |
|------|------|
| `default` | 角标内容，通常是内联 SVG 或短文本；覆盖 `label`。 |

## 概述

- 圆角缺省为 `round(size / 4)`（14→4、18→5、32→8），字号缺省为 `max(7, round(size * 0.4))`（14→7、32→13）；显式传入即覆盖。
- 宽度默认等于 `size`；`label` 超过三个字符时随文字增长，最小为 `size`，左右各留 `size × 0.2` 内边距，高度、圆角与字号不变；默认插槽内容不参与。
- 默认 `aria-hidden="true"`：角标几乎总与相邻文本重复（`report.pdf` 旁的 `PDF`）；只有角标是唯一信息载体时才传 `ariaLabel`。
- `soft` 的发丝环是 `box-shadow` 而非 `border`，不占布局，高度始终等于 `size`（长标签只放宽宽度）。
- `neutral` 在两种 `variant` 下外观相同（`inset` 底加发丝环）。

## 技术实现

- 源码：`packages/tuffex/packages/components/src/icon-chip/`。
- 改编自 [Beautiful UI](https://www.beautifului.dev)，© 2026 Shane Levine，MIT 协议；`variant="soft"` 为新增。

<TuffDocSourceLink />
