<p>data-* 属性名必须全小写加连字符，否则 DOM 解析器直接忽略；dataset 自动转驼峰（如 data-user-id → userId），值恒为字符串，存对象需 JSON 序列化，修改推荐统一用 setAttribute/getAttribute。</p>
data-* 属性名必须全小写 + 连字符，否则 dataset 读不到
浏览器在解析 HTML 时，对 data-* 属性名有硬性校验：只接受以 data- 开头、后续全部为小写字母、数字和连字符（-）的组合。任何大写字母、下划线、驼峰或数字开头，都会被 DOM 解析器直接忽略——不是“读不到”，而是根本没进 dataset 映射表。
常见错误现象：element.dataset.userId 返回 undefined，但你在 HTML 里明明写了 data-userId="1002"；根源就是这个属性压根没被当成合法的 data-* 属性处理。
-
data-user-id✅ 合法，element.dataset.userId可读 -
data-userId❌ 非法，dataset中无对应字段 -
data-user_id❌ 部分浏览器能 fallback 到userId，但 IE 和 Next.js SSR 会丢弃 -
data-123id❌ 数字开头不推荐，老版 Safari 解析异常
dataset 自动转驼峰的规则不是“删短横线”，而是“短横后首字母大写”
dataset 的映射逻辑是确定的：把每个连字符（-）后面的第一个字母转成大写，其余全小写。它不依赖你“怎么想”，只按字面规则匹配。写错名字，JS 就找不到，也不会报错，只会默默返回 undefined。
-
data-api-url→element.dataset.apiUrl（不是apiUrl，更不是apiurl） -
data-xml-ns→element.dataset.xmlNs（xml是保留前缀，ns单独大写） -
data-last-modified-at→element.dataset.lastModifiedAt（每段都转，不只是第一个）
值永远是字符串，存对象必须 JSON 序列化
无论你赋什么类型给 dataset.xxx，浏览器最终存进 DOM 的都是字符串。直接塞对象会变成 "[object Object]"，数字会变字符串，布尔值也会转成 "true" 或 "false"。
立即学习“前端免费学习笔记（深入）”；
- 错误写法：
el.dataset.config = { theme: "dark" }→ 实际存的是"[object Object]" - 正确写法：
el.dataset.config = JSON.stringify({ theme: "dark", timeout: 3000 }) - 读取时必须判空再解析：
const config = el.dataset.config ? JSON.parse(el.dataset.config) : {}
修改 data 属性必须用 setAttribute，别混用 dataset 赋值
dataset 是只读映射（read-only proxy），它反映的是当前 DOM 中 data-* 属性的字符串值。你对 dataset.xxx 赋值，浏览器会自动调用 setAttribute('data-xxx', value)；但反过来，如果你用 setAttribute('data-user-id', '1003') 修改了属性，dataset.userId 会立刻同步更新。混用容易导致状态不一致，尤其在 SSR 或框架 hydration 场景下。
- 推荐统一用
setAttribute/getAttribute做持久化操作 -
dataset适合快速读取、临时计算，不适合做“唯一数据源” - 敏感信息（token、手机号、用户 ID）绝不能放
data-*——源码里明文可见
命名合规性这事，不是“差不多就行”，而是“错一个字符就失效”。最常被忽略的点是：你以为写对了，其实是浏览器在解析阶段就把它当普通属性扔掉了，连 warning 都不抛。
