---
title: "DotIndicator 圆点指示器"
description: "圆点加文案的状态指示原语"
category: Data
status: beta
since: 0.3.9
tags: [status, dot, table, data]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
`color` 给圆点上色，`label` 或默认插槽提供文案。
:::TuffDemoWrapper{demo="DotIndicatorDotIndicatorDemo" code-lang="vue"}
---
code: |
  <template>
    <TxDotIndicator color="var(--tx-bui-green)" label="非常紧密" />
    <TxDotIndicator color="var(--tx-bui-orange)" label="一般" />
    <TxDotIndicator color="var(--tx-bui-red)" label="较弱" />
    <TxDotIndicator color="var(--tx-bui-ink-3)" label="无往来" />

    <TxDotIndicator color="var(--tx-bui-orange)">
      <strong>44% 平均强度</strong>
    </TxDotIndicator>
  </template>
---
:::

### 最佳实践

- 优先给 `label`：颜色不能是状态的唯一载体。
- 只有同一行已有文字说明含义时，才只给 `ariaLabel`。
- 颜色用 `--tx-bui-*` 或 `--tx-color-*` 变量；硬编码 hex 不随主题切换。
- 汇总行用默认插槽包一层 `<strong>` 强调数值，圆点保持对齐。
- 表格单元格、汇总行等高密度场景用圆点；独立的状态标记用 `TxStatusBadge`。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `color` | `string` | `'currentColor'` | 圆点颜色，接受任意 CSS 颜色或变量。 |
| `label` | `string` | - | 圆点旁的文案。 |
| `size` | `number` | `8` | 圆点直径（px）。 |
| `ariaLabel` | `string` | - | 没有可见文案时的可访问名称。 |

### 插槽

| 名称 | 说明 |
|------|------|
| `default` | 替换圆点旁的文案。 |

## 概述

- 有 `label` 或默认插槽时由文案说明含义，不加 role 或 `aria-label`。
- 只有 `ariaLabel` 时渲染为 `role="img"` 并带该名称。
- 两者都没有时视为装饰，设置 `aria-hidden="true"`。
- 文案使用等宽数字（`tabular-nums`），数值变化时不左右跳动。

## 技术实现

- 源码：`packages/tuffex/packages/components/src/dot-indicator/`。
- 移植自 [Beautiful UI](https://www.beautifului.dev)（© 2026 Shane Levine，MIT）；上游是纯视觉圆点，此处补上三种无障碍身份。

<TuffDocSourceLink />
