---
title: "AllocationBar 占比条"
description: "按份额分段的胶囊条 + 图例胶囊，选中哪段就检查哪段"
category: Visualization
status: beta
since: 0.3.9
tags: [data, allocation, segment, chart]
syncStatus: reviewed
verified: true
---

## 用法

### AllocationBar

:::TuffDemoWrapper{demo="AllocationBarAllocationBarDemo" code-lang="vue" title="库存占比" description="分段条 + 图例 + 明细面板，选中项由宿主持有。"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const selected = ref('van')
  const segments = [
    { key: 'van', label: '香草', short: 'VAN', percent: 72.5, amount: '$51,785', description: '当前库存价值的贡献快照。' },
    { key: 'choc', label: '巧克力', short: 'CHOC', percent: 22.8, amount: '$16,278' },
    { key: 'mint', label: '薄荷', short: 'MINT', percent: 4.7, amount: '$3,357' },
  ]
  </script>

  <template>
    <TxAllocationBar v-model="selected" :segments="segments" detail />
  </template>
---
:::

### 最佳实践

- 分段数控制在 3–5 个，尾部合并成「其他」；默认阶梯只有四档（强调色 + 三层墨色），第 5 段起请显式给 `color`。宽度小于 ~2% 的段点不中，也读不出来。
- 默认阶梯已经把主份额涂成强调色、其余留作逐级淡出的墨色；只有分段有真实类目色时才传 `color`——全部上色会让「谁是重点」这件事消失。
- 颜色不是唯一载体：图例里始终带短码与百分比，明细面板带完整名称。
- 需要主数字（如 `$51,785`）时由宿主渲染，跟随 `modelValue` 从 `segments` 里取——这样卡片高度不随选中变化。
- 进度条表达单一进度，这里表达构成；两者视觉相近但语义不同，不要互相替代。

## API 参考

### Props

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `segments` | `AllocationSegment[]` | — | 分段数组，见下。 |
| `modelValue` | `string` | — | 选中段的 `key`。省略时高亮第一段。 |
| `legend` | `boolean` | `true` | 是否渲染下方图例胶囊。 |
| `detail` | `boolean` | `false` | 是否渲染明细面板（当前段的名称 + 描述）。 |
| `ariaLabel` | `string` | `'Allocation segments'` | 分段组的可访问名。 |
| `percentFormatter` | `(percent: number) => string` | — | 覆盖默认的 `${percent}%`。 |

`AllocationSegment` = `{ key, label, short?, percent, amount?, color?, description? }`。`short` 是图例里的短码（缺省用 `label`），`percent` 取 0–100。

### Events

| 事件名 | 回调参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(key: string)` | 选中另一段。 |
| `change` | `(segment: AllocationSegment)` | 同上，带整个分段对象。 |

## 选中即检查

分段条不是只读图表：点任意一段（或它的图例胶囊），或在条上拖过它，就把检查对象换成那一段，条子本身不动。这是它与进度条的根本区别——它表达的是「整体由哪些部分构成」，而不是「完成了多少」。

选中值完全受控。`modelValue` 不传时默认高亮第一段，但点击和拖动仍然只发事件、不自行改变——宿主要么绑 `v-model`，要么自己处理 `change`。

`amount` 留在数据里但**条子不渲染它**：它属于卡片顶部的主数字，由宿主排版（见示例）。

## 概述

- 分段与图例是**同一个单选组的两套控件**，共同持有同一个值：整组是 `role="radiogroup"` 并带 `aria-label`，每个分段与图例胶囊是 `role="radio"`、以 `aria-checked` 表达选中，`tabindex` 只在选中项上为 0；方向键在当前这套控件内移动焦点并同步选中（循环）。分段另带 `aria-label="{label}: {percent}"`。
- 在分段条上按住拖动会逐段选中指针下的分段：每越过一段发一次事件，间隙归较近的一段，拖出两端停在首尾段；焦点在组内时随之移动。松手保留最后的选中且不再触发点击，Escape 或指针被取消时退回拖动起点。触屏横向拖动选择，纵向滑动仍滚动页面；拖动期间关闭过渡，选中 1:1 跟手。
- 再次点击当前段不发事件——选中态没有「取消」语义。
- 未指定 `color` 的分段按位置落到「强调色 → 向轨道底色逐级淡出的墨色」阶梯：`--tx-bui-accent` → `--tx-bui-ink` → `--tx-bui-ink-2` → `--tx-bui-ink-3`，超过四段会重用到最后一档。这是上游「主份额着色、其余留灰」的表达方式；灰阶取 ink 系而不是 `--tx-bui-line*`，因为后两者与轨道底色 `--tx-bui-field` 只差 ΔRGB 5–18（约 1.03:1），两套主题下都读成空轨道。
- 分段宽度与 `percent` 严格成比例：轨道留出 2px 内边距与 2px 间隙，间隙预算按各段 `percent` 的比例预先从其宽度里扣除（`width: calc(percent% - 该段分摊的间隙)`），所以间隙只花固定像素、不会改写数据；总和略超 100% 时仍由 flex 等比收缩，不会裁切最后一段。
- 选中段的高光是**类驱动**而非动画驱动：减弱动效下过渡被关掉，高光仍然立刻出现，不会留空白。
- 缓动用的是 `cubic-bezier(0.16, 1, 0.3, 1)`（上游的 `--ease-link`），比这一族常用的 `--tx-ease-out-strong` 更「沉」，是刻意保留的差异。

## 技术实现

- 组件源码与类型：`packages/tuffex/packages/components/src/allocation-bar/src/`（`TxAllocationBar.vue`、`types.ts`）。
- 拖动选择复用 `packages/tuffex/packages/utils/press-scrub.ts`，与 MonoChart、DitherChart 共用。- 移植自 Beautiful UI（https://www.beautifului.dev），© 2026 Shane Levine，MIT。

<TuffDocSourceLink />