ECharts 报错背后的 DOM 访问：从容器尺寸到安全渲染

打开控制台看到一长串报错，里面夹着 log.js:72 [echarts] can't get dom width or height. please check dom.clientWidth / clientHeight 的时候，很多人的第一反应是：ECharts 是不是没加载成功？版本是不是有问题？然后开始换 CDN、清缓存、查网络。但我可以负责任地说，这个报错绝大多数情况下根本不是库的问题，而是 DOM 访问出了问题。你在图表初始化的时候，容器没有拿到有效的宽度或高度，ECharts 连自己的画布都撑不开，自然只能打一行日志拒绝干活。

这里说的“DOM 访问”，并不只是 document.getElementById 这么简单。它决定了你写的代码会不会突然冒出 Cannot read properties of null，也决定了动态渲染出来的数据能不能稳定显示，更决定了你从 URL、接口、用户输入里拿到的内容放到页面后会不会变成安全隐患。无论你是刚写前端的小白，还是维护过几个后台系统的老手，把 DOM 访问这套逻辑捋清楚，再回头看那些奇奇怪怪的线上问题，多半会很通透。

这篇文章会从 DOM 访问的底层直觉讲起，聊清楚访问时机、选择器 API、布局尺寸、动态渲染和数据安全这些事。核心会围绕几个非常常见的场景展开：ECharts 的容器尺寸报错、AJAX 拿到 JSON 之后怎么把数据写进页面、还有什么是 DOM 型 XSS。全部代码都能直接在浏览器控制台里验证，不需要额外装任何环境。

1. 按“访问”的思路重新看 DOM 操作

1.1 访问一个 DOM 元素，本质上是在树里找一条路径

平时写 const btn = document.getElementById('saveBtn')，看起来只是一句获取元素的代码，但背后其实发生了很多步：浏览器把 HTML 解析成一棵节点树，然后从 document 根节点出发，按 id、标签、属性或选择器一路走到目标节点，最后把那个真实的节点对象交到变量里。

很多人会把“HTML 字符串”和“DOM 节点”混在一起。HTML 字符串只是源代码，DOM 节点是浏览器解析后生成的。你访问到的节点是可以直接修改属性、绑定事件、读取布局数据的活对象。这个区别很重要，因为一旦你通过 innerHTML 把整块内容替换掉，旧的节点对象并不会变成 null，它仍然存在，只是已经脱离了文档树。这种事我见过太多次了：开发者在页面初始化时缓存了一个 container 变量，后来又用 container.innerHTML = ... 整体刷新，再往后往这个旧容器里追加子节点，页面怎么都不更新，最后发现往一个已经不连在 DOM 树里的孤儿节点上写东西，浏览器当然不会画给你看。

整个访问过程可以分成三件事：找路径、取节点、保持引用。找路径要面对 css 选择器的匹配规则；取节点要区分单个元素和元素集合；保持引用则要关注节点什么时候从文档里被摘掉。理解了这些，你再看 document.querySelector 以后的操作，就会意识到它不是一行“取到就好”的代码，而是整条操作链的入口。

1.2 三个现实原因，让访问不会每次成功

第一个原因是时机。最经典的场景是在 head 里写 <script>，脚本一执行就去访问 body 里的 div，此时解析器还没走到那段结构，document.getElementById 只会拿到 null。有人把它改成 window.onload，有人加 defer，也有人把脚本挪到 body 底部。这些做法本质都一样：保证 DOM 树已经构建到了你要访问的节点。现在很多框架都是异步渲染，数据没回来之前，页面里对应区域还是空壳，你太早去访问，同样拿不到目标元素。

第二个原因是结构上下文。元素不一定都躺在同一条文档树里，它可能在 iframe 内部，可能在 Shadow DOM 里，也可能只是一段模板字符串还没被解析成节点。如果你直接用 document.querySelector 去查一个藏在 iframe 里的节点，肯定找不到。要是你同时在处理多个窗口或多标签页，还得确认访问的是哪个 document，否则就像在 A 仓库里找 B 仓库的货架，方向压根不对。

第三个原因是布局状态。就算你成功拿到了节点，也不代表它的宽度、高度、坐标已经可读。容器在折叠面板里隐藏着、父级没有设置高度导致子容器 height: 100% 落空、动画刚开始元素仍在 display: none 状态，这些都会让 clientWidth、clientHeight 拿到 0。DOM 节点存在只是第一步，节点有没有参与浏览器布局，是另一件必须确认的事。把结构访问和布局访问混为一谈，是很多“元素明明在啊，为什么尺寸读不出来”问题的根源。

2. 高频访问姿势与边界

2.1 选择器 API 怎么搭配合适

访问单个元素，最常用的是 getElementById 和 querySelector。性能上在老项目里 getElementById 通常更快一些，因为它能直接通过 id 索引定位；querySelector 灵活，但需要在内部解析选择器。日常业务中两者差距其实感知不到。我的习惯是：按 id 拿元素用 getElementById，按 class 或嵌套层级拿元素用 querySelector，尽量不写很长很深的 CSS 路径，因为结构稍微一变，选择器就会断。

querySelectorAll 和 getElementsByClassName 的差别更值得注意。前者返回的是静态 NodeList，等于在调用那一刻给元素集合拍了张快照；后者返回的是动态 HTMLCollection，它的长度和内容会随着 DOM 结构变化而实时改变。曾经我在一个循环里遍历 getElementsByClassName('item')，每个元素处理完就删掉，结果循环条件里每次重新读取集合长度，最后数组越删越短，后面一半元素根本没处理。后来统一改用 querySelectorAll，先拿快照再循环，问题才消失。

表单控件的访问也有专门入口。document.forms['loginForm'].elements['username'] 可以直接定位到指定表单里的输入框，比逐个 getElementById 简洁得多。这个入口很多年没变过，属于“老 API 但很好用”的那一类。不过当表单是动态渲染出来的时候，访问还是要等表单插入文档后再执行。

2.2 动态元素的访问时机：从 DOMContentLoaded 到 MutationObserver

访问动态元素最难受的一点是：你不知道它什么时候出现。数据请求是异步的，弹窗是点了按钮以后才渲染的，列表是滚动到底部才加载的。如果都靠“过一会儿再访问”的 setTimeout，不仅慢，还得猜时间，猜短了节点还没出来，猜长了页面体验差。

比较靠谱的思路是改访问方式。事件委托就是一个例子，你不去直接找目标按钮绑定事件，而是把监听器挂到更稳定的父级或 document 上，等事件触发时再用 e.target.closest('.target') 去访问实际元素。这样就算目标元素是未来才出现的，也不影响事件绑定。

如果确实是拿到数据或用户操作后需要主动访问某个新生节点，可以用 MutationObserver 观察容器变化。举个例子，你向一个列表容器追加了一段 HTML，然后想立刻找到里面第一张图片并校验尺寸。虽然元素在 innerHTML 赋值后同步存在于 DOM，但某些情况下节点内部的资源加载状态还不完整，这时候可以先观察图片的 complete 属性，甚至监听它的 load 事件。动态渲染场景下，“节点出现在 DOM”和“内部资源可用”是两个不同的时间点，访问时要分清楚你要的是哪一个。

2.3 类名、自定义属性和文本内容访问的边界

对 class 的操作，我习惯统一走 classList，它能 add、remove、toggle、contains，比手动操作 className 字符串拼接安全得多。自定义属性访问优先用 dataset，element.dataset.userId 对应的是 data-user-id。注意 dataset 里只放得下字符串，放对象会被转成 [object Object]，放 JSON 也要先序列化再存，取出来再 JSON.parse，不能直接把一个对象塞进去。

文本内容的访问也有讲究。textContent 和 innerText 看起来都能拿到元素里的文字，但 textContent 会把所有子节点的文本拼起来，连隐藏元素的文本也会算进去；innerText 更贴近用户实际看到的内容，会触发浏览器做一次渲染相关的计算。写入内容时我会优先用 textContent，因为它不会把字符串里的 HTML 标签解析成节点，这也是后面说 DOM 型 XSS 时最关键的一道防线。

样式的访问是个大坑。element.style.width 只能拿到内联样式里写的宽度，如果宽度是在 <style> 或 CSS 文件里定义的，这里读到的是空字符串。想拿最终样式，必须用 window.getComputedStyle(element).width，它返回的是带单位的字符串，比如 100px。需要做计算时再用 parseFloat 转成数字。如果你关心的是元素实际占用的布局宽度，可以直接读 element.clientWidth，它包含 padding但不包含边框和外边距。每次访问这些尺寸时都要想清楚：我要的是内联样式、计算样式，还是布局宽度？选错了 API，拿到的结果自然不是心里想要的。

3. 从报错到完整数据渲染：DOM 访问实战

3.1 复现 ECharts 容器尺寸报错

把报错原文再看一遍：log.js:72 [echarts] can't get dom width or height. please check dom.clientWidth / clientHeight。ECharts 在 init 的时候需要容器有明确的宽度和高度，它会去读容器节点的 clientWidth 和 clientHeight。两个值只要有一个是 0，它就会认为容器还没有有效的显示空间，直接拒绝初始化。

最容易被这个报错击中的场景有三种。第一种，图表写在一个 Tab 页里，但这个 Tab 页的默认样式是隐藏的，display: none 会让容器没有布局尺寸。第二种，容器 CSS 写了 height: 100%，可父级根本没有设置高度，子级百分百也就成了空话。第三种，弹窗打开后马上初始化图表，可弹窗还在做入场动画，或者数据请求还没回来，弹窗里实际还是空的，等到弹窗真正显示出来时，初始化已经变成了一个失败动作。

我见过有人在报错出现后把 ECharts 从 4.x 一路升到 5.x，问题依然在。也见过有人把 CSS 里容器高度从 300px 改成 100vh，反而引发更多布局问题。实际上只要理解了尺寸访问的原理，这类报错非常好定位。

3.2 最小复现与三步排查

遇到这个报错，第一步先别看堆栈，打开控制台手动执行这几行：

javascript复制const el = document.getElementById('chart');
console.log('element:', el);
console.log('clientWidth:', el && el.clientWidth);
console.log('clientHeight:', el && el.clientHeight);
console.log('display:', el && window.getComputedStyle(el).display);

如果 display 是 none，问题就出在元素被隐藏了。你需要在真正显示它之后再初始化图表。如果 display 不是 none，但宽高仍然是 0，就往上查父级：

javascript复制console.log('parent display:', el.parentElement && getComputedStyle(el.parentElement).display);
console.log('parent clientHeight:', el.parentElement && el.parentElement.clientHeight);

还有一种情况是样式表里的高度没生效。你可以在 Elements 面板里选中节点，看 Computed 标签页里的宽度和高度到底是多少。手动改一个固定高度，如果图表立刻能显示，说明 CSS 高度链路出了问题，不是 ECharts 的问题。为了让这个排查过程不那么生硬，建议直接把这段打印封装成一个 debugElement('chart') 函数，开发环境下调用，省得每次都敲好几行。

3.3 初始化一个能自适应尺寸的图表

找到原因之后，修复思路就不是“改一行代码”这么简单了。你得保证初始化的时机在容器真正可见之后，还要让图表在后续窗口尺寸和容器尺寸变化时也能跟着更新。

常见的做法是把初始化封装成一个“等容器可见再执行”的函数：

javascript复制function initChartWhenVisible(el, option) {
  if (!el) return null;
  if (el.clientWidth > 0 && el.clientHeight > 0) {
    return echarts.init(el).setOption(option);
  }

  const check = () => {
    if (el.clientWidth > 0 && el.clientHeight > 0) {
      observer.disconnect();
      echarts.init(el).setOption(option);
    }
  };
  const observer = new MutationObserver(check);
  observer.observe(el, { attributes: true, childList: true, subtree: true });
  return null;
}

当然，这个观察器不能滥用。如果你在弹窗里初始化，弹窗打开以后会修改容器或父级的 style，MutationObserver 有机会触发检查。如果你的场景里弹窗显示方式是切 class，而变化发生在更上层的父节点，观察容器本身可能监控不到。另一种更轻量但也有效的方案，是在弹窗打开后使用 requestAnimationFrame 延迟一帧再初始化：

javascript复制modalOpen();
requestAnimationFrame(() => {
  const el = document.getElementById('chart');
  if (el && el.clientWidth > 0) {
    echarts.init(el).setOption(option);
  }
});

浏览器在把元素从隐藏切换到显示后，会在下一帧前完成布局，此时 clientWidth 已经是真实值。这个方法虽然在极复杂页面里偶尔要等两帧，但绝大多数情况下足够稳定。

尺寸变化这一层，比较经典的是监听 window.resize 后调用图表实例的 resize。如果页面上只有一两个图表，直接这么干没问题；如果图表多，最好做一个轻量防抖。现在更推荐用 ResizeObserver，因为它能监听容器自身尺寸变化，不需要依赖 window 事件：

javascript复制const chart = echarts.init(el, null, { renderer: 'canvas' });
const ro = new ResizeObserver(() => chart.resize());
ro.observe(el);

这样侧边栏收起、弹窗变大变小、甚至容器被 flex 布局压缩，都能自动触发重绘。别忘了在组件销毁时调用 ro.disconnect()，否则监听器一直活着，内存会涨。

3.4 请求 JSON 数据后，把数据安全写进 DOM

很多页面业务都是“请求接口拿到 JSON，再渲染到 DOM”。看起来不复杂，但这里藏着大量 DOM 访问细节。我先写一个比较完整的示例，请求用户列表，然后渲染成 li：

javascript复制async function loadUsers() {
  const container = document.getElementById('userList');
  if (!container) return;

  const res = await fetch('/api/users', {
    headers: { 'Content-Type': 'application/json' }
  });
  if (!res.ok) {
    container.textContent = '加载失败';
    return;
  }

  const users = await res.json();
  const fragment = document.createDocumentFragment();

  users.forEach((user) => {
    const li = document.createElement('li');
    li.className = 'user-item';
    li.textContent = `${user.name} - ${user.email}`;
    fragment.appendChild(li);
  });

  container.appendChild(fragment);
}

这段代码最关键的几个点恰恰都不是请求逻辑。第一，container 在渲染前重新查询了一次，而不是一直用很久以前缓存的引用，因为页面可能在等待接口时发生过其他渲染，旧容器可能已经被替换掉了。第二，用 DocumentFragment 把一次循环要追加的所有节点先组装好，最后只访问一次真实 DOM 做插入，这样能明显减少重排。第三，用 textContent 写入用户名和邮箱，用户数据里哪怕有 <img> 或 <script> 也不会被浏览器当成 HTML 解析，这从一开始就规避了大量 XSS 问题。

这个例子里我用的是 fetch。AJAX 这个老词里虽然带着 XML，但现在大家传输的数据基本是 JSON。如果你真的接到一个返回 XML 的接口，浏览器里可以用 DOMParser 来解析：

javascript复制const xmlDoc = new DOMParser().parseFromString(xmlString, 'text/xml');
const items = xmlDoc.getElementsByTagName('item');
for (const item of items) {
  console.log(item.textContent);
}

解析 XML 文本后拿到的也是一棵节点树，访问方式与 HTML DOM 很像，getElementsByTagName、parentNode、textContent 都能用。而在服务端或原生环境里，libxml 是经常听到的 XML 解析方案，很多语言绑定底层都实现了它。理解浏览器里的 DOM 树之后，再去看服务端的 XML 解析或 JSON 遍历，思路是连通的：你永远是从原始数据里找到结构，再把结构转换成页面或上层逻辑需要的内容。

3.5 DOM 型 XSS：访问到数据后别急着用 innerHTML

DOM 型 XSS 和普通 XSS 不太一样。它的数据不一定经过服务端，可能来自 location.hash、window.name、postMessage，也可能是某个接口返回后被前端代码拼接进了 HTML。攻击者的输入字符串本身不可怕，可怕的是你用 innerHTML 把它交给浏览器解析。浏览器会把 <img src=x onerror=...> 这样的字符串当成 HTML 标签处理，从而执行里面的脚本。

想要彻底避免这类问题，核心原则是：从不可信来源访问到的数据，默认不要当成 HTML。展示文本用 textContent，属性值用 setAttribute，真要拼 HTML 结构时，先用转义函数处理数据。

javascript复制function escapeHTML(str) {
  return String(str)
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

node.innerHTML = `<div class="title">${escapeHTML(userInput)}</div>`;

这不是完整的 XSS 防护，但作为基础防线足够应对日常拼接。更推荐的做法是干脆不用 innerHTML，改成 createElement 加 textContent，让数据永远停留在一个“文本值”的身份里。每当你写 .innerHTML 的时候，先问一句：这里面的值全部可信吗？只要有一个是从 URL 参数、接口响应、用户输入、第三方脚本里来的，就不要直接拼。DOM 访问的安全边界，就藏在每一次把数据放上页面的选择里。

4. 高频问题排查与日常提效

4.1 一张速查表定位常见 DOM 访问异常

4.2 三步法定位节点访问与尺寸问题

遇到诡异的渲染问题，先不要急着改业务代码，更不要靠猜。直接按三步走。第一步，在 console 里执行 document.querySelector('你怀疑的容器')，看返回的是元素还是 null。如果是 null，说明访问时机或选择器有问题，去 Elements 面板确认节点真实存在的位置和名字。第二步，如果元素存在，就读取它的布局状态，打印 getBoundingClientRect()、clientWidth、getComputedStyle(el).display、parentElement.clientHeight。通过这一组数据，你能立刻知道它是被隐藏、没有高度还是干脆没参与布局。第三步，如果问题发生在异步回调里，打开 Network 面板看请求返回时间，再在回调开头打一个 console.trace()，确认当前执行栈和页面状态。

还有一个特别实用的浏览器能力：DOM 断点。在 Elements 面板里选中节点，右键选择 Break on 下的子节点修改或属性修改，当代码动态改动这个节点时，浏览器会暂停在触发点。调用栈里能看到是哪个函数在什么时候改了它。这个方法查“样式被覆盖”“class 被莫名移除”特别高效，比自己一遍遍加日志快得多。

4.3 通过减少无意义的 DOM 访问来提效

每次访问 DOM 都有成本，频繁访问还可能让浏览器陷入强制同步布局。最典型的反例是在循环里反复读 offsetHeight：

javascript复制rows.forEach((row) => {
  row.style.height = row.offsetHeight + 1 + 'px';
});

因为读取 offsetHeight 会强制浏览器计算布局，而你的循环又同时在改高度，浏览器只能一遍遍重排。更好的做法是先把要的值读出来，再集中写入：

javascript复制const rows = document.querySelectorAll('tr');
const heights = Array.from(rows).map((row) => row.offsetHeight);
rows.forEach((row, index) => {
  row.style.height = heights[index] + 'px';
});

这种“先读后写”的习惯，看起来只是性能优化，实际也避免了很多意外。读取阶段拿到的是同一份快照，你不会在写入过程中因为 DOM 变化而读到错乱的值。

节点引用缓存也值得养成习惯。一个元素如果只在初始化时存在，之后不会替换，那把它存到一个变量里反复使用没问题。但如果页面区域经常整体刷新，每次渲染前都重新查询一次容器，比盲目复用旧引用更安全。判断引用是否还可靠，可以检查 element.isConnected，它返回 true 表示节点仍然连接在文档树上。用这个属性比判断 parentNode 更直观，也比自己维护一堆“是否销毁”的标记干净得多。

最后分享一点个人习惯。我写初始化图表的函数时，总会默认留一个 debug 开关，在开发环境打印一次容器尺寸和可见状态。别人看这段代码可能觉得多余，但它救过我很多次。DOM 访问这件事，看起来全是基础 API，真正难的是明白每一次访问背后对时机、布局和数据信任的要求。你把这些要求确认了，ECharts 的报错不会再让你慌，动态渲染和数据安全也会慢慢变成下意识的设计考虑。