用 Claude Code 实现 D3.js 数据可视化

从真实页面出发

目标不是生成炫技代码，而是让真实页面在移动端、键盘操作、长文本、空数据和商业 CTA 下仍然稳定。要让 Claude Code 真正派上用场，提示词里必须写清边界：哪些文件可以改、哪些内容必须保持可见、哪里需要键盘支持，以及最终如何验证结果。

D3.js 的难点其实不在于怎么画一根柱子，而在于 scaleBand、axisLeft、selection.join、transition 这些部件到底在哪里衔接。理解清楚之前就照搬示例代码，往往会把图表改坏。把现有的 HTML、CSS、TypeScript 和数据结构喂给 Claude Code，再一起决定「这份数据放在哪个轴」「要不要做响应式」「无障碍怎么保证」，比直接丢一句「画个柱状图」要可靠得多。

延伸阅读：Claude Code 图表库、Claude Code 数据可视化、Claude Code 仪表板开发。官方参考：D3 getting started、D3 scales、D3 axes。

给 Claude Code 的提示词

请用最小安全改动实现这个功能。保留现有路由、样式规则和主要 CTA。返回可复制运行的代码、use case、pitfall、移动端检查和回滚方法。

适用场景清单

1. 内容站的搜索、图表、相关文章或 CTA 改善。
2. SaaS 管理画面的列表、看板、仪表板和表单。
3. 商品页、咨询页和广告页面的收入路径保护。
4. 团队 review 流程：让 Claude Code 把实现、风险和手动检查项一并返回。

实现示例

<figure>
  <svg id="revenue-chart" width="640" height="360" role="img" aria-labelledby="chart-title"></svg>
  <figcaption id="chart-title">Monthly revenue trend</figcaption>
</figure>

import * as d3 from "d3";

const data = [
  { month: "Jan", revenue: 12000 },
  { month: "Feb", revenue: 16400 },
  { month: "Mar", revenue: 15100 },
  { month: "Apr", revenue: 20100 },
];

const svg = d3.select("#revenue-chart");
const width = 640;
const height = 360;
const margin = { top: 24, right: 24, bottom: 44, left: 72 };

const x = d3
  .scaleBand()
  .domain(data.map((d) => d.month))
  .range([margin.left, width - margin.right])
  .padding(0.2);

const y = d3
  .scaleLinear()
  .domain([0, d3.max(data, (d) => d.revenue) ?? 0])
  .nice()
  .range([height - margin.bottom, margin.top]);

svg.append("g").attr("transform", `translate(0,${height - margin.bottom})`).call(d3.axisBottom(x));
svg.append("g").attr("transform", `translate(${margin.left},0)`).call(d3.axisLeft(y));

svg
  .append("g")
  .selectAll("rect")
  .data(data)
  .join("rect")
  .attr("x", (d) => x(d.month) ?? 0)
  .attr("y", (d) => y(d.revenue))
  .attr("width", x.bandwidth())
  .attr("height", (d) => y(0) - y(d.revenue))
  .attr("fill", "#2563eb");

先把整体拆给新手看

D3.js 的核心就是「把数据换算成像素，再用 SVG 元素画出来」。先把几个绕口的术语理清楚，给 Claude Code 的指令也会更具体。

部件	通俗解释	在本例中的角色
selection	选中 DOM 元素的操作	往 #chart 里追加一个 svg
scale（比例尺）	把数值或类别换算成屏幕上的位置	把渠道名换成横向位置，把转化数换成纵向位置
axis（轴）	刻度和标签	横轴显示渠道，纵轴显示转化数
mark（标记）	真正能看见的图形	用 rect 画柱子，用 path 画辅助线
join	让数据和 DOM 元素一一对应	数据条数变了也能更新柱子
transition	让变化平滑呈现	给柱子加上从下往上长出来的动画

给 Claude Code 的提示里，除了「用 D3 画柱状图」，最好把数据结构、显示单位、无障碍、更新时的行为、验证方法一并交代。例如这样请求：用 Vite + TypeScript + D3 v7 做一个按流量来源展示访问数和转化数的响应式柱状图，使用 selection.join，并包含 tooltip、键盘焦点、aria-label、空数据时的处理，以及能在浏览器控制台里跑的冒烟测试。

三个以上的实务场景

把 D3.js 只当成「画好看图表的工具」往往出不了成果。只有把咨询、购买、注册、持续使用这些与收益挂钩的行为可视化出来，仪表板才真正成为决策工具。

场景	适合用 D3.js 的理由	交给 Claude Code 的事情
内容导线的转化分析	流量来源、文章分类、CTA 点击能放在同一屏对比	先读 分析实现 的事件定义，再对齐图表指标
SaaS 使用情况仪表板	功能使用次数、留存率、各套餐差异都能细致表达	用 TypeScript 固定数据类型、空状态、加载状态和差异展示
错误监控与运维报表	时间序列、阈值、异常值高亮都能自由设计	配合 性能优化 检查大量数据点的渲染负担
A/B 测试结果可视化	置信区间和分段差异比纯表格更直观	把 A/B 测试实现 的汇总逻辑和图表展示分开

让 Claude Code 做 review 时，只说「找找有没有 bug」太弱了。把观察点列出来效果会好得多：请检查重绘时的重复元素、空数组、除以零、键盘操作、屏幕阅读器、移动端宽度，以及数据有 1000 条时的渲染负担。

陷阱清单

• 不要只为桌面端截图做优化。
• 不要让长文本、表格、SVG 或代码块产生横向溢出。
• 不要把 CTA、价格、表单或广告位藏在装饰性的交互后面。
• 不要只依赖颜色或鼠标拖拽，键盘操作和文字替代同样重要。
• 不要让 Claude Code 改动无关文件，否则 review 成本会迅速上升。

验证方法

运行 build 后，用 375px 移动端宽度检查没有横向溢出。确认代码块可滚动，CTA 可见，键盘焦点清楚，错误状态不会让页面空白。再让 Claude Code 做第二轮 review，列出改动过的文件、有风险的假设、可以删掉的复杂度，以及回滚步骤。

商业化视角

如果想把这种改进放进团队流程，可以从 Claude Code 培训与咨询 开始。重点不只是把界面做得更好看，而是在提升可维护性的同时，守住广告、商品卡、咨询链接、价格表和表单这些收益相关的元素。

额外检查

发布前，把改动前后的页面对照一遍。确认商业动作依然一目了然、布局不会发生位移，并且实现足够小，能让另一位同事顺利 review。如果这次改进没法用一段话讲清楚，就把它拆成更小的补丁。

实测记录

这套流程，我是一边实际确认手机端宽度、代码块、CTA 和键盘操作，一边试出来的。把实现和 review 分开做，结果会更稳定。把数据型、比例尺、轴、标记、交互这几块边界先和 Claude Code 讲清楚，再让它动手，修改的来回次数会明显减少；尤其是一开始就把 aria-label 和聚焦时的 tooltip 列为条件，比事后再补无障碍支持要省事得多，代码和文章都更好解释。