ゲージチャートGaugeChartExperimental

スコアや進捗、容量を示す半円ゲージです。

プレビュー

データ

状態とバリエーション

標準表示

スコアや進捗の現在値を半円で示す、SSOT 登録済みの標準バリエーションです。

コンパクト

狭いカードやサイドパネルで高さを抑える SSOT 登録済みバリエーションです。

容量レンジ

最大値を変更して、容量や上限付きの使用量を示す状態です。

最小値あり

最小値が 0 ではない範囲でも、現在値を正規化して表示できます。

警告色

負荷や注意が必要な状態を warning カラーで示します。

高リスク

高リスクや危険域に近い値を destructive カラーで示します。

プロパティ

表は横にスクロールできます
プロパティ型初期値説明
valuenumber-半円ゲージに表示する現在値です。
minnumber0正規化に使う最小値です。
maxnumber100正規化に使う最大値です。
variant"compact" | "default""default"チャートサイズを切り替える SSOT 登録済みバリエーションです。
colorChartColor-アクティブな円弧のトークンカラーです。未指定時は primary を使います。
labelReactNode-値の下に表示する補足ラベルです。
valueLabelReactNode-ゲージ内に表示する任意の表示値です。
formatValue(value: number) => ReactNode-ゲージとツールチップ範囲に表示する値を整形します。関数propのため Client Component からのみ渡すこと（Server Component から渡すと next build が落ちる）。RSC 安全な整形には valueFormat を使う。
valueFormat"number" | "compact" | "integer" | Intl.NumberFormatOptions-シリアライズ可能な数値フォーマット＝formatValue の RSC 安全な代替。formatValue 指定時は無視。en-US ロケール固定で整形。(#338)
rangeLabelReactNode"Range"ツールチップとアクセシビリティテキストで min/max 範囲の前に表示するラベルです。

使い方

import { GaugeChart } from "@gunjo/ui";

export function GaugeChartUsage() {
    return (
        <div className="grid gap-6">
            <GaugeChart
                value={82}
                label="スコア"
                valueLabel="82%"
                formatValue={(value) => value + "%"}
                rangeLabel="範囲"
            />
            <GaugeChart value={420} max={500} label="容量" />
            <GaugeChart value={64} variant="compact" color="success" />
            <GaugeChart
                value={260}
                max={500}
                color="warning"
                formatValue={(value) => value + "GB"}
            />
        </div>
    );
}

設計の判断

  • 範囲を、読み上げ名に必ず畳み込みます。ゲージは目盛りを描かないので、弧の長さだけでは「73 が何に対する 73 か」が分かりません。aria-label は「ラベル: 値（Range: 下端 - 上端）」の形で組み立てられ、min と max が必ず入ります。資料は role="meter" と aria-valuetext を薦めていますが、GUNJO は role="img" を選び、範囲を名前の中に入れる形にしました。rangeLabel の既定は英語の「Range」なので、日本語の画面では渡し直します。
  • 判定の語は、部品が持ちません。color に warning や destructive を渡しても、変わるのは弧の色だけです。「正常・注意・危険」は label か周りの文字で書いてください。値そのものは常に中央に文字で出るので（valueLabel で上書きできます）、数字が色だけになることはありません。
  • 範囲の外の値は、端で止めます。value は min と max に丸められるので、上限を超えた値も弧からはみ出しません。ただし丸めたことは図からは分からないので、超過そのものを見せたい画面では、max を超えた事実を文字で添えてください。表示だけの図でもフォーカスできるのは、範囲を出すツールチップをキーボードからも開けるようにするためです。数値の整形は formatValue のほかに、サーバーコンポーネントからも渡せる valueFormat を持っています（#338）。
    UIXHERO: ゲージチャート（Gauge Chart）

使用コンポーネント

ゲージチャートツールチップ

関連コンポーネント

セグメントゲージカード同心円進捗カードラジアルバーチャート統計