使用 p5.js 读取 JSON 数据绘制动态柱状图

在前端交互式数据可视化场景中，使用 p5.js 读取外部 JSON 数据并绘制柱状图，核心在于完成三个递进环节：通过 preload() 函数配合 loadJSON() 实现可靠的异步数据预加载、基于画布边界与数据极值建立双向坐标映射比例尺、并在 draw() 渲染主循环中利用线性插值（lerp()）实现柱体高度平滑生长的缓动动画。相比依赖复杂图表库的黑盒方案，原生 p5.js 绘制直接操控 Canvas 像素矩阵，兼具轻量直观的开发体验与高度灵活的视觉定制能力。本文将拆解完整的实现路径，提供开箱即用的工程代码与易错点解决方案。

一、数据组织与本地运行环境准备

实现动态柱状图的第一步是规范化数据格式。通常我们将数据独立存储于工程目录下的 data.json 文件中，以便于后续业务数据的维护与接口解耦。数据格式推荐使用对象数组，每个元素包含图表所需的分类名称与具体度量值。

[
  { "label": "周一", "value": 68 },
  { "label": "周二", "value": 112 },
  { "label": "周三", "value": 145 },
  { "label": "周四", "value": 88 },
  { "label": "周五", "value": 130 },
  { "label": "周六", "value": 95 }
]

二、生命周期控制与安全数据加载

在传统的 JavaScript 异步编程中，网络请求常依赖回调函数或 Promise。如果在 p5.js 的 setup() 函数内直接调用异步请求，主渲染循环 draw() 会在请求响应返回前立即启动，导致读取数据时产生 TypeError: Cannot read properties of undefined 错误。

p5.js 针对此问题提供了专用的 preload() 生命周期钩子：

• 阻塞式加载机制：定义在 preload() 中的 loadJSON('data.json') 会被 p5.js 内部的加载计数器跟踪。在此阶段完成并解析出完整 JSON 对象之前，程序不会进入 setup()，从而彻底规避异步竞态条件；
• 全局变量接收：在 preload() 外层声明全局变量 let chartData = []，通过 loadJSON() 的返回值直接赋值。进入 setup() 时，chartData 已经是一个可读取长度与遍历的完整数组；
• 极值提取：在 setup() 中通过 Math.max(...chartData.map(d => d.value)) 计算出当前数据集的最大值，并保留约 15% 的顶部裕量，防止最高的柱体顶格贴紧画布边缘。

三、Canvas 坐标映射与几何尺寸推导

计算机屏幕绘图与传统数学坐标系存在一个核心差异：HTML5 Canvas 的坐标原点 (0, 0) 位于画布左上角，X 轴水平向右递增，而 Y 轴垂直向下递增。在绘制柱状图时，柱体需要从图表基准线向上“长出”，这就需要对 Y 坐标进行方向反转转换。

坐标与布局的核心数学推导由以下三个公式构成：

1. 有效绘制区域计算：为画布设定边距（marginTop、marginBottom、marginLeft、marginRight）。图表实际宽度 chartWidth = width - marginLeft - marginRight，实际高度 chartHeight = height - marginTop - marginBottom，底端水平基准线为 chartBottom = height - marginBottom；
2. 柱宽与间距动态分配：设数据项总数为 n，设定柱体间隙 barGap（例如 16 像素）。单个柱体的宽度公式为 barWidth = (chartWidth - (n - 1) * barGap) / n，第 i 个柱体的起始横坐标为 x = marginLeft + i * (barWidth + barGap)；
3. 比例尺高度与坐标取反：使用 p5.js 原生 map() 工具函数将原始业务值线性转换到像素范围：h = map(value, 0, maxValue, 0, chartHeight)。因为 p5.js 的 rect(x, y, w, h) 默认以左上角为定位点绘制矩形，柱体左上角纵坐标应设为 y = chartBottom - h。

四、缓动插值动画与鼠标悬停交互

若在每一帧直接绘制目标高度 h，图表在首帧就会瞬间渲染完毕，失去动态表现力。常见的帧累加方式（例如 h += 5）在触达目标值时会产生生硬的急停感。更为专业的做法是引入阻尼缓动插值函数 lerp()。

1. 基于 lerp() 的平滑生长算法

p5.js 内置的 lerp(start, stop, amt) 函数表示在 start 到 stop 之间按比例 amt 进行线性插值。我们在 setup() 中声明一个与数据长度相同且初值为 0 的高度数组 currentHeights。在每一帧 draw() 执行时，针对第 i 个柱体执行状态更新：

currentHeights[i] = lerp(currentHeights[i], targetHeight, 0.08);

在此公式中，amt = 0.08 为阻尼系数。每帧柱体生长距离为“当前高度与目标高度差值的 8%”。在初始阶段差值较大，柱体快速向上冲刺；随着高度逼近目标值，差值越来越小，生长速度自然减缓，约在 50~60 帧内柔和停靠在目标点，产生工业级平滑的减速动画效果。

2. 鼠标双轴碰撞判定与 Tooltip 浮层

为了使图表具备良好的交互反馈，我们在遍历绘制每个柱体时，检测当前鼠标指针坐标 (mouseX, mouseY) 是否命中该柱体的包围盒（Bounding Box）：

let isHovered = mouseX >= x && mouseX <= x + barWidth &&
                mouseY >= (chartBottom - currentHeights[i]) && mouseY <= chartBottom;

当判定为 true 时，我们将当前柱体的填充颜色切换为强调色（如稳重蓝 #477DAD），并记录该柱体的索引。为了防止悬停提示框（Tooltip）被后续绘制的相邻柱体遮挡，整个画布采用“双通道渲染”策略：先在主循环中完成所有网格、刻度与柱体的渲染，循环结束后若存在被选中的悬停柱体，再在最顶层绘制悬浮气泡框与精确数值。

五、完整开箱即用代码实现

以下是经过结构化封装的完整工程代码。包含标准 HTML 文件、JSON 数据以及完整的 sketch.js 逻辑脚本：

1. index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>p5.js 动态柱状图</title>
  <!-- 引入 p5.js 核心库 -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.0/p5.min.js"></script>
  <style>
    body {
      margin: 0;
      padding: 24px;
      background: #F8F9FA;
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
    }
    #chart-container {
      background: #FFFFFF;
      padding: 20px;
      border-radius: 10px;
      box-shadow: 0 4px 16px rgba(79, 98, 114, 0.1);
    }
  </style>
</head>
<body>
  <div id="chart-container"></div>
  <script src="sketch.js"></script>
</body>
</html>

2. sketch.js

// 全局状态变量
let rawData;
let chartData = [];
let currentHeights = [];
let maxValue = 0;

// 布局与尺寸定义
const canvasWidth = 760;
const canvasHeight = 440;
const margin = { top: 50, right: 40, bottom: 60, left: 60 };
const barGap = 18;
const easingFactor = 0.08;

// 色彩规范：钢灰与稳重蓝
const COLOR_PRIMARY = [79, 98, 114];
const COLOR_ACCENT = [71, 125, 173];
const COLOR_GRID = [226, 232, 240];
const COLOR_TEXT = [100, 116, 139];

function preload() {
  // 步骤 1：在 preload 钩子中同步阻塞预加载 JSON
  rawData = loadJSON('data.json');
}

function setup() {
  const canvas = createCanvas(canvasWidth, canvasHeight);
  canvas.parent('chart-container');
  textFont('-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif');

  // 转换并规范化数据数组
  chartData = Object.values(rawData);

  // 计算最大值并上浮 15% 留出视觉安全余量
  let peak = Math.max(...chartData.map(d => d.value));
  maxValue = Math.ceil(peak * 1.15);

  // 初始化插值高度数组为 0
  for (let i = 0; i < chartData.length; i++) {
    currentHeights[i] = 0;
  }
}

function draw() {
  background(255);

  const chartWidth = width - margin.left - margin.right;
  const chartHeight = height - margin.top - margin.bottom;
  const chartBottom = height - margin.bottom;
  const n = chartData.length;
  const barWidth = (chartWidth - (n - 1) * barGap) / n;

  // 1. 绘制水平参考网格线与 Y 轴刻度
  stroke(COLOR_GRID);
  strokeWeight(1);
  fill(COLOR_TEXT);
  textAlign(RIGHT, CENTER);
  textSize(11);

  const gridSteps = 4;
  for (let i = 0; i <= gridSteps; i++) {
    let stepVal = Math.round((maxValue / gridSteps) * i);
    let yPos = map(stepVal, 0, maxValue, chartBottom, margin.top);
    line(margin.left, yPos, width - margin.right, yPos);
    noStroke();
    text(stepVal, margin.left - 10, yPos);
    stroke(COLOR_GRID);
  }

  // 2. 绘制基准轴线
  stroke(COLOR_PRIMARY);
  strokeWeight(2);
  line(margin.left, chartBottom, width - margin.right, chartBottom);
  line(margin.left, margin.top, margin.left, chartBottom);

  let hoveredItem = null;
  let hoveredX = 0;
  let hoveredY = 0;

  // 3. 循环计算高度插值并绘制各柱体
  for (let i = 0; i < n; i++) {
    let targetH = map(chartData[i].value, 0, maxValue, 0, chartHeight);
    // 缓动推进
    currentHeights[i] = lerp(currentHeights[i], targetH, easingFactor);

    let x = margin.left + i * (barWidth + barGap);
    let y = chartBottom - currentHeights[i];

    // 碰撞检测
    let isHover = mouseX >= x && mouseX <= x + barWidth &&
                  mouseY >= y && mouseY <= chartBottom;

    if (isHover) {
      fill(COLOR_ACCENT);
      stroke(37, 99, 235);
      strokeWeight(1.5);
      hoveredItem = chartData[i];
      hoveredX = x + barWidth / 2;
      hoveredY = y;
    } else {
      fill(COLOR_PRIMARY);
      noStroke();
    }

    // 绘制柱体圆角矩形
    rect(x, y, barWidth, currentHeights[i], 4, 4, 0, 0);

    // 绘制底部 X 轴标签
    noStroke();
    fill(COLOR_PRIMARY);
    textAlign(CENTER, TOP);
    textSize(12);
    text(chartData[i].label, x + barWidth / 2, chartBottom + 12);
  }

  // 4. 最顶层绘制悬停提示气泡（Tooltip），防止被遮挡
  if (hoveredItem) {
    cursor(POINTER);
    drawTooltip(hoveredItem.label, hoveredItem.value, hoveredX, hoveredY);
  } else {
    cursor(ARROW);
  }
}

function drawTooltip(label, val, x, y) {
  push();
  const tipWidth = 92;
  const tipHeight = 32;
  const tipX = constrain(x - tipWidth / 2, margin.left, width - margin.right - tipWidth);
  const tipY = y - tipHeight - 10;

  // 气泡阴影与底框
  fill(30, 41, 59);
  noStroke();
  rect(tipX, tipY, tipWidth, tipHeight, 6);

  // 指示三角
  triangle(x - 5, tipY + tipHeight, x + 5, tipY + tipHeight, x, tipY + tipHeight + 6);

  // 提示文本
  fill(255);
  textAlign(CENTER, CENTER);
  textSize(11);
  text(`${label}: ${val}`, tipX + tipWidth / 2, tipY + tipHeight / 2);
  pop();
}

六、高频故障排查与避坑指南

在实际编码与调试过程中，初学者常会遇到以下几种典型现象与报错，可对照下表进行针对性处理：

• 控制台报 CORS 跨域错误：这是由于直接在文件系统双击 index.html 运行导致的。请确保工程在任意静态 HTTP 服务器环境下启动运行；
• 柱体向下生长甚至冲出屏幕底端：检查 rect() 调用中的 Y 参数。若写为 rect(x, chartBottom, barWidth, h)，矩形会以基准线为起点顺沿 Canvas 的正向 Y 轴向下延伸。必须纠正为 chartBottom - h；
• 页面初次刷新时文字与柱体闪烁：检查是否将 loadJSON() 错误地放置在了 setup() 函数内。放在 setup() 会导致前几个渲染帧读取空数据，产生数值重置与尺寸跳跃，必须统一放置在 preload() 中；
• 数据差异极小时柱体高度几乎无区别：若数据均值较高而离差较小（如 980 与 995），将 Y 轴起点直接设为 0 会导致肉眼极难辨识柱体差异。此时可根据业务需求，将映射区间的下限从 0 调整为 minValue * 0.9，以放大动态差值；
• Tooltip 在右侧边界柱体处被画布截断：在计算气泡左上角横坐标时，不可简单设为 x - tipWidth / 2，应当使用 p5.js 的 constrain(x - tipWidth / 2, margin.left, width - margin.right - tipWidth) 实施边界夹紧约束。

七、总结

通过本文的讲解与工程示例，我们梳理了在 p5.js 中读取外部 JSON 并构建平滑柱状图的核心路径：依托 preload() 阻断渲染竞态、运用 Canvas 坐标换算将业务数据严格缩放到安全视口、并通过帧状态数组与 lerp() 阻尼函数实现了从底层像素到动态缓动的完整把控。这一架构不仅适用于柱状图，还可无缝迁移至折线图、雷达图与多维散点图等各类交互式创意可视化项目的构建中。