Gauge

React 血条组件：读数显示在斜切的槽中，数值下降时留下一段残影，每次受击的伤害量一目了然。

安装

terminal

# once per project: where @zzzui items come frompnpm dlx shadcn@latest registry add @zzzui=https://zzzui.catforest.dev/r/{name}.jsonpnpm dlx shadcn@latest add @zzzui/gauge

示例

受击与修复

Hull

gauge-hit.tsx

import { useState } from "react";import { Button } from "@/components/zero/button";import { Gauge, GaugeLabel, GaugeValue } from "@/components/zero/gauge";export default function GaugeHit() {  const [hull, setHull] = useState(84);  return (    <div className="grid w-full max-w-md gap-5">      <Gauge value={hull} max={120} low={0.25}>        <GaugeLabel>Hull</GaugeLabel>        <GaugeValue />      </Gauge>      <div className="flex flex-wrap gap-3">        <Button          variant="danger"          size="sm"          onClick={() => setHull((h) => Math.max(0, h - 26))}        >          Take a hit        </Button>        <Button          variant="secondary"          size="sm"          onClick={() => setHull((h) => Math.min(120, h + 30))}        >          Patch up        </Button>      </div>    </div>  );}

分格与色调

Shield

Fuel

Signal

gauge-kinds.tsx

import { Gauge, GaugeLabel, GaugeValue } from "@/components/zero/gauge";export default function GaugeKinds() {  return (    <div className="grid w-full max-w-md gap-6">      <Gauge value={68} segments={5} tone="rare">        <GaugeLabel>Shield</GaugeLabel>        <GaugeValue />      </Gauge>      <Gauge value={41} max={60} tone="legendary">        <GaugeLabel>Fuel</GaugeLabel>        <GaugeValue>{(_, value) => `${value} L`}</GaugeValue>      </Gauge>      <Gauge value={7} max={10} segments={10} tone="epic">        <GaugeLabel>Signal</GaugeLabel>        <GaugeValue />      </Gauge>    </div>  );}

行为

数值下降时，填充条立即缩短，原位置留下一段浅色残影，停留片刻（--zero-dur-hold）后再收缩到新值。数值上升时，先有一段淡色的条延伸至新值，填充条随后增长到该位置。降到 low（占总量的比例）及以下时，填充条变红并呼吸闪烁。开启「减少动态效果」时，残影不再停留，填充条也不再呼吸闪烁。

segments 将槽分成若干斜切的格子，依次填满，适合表示护盾或充能次数。tone 决定填充条的颜色：强调色、危险色、某一稀有度的颜色，或中性的灰色；多个读数并列时，中性灰用于无需突出的那些。组件基于 Base UI 的 Meter：读屏软件会读出数值及其范围，名称取自 GaugeLabel。

属性

Gauge

属性	类型	默认值	说明
value	number	—	读数。
min / max	number	0 / 100	取值范围。
tone	"accent" \| "quiet" \| "danger" \| "uncommon" \| "rare" \| "epic" \| "legendary"	"accent"	填充条颜色。
segments	number	—	槽的分格数。
low	number	—	占总量的比例（0–1）；降到此值及以下时，填充条变红并呼吸闪烁。

另可传入 Base UI Meter.Root 的全部属性。

GaugeValue

属性	类型	默认值	说明
children	(formatted, value) => ReactNode	"value / max"	自定义读数的显示方式。

另可传入 Base UI Meter.Value 的全部属性。