kaze風
ChartLegend
チャート共通の凡例。onToggle を渡すと系列の表示 / 非表示を切り替えるボタンになる。LineChart / ColumnChart の内部でも使用。
プレビュー
使いどころ
使う場面
- 複数系列のグラフで、色と系列名の対応を示す。色だけでは系列が判別できないので、凡例は省略しない
- onToggle を渡すと、各項目が切り替えボタンになり、利用者が系列を隠せる。hidden に隠れているキーを渡して状態を持つ
- LineChart と ColumnChart は自前で ChartLegend を持つ。自作のグラフや、複数のグラフで凡例を共有するときに、単体で使う
使わない場面
- 系列が 1 本のとき。グラフのタイトルで足りる
- DonutChart と CategoryBar。すでに値付きの凡例を内蔵している
- 系列を隠す機能を持たないグラフで、onToggle を渡すこと。押しても何も起きないボタンになる
使い方
const [hidden, setHidden] = useState<string[]>([]);
<ChartLegend
items={[
{ key: "web", label: "Web", color: "var(--chart-1)" },
{ key: "ios", label: "iOS", color: "var(--chart-2)" },
]}
hidden={hidden}
onToggle={(key) =>
setHidden((prev) => (prev.includes(key) ? prev.filter((k) => k !== key) : [...prev, key]))
}
/>プロパティ
| 名前 | 型 | デフォルト | 説明 |
|---|---|---|---|
items必須 | ChartLegendItem[] | なし | { key, label, color } の配列 |
hidden | readonly string[] | なし | 非表示中の系列 key（薄く表示） |
onToggle | (key: string) => void | なし | 指定すると各項目が aria-pressed 付きのトグルボタンになる |
型と必須かどうかはソースの型定義から自動で生成しています。表にない HTML 標準の属性（className や aria-* など）も、ルート要素にそのまま渡せます。
キーボード操作
| キー | 動作 |
|---|---|
| Tab | 凡例の項目（onToggle があるとき）にフォーカスを移す |
| Enter / Space | 系列の表示と非表示を切り替える |
アクセシビリティ
- onToggle があるときは <button> で、aria-pressed が系列の表示状態を伝える。押された状態が「表示中」。onToggle がなければ、ただの文字（span）になり、操作できない
- 色見本（swatch）は aria-hidden で、系列名の文字が読み上げられる。系列名は色の説明ではなく、データの名前にする
- 隠れた項目は薄く表示される。薄さは見た目だけの手がかりで、状態は aria-pressed で伝わる。hidden に渡したキーの系列は、グラフ側でも実際に描画から外す
文言
- label はグラフの系列名と一致させる（「売上」「利益」）。tooltip や軸の表記と揃える