如何在 D3 v7 中正确处理异步 CSV 数据加载并避免全局数组未定义问题

本文详解 d3 v7 中 `d3.csv()` 的异步特性导致全局数组在函数外部仍为 `undefined` 的根本原因，并提供基于 `async/await` 的标准解决方案，确保数据加载完成后再执行地图标记创建等依赖操作。

D3 v7 的 d3.csv() 返回一个 promise，其内部数据解析与赋值操作是异步完成的。原代码中，data() 函数调用后立即执行 createMarkers(map)，此时 lat、projectName 等全局数组尚未被填充（因 .then() 回调还未执行），因此 lat.Length 为 0，所有索引访问均返回 undefined——这正是问题的核心。

要修复此问题，必须让 initMap() 等待 CSV 加载与数组填充完全结束。关键有两点：

1. data() 函数需返回 d3.csv() 的 Promise；
2. 调用处必须 await data()，而非仅调用 data()。

此外，原代码中存在几处需同步修正的细节：

• CSV 解析器函数中误将字符串字段（如 Project_Name, Artist）用 + 转为数字（应直接保留字符串）；
• d3.csv() 的类型转换函数参数名 d 与后续 .then() 中的 d 冲突，易引发混淆；
• 全局变量 map 被局部 const map 遮蔽，导致 createMarkers(map) 传入的是局部变量，而函数内实际使用的是全局 map（未初始化）。

以下是修正后的完整可运行代码：

// Request needed libraries. const { Map, InfoWindow } = await google.maps.importLibrary("maps"); const { LatLng } = await google.maps.importLibrary("core"); const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker");  // Global variables (initialized) let map; let projectName = []; let artist = []; let lat = []; let long = []; let markers = [];  // ✅ Return the Promise to enable await async function loadData() {   return d3.csv("/data/single.csv", (row) => ({     projectName: row.Project_Name,   // ✅ Keep as string     artist: row.Artist,               // ✅ Keep as string     lat: parseFloat(row.Latitude),    // ✅ Parse number safely     long: parseFloat(row.Longitude),  // ✅ Parse number safely   })); }  // ✅ Accept map instance as parameter (avoid global dependency) function createMarkers(m) {   for (let z = 0; z < lat.length; z++) {     markers[z] = new google.maps.Marker({       position: new google.maps.LatLng(lat[z], long[z]),       map: m,       title: projectName[z],     });   } }  async function initMap() {   map = new Map(document.getElementById("map"), {     zoom: 11,     center: { lat: 37.4239163, lng: -122.0947209 },     mapId: "[MAP ID]",     mapTypeControl: false,   });    const infoWindow = new google.maps.InfoWindow({     content: "",     disableAutoPan: true,   });    // ✅ Await CSV loading AND array population   try {     const data = await loadData(); // Returns parsed array of objects     // Populate global arrays     projectName = data.map(d => d.projectName);     artist = data.map(d => d.artist);     lat = data.map(d => d.lat);     long = data.map(d => d.long);   } catch (error) {     console.error("Failed to load CSV:", error);     return;   }    // ✅ Now safe to create markers   createMarkers(map); }  initMap();

注意事项总结：

• ❌ 不要仅调用 data() 而不 await —— 这等同于“发起请求后立刻继续”，数据尚未就绪；
• ✅ 始终对 d3.csv() 或封装它的函数使用 await，确保后续逻辑在数据可用后执行；
• ✅ 使用 .map() 批量赋值比手动 for 循环更安全、简洁，且避免索引越界风险；
• ✅ 添加 try/catch 处理网络失败或 CSV 格式错误，提升健壮性；
• ✅ 显式传递 map 实例而非依赖全局变量，提高函数可测试性与可维护性。

遵循上述模式，即可彻底解决“全局数组在异步加载后仍为 undefined”的典型陷阱。