本文深入解析 html `data-*` 自定义属性在 javascript 中通过 `dataset` 访问时的命名转换规则，重点解决因大小写不匹配导致的 `undefined` 或 `nan` 问题，并提供可靠、可复用的实践方案。
在 Web 开发中，使用 data-* 属性传递配置或状态信息是常见做法。但许多开发者在首次尝试通过 element.dataset 读取时，会意外得到 undefined——尤其当属性名含连字符（如 data-addval）时。根本原因在于：dataset 属性名遵循严格的驼峰化（camelCase）映射规则，且完全区分大小写。
? 命名映射规则：连字符 → 驼峰首字母大写
html 中的 data-addval 并不会映射为 dataset.addVal，而是映射为 dataset.addval（全小写）。这是因为浏览器将 data- 后的所有连字符 – 移除，并将紧跟其后的字母自动转为大写，其余字母保持小写。例如：
| HTML 属性名 | dataset 对应属性名 |
|---|---|
| data-addval | addval ✅ |
| data-add-val | addVal ✅ |
| data-addValue | addvalue ❌（非法：data-* 只允许小写字母、数字、连字符） |
| data-add-val-2 | addVal2 ✅ |
因此，你原始代码中的：
对应 dataset.addval，而非 dataset.addVal —— 这正是控制台输出 undefined 的根源。
立即学习“Java免费学习笔记（深入）”；
✅ 正确写法（推荐两种方案）
方案一：统一使用小写 dataset 键（最简单、最安全）
upgradeButtonsContainer.forEach((upgradeButton) => { upgradeButton.addEventListener("click", (e) => { const { addval, cost, progress } = e.target.dataset; // 注意：这里必须用 addval，不是 addVal console.log("addval =", addval); // "1"（字符串） // 安全转换为数字（推荐 number() 或 parseFloat()） const numAddVal = Number(addval); const numCost = Number(cost); const numProgress = parseFloat(progress); if (!isNaN(numAddVal) && !isNaN(numCost) && !isNaN(numProgress)) { upgrade(numCost, numAddVal, numProgress); } }); });方案二：修改 HTML 属性名以匹配驼峰预期（语义更清晰）
此时 js 中即可使用：
const { addVal, cost, progress } = e.target.dataset; // ✅ addVal 现在有效⚠️ 注意：data-add-val 是合法的 HTML 属性名；而 data-addVal 是非法的（data-* 规范禁止大写字母），浏览器会忽略它或导致不可预测行为。
?️ 更健壮的替代方案：getAttribute()
若需完全规避 dataset 的命名转换逻辑，或处理动态/非常规属性名，直接使用 getAttribute() 是最明确的选择：
const addvalStr = e.target.getAttribute('data-addval'); const addVal = addvalStr ? Number(addvalStr) : 0;该方式不依赖任何命名约定，语义直白，且兼容性极佳（支持所有浏览器）。
? 最佳实践总结
- ✅ 始终检查 HTML 属性名拼写与大小写：data-addval → dataset.addval；data-add-val → dataset.addVal。
- ✅ 对 dataset 值做类型校验：dataset.xxx 总是返回字符串，务必用 Number()、parseInt() 或 parseFloat() 转换，并配合 isNaN() 防御性判断。
- ✅ 优先使用解构赋值 + 默认值 提升可读性与鲁棒性：
const { addval = '0', cost = '0', progress = '0' } = e.target.dataset; const addVal = Number(addval); - ❌ 避免混合大小写命名（如 data-addVal），违反 html5 规范。
- ? 参考权威文档：MDN — Using data attributes
掌握这一底层映射机制，不仅能快速定位 undefined/NaN 问题，更能写出更清晰、可维护的 dom 数据交互逻辑。