关于本文
本文是通过利用生成式 AI 的自动化生成流程创建的。我们将使用虚拟数据和浏览器操作来学习 D3.js 的用途、机制以及失败时的观察要点。不会访问实际的服务或个人信息。验证状态：2026-10-30 将官方文档与 GitHub 固定提交的 HTML/JavaScript 进行了核对。未执行实际浏览器操作、CDN 获取以及渲染/音频输出，文中的结果均为代码的期望值。
| 项目 | 内容 |
|---|---|
| 对象 | Chrome/Edge/Firefox 等现代浏览器（尚未确认真实设备兼容性） |
| 使用的库 | D3.js（教程内版本：7.9.0） |
| 费用 | 演示源码本身不需要付费 API。通信费用和使用条件取决于运行环境 |
| 数据 | 页面内的虚拟数据。无需认证信息、位置信息以及企业数据 |
| 学习操作 | 每次为动物投票时，改变圆圈的大小和票数 |
为什么尝试这项技术
绘制图表的库有很多，但 D3.js 的特点在于能够自由构建细节表现。本次的主题是虚拟的动物人气投票，将大熊猫、猫和猫头鹰的票数以圆圈的形式展示。按下投票按钮后，圆圈变大，票数字体也会更新。这不仅是修改圆圈的大小，而是一个帮助观察数值变化如何与屏幕元素相关联的教程。在选择图表库之前，我们需要思考现成的柱状图是否足够，或者是否需要独特的视觉表达。
在制作动态示例时，不能仅停留在“界面动了”这一表象上，还必须分清“哪个输入改变了哪个变量，以及哪个处理更新了绘制”。在本节教材中，我们会将这种变化明示在屏幕上。在将其集成到实际服务中时，请另外设计认证和保存逻辑。
首先尝试：实时演示与预期结果
最初是熊猫 3 票、猫 2 票、猫头鹰 1 票的虚拟数值。给猫投一票，观察当票数与熊猫相同时圆的半径是否相等。接下来重置，使所有动物票数归零，确认即使圆不可见，各动物的名字和 0 票依然保留。屏幕下方会以文字显示总票数。只看圆形的图像很难准确读出具体的票数，因此务必同时标注数值文本，这是关键所在。
操作前需确认的事项
确认您的电脑能够运行 JavaScript。不需要管理员权限。
打开浏览器的开发者工具，准备在 Console 中查看是否有错误，在 Network 中查看是否有 CDN 获取失败的情况。
如果演示未实际发布，请将 Daily Code 侧的
index.html和app.js保存到同一个文件夹中，并通过本地 HTTP 服务器打开。当使用 module 时，不保证直接通过 file:// 运行的行为。对比操作前后的结果。如果与期望值不同，请先记录“什么没有显示出来”。
运作机制全景图
flowchart LR
A["入力やクリック"] --> B["イベントを受ける"]
B --> C["D3.js のAPI"]
C --> D["状態と描画を更新"]
D --> E["見た目と文字で確認"]
此图为学习用的概念图，并未表示浏览器内部实现或网络通信的细节。无论是什么库，“追踪操作传达给了哪个变量”这一点都是相通的。
无法使用公开演示时的本地确认方法
将固定提交中的HTML 主体和JavaScript 主体通过 GitHub 的 Raw 视图分别index.html与app.js一起保存在同一个新文件夹中。仅靠 README 无法运行。在 Windows 上，在该文件夹中打开 PowerShell，py -3 -m http.server 8000 --bind 127.0.0.1而在 Linux/macOS 上，运行python3 -m http.server 8000 --bind 127.0.0.1，然后在同一台电脑上打开http://127.0.0.1:8000/。若要退出，请在终端中输入Ctrl+C。由于浏览器会从外部 CDN 获取库本身，如果无法连接，请检查控制台（Console）和网络（Network）错误。此步骤为复现指南，并非本文的浏览器实际测量报告。
它是如何运作的：解读 API
D3 的 select 以 DOM 元素为目标，data 将各个元素与数据关联起来。当显示对象的数量发生变化时，join 可以统一处理创建、更新和删除元素的方法。SVG 是可以嵌入 HTML 中的矢量格式，因此它可以分别拥有圆圈和文本作为元素。这里圆的半径不是直接乘以投票数，而是通过 scaleSqrt 转换为平方根比例尺。因为圆的面积与半径的平方成正比，如果让半径与数值成正比，就会夸大数量上的差异。
如何阅读最小代码
const scale = d3.scaleSqrt().domain([0, 30]).range([0, 75]);
svg.selectAll("circle").data(votes, d => d.name).join("circle")
.attr("r", d => scale(d.count));
以上是提取了 API 要点的代码片段。它不是可复制并独立运行的完整文件。运行所需的 HTML 和整套实现请在 Daily Code 侧的 README / 演示文件中确认。追踪哪个函数选择 HTML 元素、哪一行更新数值，并使用已知的虚拟值进行测试。
仅修改一个条件进行比较
即使为每种动物更改了颜色，也不要仅凭颜色判断，而是要显示名称。如果要向 SVG 添加条形图，可以使用相同的 data 数组创建多种显示格式。将 transition 的时长设为 0 会立即更新，但数值本身的大小并没有改变。为了在改变呈现方式时不必连带修改数据处理，应当将数值更新函数与绘图函数分离。
比较的步骤是：记录初始值，只更改一处，然后确认结果是否出现在预期的部分中。如果一次更改多个输入，就会分不清是什么产生了影响。请连同恢复到修改前状态的操作一起进行验证。
失败时应该检查哪里
如果圆圈数量太多，标签会重叠而无法阅读。此外，即使适当调整了圆圈的面积，仅凭分散的圆圈有时也很难准确比较排名。如果顺序很重要，条形图可能更合适。此外，必须假定更新会在 transition 过程中多次发生，并在此前提下检查绘图的一致性。由于此演示不会保存投票，重新加载会恢复为初始值。
| 观察到的状态 | 排查的要点 | 应对示例 |
|---|---|---|
| 画面从初始状态起没有变化 | 脚本获取、初始化、事件注册 | 检查 Console / Network / script 标签 |
| 显示发生了变化，但含义不对 | 输入值、数组、单位、更新目标 | 固定数值，逐个条件进行检查 |
| 无法点击按钮 | 选择器与 DOM 生成顺序 | 检查 HTML，确认 id 是否一致 |
| 仅在部分终端上无法运行 | 浏览器功能、权限、CDN、性能 | 记录终端及版本、复现操作 |
浏览器内的错误与公开 Web 服务器的故障是不同的。前者通过开发者工具中的错误内容进行排查，后者通过 HTTP 响应或静态资源分发条件进行排查。不把未知的失败描述为成功，能够提升技术笔记的可靠性。
在业务与学习中的应用
可用于问卷调查结果、分类结构、教育教材、展览品等场景。在实际选举或官方统计等用途中，必须另外实现显示前的票数统计、审计、签名以及防篡改功能。D3 是一个展示类库，并不保证投票的公正性。
引入前需要决定的事项
向读者公开时，需确定显示的数据从何而来、谁可以修改、屏幕上留存的信息种类，以及类库更新时的确认项目。本次演示中既没有登录也没有服务器保存。因此，在添加运维功能之前，建议首先区分“按预期显示的最小部分”以及“需要实际业务中的可靠性、权限和备份的部分”。第三方 CDN 涉及外部通信，因此需要提前确认企业网络是否允许使用。
与其他方式进行比较
| 方式 | 适用场景 | 注意事项 |
|---|---|---|
| D3.js | 符合使用目的的场景，例如每次为动物投票时更改圆圈大小和票数 | 需要更新依赖库并管理使用条件 |
| 浏览器标准 API | 自行编写小型功能 | 自行确认规范与兼容性 |
| 静态图像、表格 | 无需操作的说明 | 无法现场体验状态的变化 |
库是按需选择的工具。请结合您想要达成的目标与学习成本来进行对比。对于小规模页面，不以“引入库”为目的会更容易维护。
GitHub 示例
博客正文用于阐述背景与理念，Daily Code 则作为运行与改造的代码，两者分工明确。其中不包含用于向外部服务发送或保存数据的 API。
官方信息与第一手资料
资料确认范围：截至2026-10-27编辑时，请参考官方文档。这并不保证链接未来的更改或所有的CDN资产响应。
验证范围补充
我们将存储在GitHub上的固定源码与官方API说明进行了核对。浏览器操作、CDN加载以及在各个操作系统上的结果尚未经过验证。在进行实际运行确认时，请检查控制台（Console）和网络（Network），切勿仅凭画面的SUCCESS显示就断定所有条件都已成功。
