data-*属性名必须全小写加连字符，否则dataset不识别；正确命名如data-user-id映射为dataset.userId，错误命名如data-userId会被浏览器忽略；关键场景应使用getAttribute兜底，修改值须用setAttribute。
data-* 属性名必须全小写 + 连字符，否则 dataset 根本不认
浏览器在解析 HTML 时，对 data-* 属性的合法性有硬性校验：只接受 data- 后跟小写字母、数字或连字符（-），其余一律忽略。写成 data-userId、data_user_id、data-UserID，DOM 中看似存在，但 element.dataset 对象里压根没有对应字段——不是读不到，是根本没进 dataset。
常见错误现象：element.dataset.userId 返回 undefined，而你反复检查 HTML 确实写了 data-userId="123"。根源就是命名违规，浏览器在解析阶段就丢弃了该属性。
-
data-user-id✅ 正确，JS 可通过dataset.userId访问 -
data-api-url✅ 正确，映射为dataset.apiUrl -
data-2024-report✅ 合法，但 JS 中需用dataset["2024Report"]访问（不能点号） -
data-addval✅ 特殊但合法：无连字符 → 全小写访问，即dataset.addval，不是addVal
驼峰转换规则不是“去掉短横线”，而是严格大小写重映射
dataset 的驼峰转换不是简单删掉 - 再首字母大写，而是把每个 - 后的第一个字母转大写，其余全部小写。写错一个字母大小写，JS 就找不到对应 key，且不报错，只返回 undefined。
例如：data-order-status → dataset.orderStatus；data-order-STATUS 在 HTML 中会被浏览器标准化为 data-order-status，但如果你手误写成 data-order-Status（S 大写），部分解析器会直接忽略。
立即学习“前端免费学习笔记（深入）”；
- 正确映射链：
data-product-category→dataset.productCategory - 错误预期：
data-product-category≠dataset.ProductCategory（首字母不能大写） - 含数字开头：
data-2024-year→dataset["2024Year"]，点号访问会语法错误 - 纯单词：
data-role→dataset.role，不是dataset.Role
IE11 和 SSR 场景下，getAttribute 是更稳的兜底方案
IE11 对 data-* 的驼峰映射有已知 bug：比如 data-user-id 有时无法稳定映射为 dataset.userId，尤其在动态插入或模板渲染后。Next.js 等 SSR 框架在服务端解析时，也可能因严格模式丢弃下划线命名（如 data_user_id）导致前后端 dataset 不一致。
此时直接用 getAttribute 绕过驼峰逻辑，最可靠：
const userId = element.getAttribute('data-user-id'); // 始终返回字符串，不管命名多怪
const cost = Number(element.getAttribute('data-cost') || '0');
- 不依赖浏览器的 dataset 映射逻辑，兼容性拉满
- 避免因命名微小偏差（如多空格、大小写混用）导致静默失败
- 适合关键路径逻辑，比如权限判断、路由跳转参数提取
修改 data-* 值必须用 setAttribute，别碰 dataset 赋值
element.dataset.xxx = 'new' 在现代浏览器虽能工作，但在 IE11 和部分移动端 WebView 中不生效，且某些构建工具（如旧版 Vite 插件）会剥离这类动态写入。真正跨环境安全的方式，永远是 setAttribute。
- ✅ 正确写法：
element.setAttribute('data-user-id', '789') - ❌ 避免写法：
element.dataset.userId = '789'（兼容性差 + SSR 不同步） - 删除属性也一样：
element.removeAttribute('data-user-id')，而非delete element.dataset.userId - 批量更新建议统一走
setAttribute，避免混用造成行为不一致
实际项目里最容易被忽略的，是 HTML 模板由后端拼接时混用下划线或驼峰命名——前端开发者只看 JS 报错 undefined，却查不到源头在哪。只要确保所有 data-* 出现在 HTML 中时，100% 符合「小写+连字符」，再配合 getAttribute 兜底关键读取，基本就避开了 95% 的驼峰冲突问题。
