#图表

图表把数值关系转换成可比较的视觉结构。它适合趋势、差异和组成关系，不适合替代精确数据表或用装饰图形填充空白。

npm install @a3s-lab/ui chart.js

<figure aria-labelledby="visitors-title">
  <figcaption id="visitors-title">
    <strong>按设备划分的月访问量</strong>
    <span id="visitors-summary">桌面端和移动端访问量都在 2 月达到峰值。</span>
  </figcaption>
  <div class="chart">
    <canvas id="visitors-chart" aria-describedby="visitors-summary">
      当前环境无法显示图表，请查看下方数据表。
    </canvas>
  </div>
  <table class="sr-only">
    <caption>按设备划分的月访问量</caption>
    <thead><tr><th scope="col">月份</th><th scope="col">桌面端</th><th scope="col">移动端</th></tr></thead>
    <tbody>
      <tr><th scope="row">1 月</th><td>186</td><td>80</td></tr>
      <tr><th scope="row">2 月</th><td>305</td><td>200</td></tr>
      <tr><th scope="row">3 月</th><td>237</td><td>120</td></tr>
    </tbody>
  </table>
</figure>

import "@a3s-lab/ui/a3s.css";

#用法

导入图表结构和 A3S 视觉令牌；Chart.js 仍是显式的宿主依赖。

@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/chart.css";
@import "@a3s-lab/ui/styles/a3s.css";

a3sUI.chart() 接收原生 canvas，使用 A3S 令牌配置坐标轴、工具提示和可选图例。通过 Chart 参数显式传入 Chart.js，避免依赖隐式全局变量。

import ChartJS from "chart.js/auto";
import "@a3s-lab/ui/runtime";
import "@a3s-lab/ui/chart";

const rows = [
  { month: "1 月", desktop: 186, mobile: 80 },
  { month: "2 月", desktop: 305, mobile: 200 },
  { month: "3 月", desktop: 237, mobile: 120 },
];

const chart = window.a3sUI.chart("#visitors-chart", {
  Chart: ChartJS,
  type: "bar",
  labelKey: "month",
  data: rows,
  series: {
    desktop: { label: "桌面端", color: "var(--chart-1)" },
    mobile: { label: "移动端", color: "var(--chart-2)" },
  },
  legend: true,
});

画布必须与标题、简短结论和等价数据放在同一个 figure 中。视觉图表不是数据的唯一表达。

<figure aria-labelledby="visitors-title">
  <figcaption id="visitors-title">
    <strong>按设备划分的月访问量</strong>
    <span id="visitors-summary">桌面端和移动端访问量都在 2 月达到峰值。</span>
  </figcaption>
  <div class="chart">
    <canvas id="visitors-chart" aria-describedby="visitors-summary">
      当前环境无法显示图表，请查看下方数据表。
    </canvas>
  </div>
  <table class="sr-only">
    <caption>按设备划分的月访问量</caption>
    <thead><tr><th scope="col">月份</th><th scope="col">桌面端</th><th scope="col">移动端</th></tr></thead>
    <tbody>
      <tr><th scope="row">1 月</th><td>186</td><td>80</td></tr>
      <tr><th scope="row">2 月</th><td>305</td><td>200</td></tr>
      <tr><th scope="row">3 月</th><td>237</td><td>120</td></tr>
    </tbody>
  </table>
</figure>

辅助 API 会复用已有 .chart 容器；若画布没有容器，它会生成一个。主题或样式包变化时会从 CSS 令牌重新解析颜色。

#参数

series 中的 label 必须是面向用户的本地化名称。color 使用 --chart-1 到 --chart-5 等稳定令牌；surface 可为 true、"gradient" 或 { from, to }；dataset 只放当前系列的原生 Chart.js 配置。

#状态与变体

#选择正确图形

• 条形图比较离散类别，基线通常从零开始。
• 折线图表达有顺序的时间趋势，不应用平滑曲线暗示不存在的数据。
• 堆叠图只在用户需要比较整体组成时使用；类别过多时改用表格。
• 环形图只适合少量、总和明确为整体的类别，并同时显示数值。
• 雷达图很难精确比较，只适合少量同尺度维度的概览，不用于关键决策。

<div class="grid gap-8">
  <div><h3 class="mb-3 text-sm font-semibold">连续趋势</h3><ChartDemo variant="line" /></div>
  <div><h3 class="mb-3 text-sm font-semibold">整体组成</h3><ChartDemo variant="donut" /></div>
</div>

#加载、空白与错误

数据未就绪时保留图表测量框，并在 data-chart-state 中说明当前状态。空白状态解释为什么没有数据；错误状态提供恢复方式。不要用一张零值图表伪装空数据。

<div class="grid w-full gap-4 lg:grid-cols-3">
  <div class="chart" data-state="loading" aria-busy="true">
    <canvas aria-hidden="true"></canvas>
    <div data-chart-state role="status">
      <strong>正在加载访问量</strong>
      <span>保留图表尺寸，避免内容完成后跳动。</span>
    </div>
  </div>
  <div class="chart" data-state="empty">
    <canvas aria-hidden="true"></canvas>
    <div data-chart-state>
      <strong>没有可比较的数据</strong>
      <span>选择至少两个时间点，或扩大日期范围。</span>
    </div>
  </div>
  <div class="chart" data-state="error">
    <canvas aria-hidden="true"></canvas>
    <div data-chart-state role="alert">
      <strong>访问量加载失败</strong>
      <span>检查数据连接后重试，当前筛选仍会保留。</span>
      <footer><button type="button" class="btn" data-size="sm" data-variant="outline">重新加载</button></footer>
    </div>
  </div>
</div>

loading、empty 和 error 由宿主数据生命周期驱动。更新数据时优先调用 Chart.js 实例的更新 API，避免销毁后造成焦点、尺寸和动画上下文跳变。交互式图例属于筛选控件，应使用真实按钮并同步 aria-pressed；默认生成的图例只用于识别系列。

#可访问性

图表必须有可见标题、简短结论和等价数据表；canvas 的 aria-label 只能概括主要发现，不能替代全部数值。系列同时使用标签、形状或位置区分，不能只依赖颜色。工具提示信息应可从表格获得，默认只读图例不进入 Tab 顺序；交互式图例必须改为真实按钮。缩放到 200%、暗色主题、RTL 和窄屏时仍要保留标签与数据理解路径。动画遵循减弱动态效果偏好，实时数据更新不应高频播报。宿主负责数据真实性、格式化、单位、时区、空白与错误状态；组件只负责视觉映射和主题集成。