用 Claude Code 选择图表库：Recharts、Chart.js 与 D3

先控制产品风险

用 Claude Code 选择图表库时，关键不是把界面做得多炫，而是在不破坏转化、阅读体验、移动端和可访问性的前提下，让界面更可靠。初学者很容易让 Claude Code 一次生成大量代码，觉得”能跑起来”就算完成，但真正上线时，空数据、加载状态、键盘焦点、屏幕宽度、颜色对比和主要按钮的位置才更重要。本文要讲的是：如何把图表小步、安全地引入项目，并把它培养成日后不易出错的形态。

建议同时阅读 claude code dashboard development, claude code data visualization, claude code accessibility。官方资料可以参考 Claude Code docs, Recharts, Chart.js, D3, WCAG 2.2。给 Claude Code 的指令要写清楚目标、禁止改动的范围、需要检查的 use case 和 pitfall。

推荐提示词

请用最小安全改动实现这个功能。
保留现有组件结构、设计 token 和路由。
请覆盖 use case、pitfall、可访问性、移动端、失败状态和回滚方法。
返回可直接复制运行的代码，并附上 review checklist。

这段提示词的用意，是让 Claude Code 产出的不是”完成版 UI”，而是”不易出错的改动流程”。在已有站点上尤其如此：比起华丽的改版，更重要的是不增加跳出、不挡住咨询和购买入口。

适用场景清单

1. 落地页和文章页：让读者更容易看到下一步，但不能遮挡正文、广告或咨询按钮。
2. SaaS 仪表板：加载、空数据、错误和成功状态要清楚。
3. 购买、注册、咨询流程：视觉优化不能抢走主要行动按钮。
4. 团队协作：Claude Code 需要输出代码、理由和检查清单，方便他人复核。

实现代码

npm i recharts chart.js react-chartjs-2 d3
npm i -D @types/d3

"use client";

import {
  CartesianGrid,
  Line,
  LineChart,
  ResponsiveContainer,
  Tooltip,
  XAxis,
  YAxis,
} from "recharts";

type Point = {
  date: string;
  revenue: number | null;
  orders: number;
};

const money = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 0,
});

function normalize(points: Point[]) {
  return points
    .filter((point) => Number.isFinite(Date.parse(point.date)))
    .sort((a, b) => Date.parse(a.date) - Date.parse(b.date))
    .map((point) => ({
      ...point,
      label: new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric" }).format(
        new Date(point.date),
      ),
      revenue: point.revenue ?? 0,
      orders: Number.isFinite(point.orders) ? point.orders : 0,
    }));
}

export function RevenueChart({ data }: { data: Point[] }) {
  const rows = normalize(data);

  if (rows.length === 0) {
    return <p role="status">No chart data yet. Check the date range or filters.</p>;
  }

  return (
    <figure aria-labelledby="revenue-chart-title">
      <h2 id="revenue-chart-title">Revenue trend</h2>
      <ResponsiveContainer width="100%" height={320}>
        <LineChart data={rows} margin={{ top: 16, right: 24, bottom: 8, left: 8 }}>
          <CartesianGrid strokeDasharray="3 3" />
          <XAxis dataKey="label" />
          <YAxis tickFormatter={(value) => money.format(Number(value))} />
          <Tooltip formatter={(value) => money.format(Number(value))} />
          <Line type="monotone" dataKey="revenue" stroke="#2563eb" strokeWidth={3} dot={false} />
        </LineChart>
      </ResponsiveContainer>
      <figcaption>Data is sorted by date and null revenue is rendered as zero.</figcaption>
    </figure>
  );
}

如何在 Recharts、Chart.js 与 D3 之间选择

图表库如果只凭”流行”来选，后面往往会后悔。在实务中，应该根据你要展示的图表类型、团队的熟练度、设计自由度和打包体积，决定优先满足哪一项。把选型交给 Claude Code 时，也要把这三个候选一起给它，并让它说明”为什么选这个”，这样判断的依据日后才有据可查。

库	适合的场景	注意点
Recharts	在 React 中快速画出 KPI 卡片、营收趋势等常规图表	不擅长复杂的自定义表现，也不适合渲染数千个数据点
Chart.js	在非 React 页面也能用，基于 Canvas 渲染、轻快	不是 DOM 元素，可访问性需要另行补足
D3	细致打磨独特的数据可视化	学习成本高，实现量和 review 量都会增加

第一步的判断其实很简单：如果只是在 React 仪表板里画折线、柱状、饼图这类常规图表，用 Recharts 就够了。非 React 的页面，或者数据点多达数千的重图表，Chart.js 的 Canvas 渲染会更稳。只有当你需要带动效的独特表现、或报告级别的精致图形时，才考虑 D3。拿不定主意时，先用 Recharts 做出能跑的版本，等表现力不够了再迁移，返工成本会小很多。

Masa 在做一个小仪表板时，也是一上来就动用 D3，结果实现越写越大，review 跟不上。把”常规图表用 Recharts、只有特殊那一张用 D3”的职责划分清楚后，整体维护反而轻松很多。给 Claude Code 下指令时，明确写出”这张图用 Recharts，只有这里用 D3”，就能避免它给你塞进不必要的高功能库。

一定要准备空数据、加载中、错误三种状态

图表里事故最多的，就是”数据还没来”时的显示。如果不去考虑 API 返回了空数组、统计结果为 0 条、获取失败这几种状态就直接开写，读者就可能看到只剩坐标轴的图、一片空白的区域，最糟的是整页崩溃。上面的实现示例在 rows.length === 0 时返回一句提示，正是为了避免这类事故。

实务中至少要准备以下 4 种状态。加载中时，放一个与图表等高的占位，避免布局跳动；空数据时，写明”暂无数据”的原因或下一步操作；错误时，给出原因和重试按钮；只有在正常状态下，才绘制图表本体。

状态	显示	常见失败
加载中	等高的骨架屏	只放转圈、高度变化，画面跳动
空数据	原因与下一步操作	只显示一张光秃秃的坐标轴
错误	原因与重试	异常把整页一起带崩
正常	图表本体	不区分 0 条与正常

给 Claude Code 下指令时，开头就要说清”不只要正常情况，也要给出空数据、加载中、错误的显示”。不这么说，AI 往往只实现成功路径，一遇到真实数据必然卡住。图表越是视觉抢眼，出问题时留给人的印象也越深，所以把这些状态做扎实，是值得的投入。

陷阱清单

• 只看截图不看真实流程，容易让转化路径变差。
• 只依赖颜色或动效表达含义，会影响可访问性。
• 未检查 375px 宽度时，移动端可能出现横向滚动。
• 未处理空数据、长文本、慢网络和刷新，会在真实用户环境出错。
• 让 Claude Code 顺手重构无关文件，会让 review 成本变高。

验证方法

让 Claude Code 再做一次只读 review，要求列出改动文件、风险、手动检查项和浏览器检查项。然后在移动端宽度打开页面，确认没有横向溢出，代码块可以滚动，CTA 仍然可见，辅助文本和焦点样式没有消失。

商业化视角

图表展示不是装饰，而是减少读者走向咨询、资料索取、购买、报名培训路上犹豫的改进。想在自家站点搭好 Claude Code 的引入和 review 流程的团队，可以通过 Claude Code 培训与咨询，以现有界面为题材讨论改进步骤。

额外检查

• 把修改前后的截图并排对比，确认 CTA、广告、正文、表单和代码块依旧清晰易读。
• 不要直接照搬 Claude Code 的建议，反过来追问它哪些代码可以删、哪些命名别扭、哪些地方和既有 CSS 冲突。
• 上线前把移动端、桌面端、键盘操作、慢网络、空数据和刷新行为都过一遍。

实测记录

这套步骤是在不破坏既有博客 UI 的前提下，一边盯着 375px 手机宽度、常规显示、慢网络和键盘操作一边验证的。我没有把所有事情一次性丢给 Claude Code，而是拆成实现、review、修正三步——这样差分更好读，质量也更稳。比起一次性大改，更容易发现问题，也更适合每天持续打磨内容站和产品页。