---
title: "SignalMeter 信号量表"
description: "分段强度条，用几格表达置信度、相关度或信号强弱"
category: Visualization
status: beta
since: 0.3.9
tags: [ai, confidence, meter]
syncStatus: reviewed
verified: true
---

## 用法

### 四档强度

点亮格数由 `value` 决定，未点亮的格固定用发丝线色，不受 `tone` 影响。

:::TuffDemoWrapper{demo="SignalMeterLevelsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSignalMeter :value="3" tone="var(--tx-bui-green)" label="高置信" />
    <TxSignalMeter :value="2" tone="var(--tx-bui-orange)" label="需要复核" />
    <TxSignalMeter :value="1" tone="var(--tx-bui-red)" label="证据薄弱" />
    <TxSignalMeter :value="0" tone="var(--tx-bui-ink-3)" label="无信号" />
  </template>
---
:::

### 最佳实践

- 颜色永远不是状态的唯一载体：量表旁边要有文字标签（`高置信` / `需要复核`），并把同一段文字传给 `label`。
- 同屏内保持相同 `max`，否则「三格里的两格」和「五格里的两格」会被读成同一强度。
- 父级已有可见标签时，量表本身不传 `label`，让读屏只念一次。
- 在宿主侧把 `confidence` 这类语义值映射成 `value` + `tone`，不要在模板里散落魔数。

## API 参考

### Props

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `value` | `number` | — | 点亮的格数。必填；超出 `[0, max]` 会被夹紧，小数向零取整。 |
| `max` | `number` | `3` | 总格数。 |
| `tone` | `string` | `'currentColor'` | 点亮格的颜色，任意 CSS 颜色值。默认继承父级文字色。 |
| `label` | `string` | — | 无障碍名称。不传时整条被标记 `aria-hidden`。 |
| `barHeight` | `number` | `10` | 单格高度（px）。 |
| `barWidth` | `number` | `4` | 单格宽度（px）。 |

### Events

组件没有交互，不派发任何事件。

### Slots

组件没有插槽。

## 概述

- 纯展示原语：没有事件、没有内部状态，`value` 变化即重绘。
- **`label` 决定无障碍语义。** 传了就渲染 `role="img"` + `aria-label`；不传就整条 `aria-hidden="true"`。后者是刻意的——三个空 `span` 被逐个念出来只是噪音，而这条量表在实际版式里总是紧挨一段可见文字。
- `value` 越界不会报错也不会溢出，一律夹紧到 `[0, max]`。
- `tone` 收的是裸 CSS 颜色字符串，**不参与主题切换**。想跟随主题就传 `var(--tx-color-success)` 这类变量，而不是十六进制值。
- 填充色过渡 300ms；`prefers-reduced-motion: reduce` 下取消过渡，保留最终颜色。

## 技术实现

- 组件源码与类型：`packages/tuffex/packages/components/src/signal-meter/src/TxSignalMeter.vue`、`types.ts`。
- 移植自 Beautiful UI（https://www.beautifului.dev），© 2026 Shane Levine，MIT。

<TuffDocSourceLink />
## 使用场景

- 建议卡的置信度页脚与备选列表——`TxRecommendationCard` 内部就用它。
- 检索结果的相关度：三格比一个百分比更容易横向扫读。
- 任何「强 / 中 / 弱 / 无」的离散量。连续量请用 `TxProgressBar`。
- 与 `TxStatusBadge` 的分工：后者是带框的五档语义徽标，本组件是没有边框与图标的裸格子，接受任意颜色；两者不要互相替代。
