数据集和 data-*

适用范围	?

##### 3.2.3.9嵌入自定义不可见数据使用 `data-*` 属性

一个自定义数据属性是一个没有命名空间的属性，其名称以字符串 "data-" 开头，在连字符后至少有一个字符，是 <a href="infrastructure.html#xml-compatible">XML 兼容的</a>，并且不包含 <a href="infrastructure.html#uppercase-ascii-letters">大写 ASCII 字母</a>。

在 <a href="infrastructure.html#html-documents">HTML 文档</a> 中所有 <a href="infrastructure.html#html-elements">HTML 元素</a> 上的属性名称都会自动转换为 ASCII 小写，因此对 ASCII 大写字母的限制不会影响这些文档。

<a href="#custom-data-attribute" title="custom data attribute">自定义数据属性</a> 旨在存储特定于页面或应用程序的自定义数据，而这些数据没有更合适的属性或元素。

这些属性不打算由独立于使用这些属性的站点之外的软件使用。

例如，一个关于音乐的站点可以注释表示专辑中曲目的列表项，其中包含每个曲目的长度的自定义数据属性。然后，站点本身可以使用此信息来允许用户按曲目长度对列表进行排序，或按特定长度过滤列表中的曲目。

<ol>
 <li data-length="2m11s">Beyond The Sea</li>
 ...
</ol>

然而，让用户使用与该音乐站点无关的通用软件通过查看此数据来搜索特定长度的曲目是不合适的。

这是因为这些属性旨在由站点自己的脚本使用，而不是用于公共可用元数据的通用扩展机制。

每个 <a href="infrastructure.html#html-elements" title="HTML elements">HTML 元素</a> 可以指定任意数量的 <a href="#custom-data-attribute" title="custom data attribute">自定义数据属性</a>，并具有任意值。

元素 . <a href="#dom-dataset">dataset</a>

返回一个 <a href="infrastructure.html#domstringmap-0">DOMStringMap</a> 对象，用于该元素的 <a href="#attr-data-*">data-*</a> 属性。

带连字符的名称会变为驼峰式大小写。例如，data-foo-bar="" 变为 element.dataset.fooBar。

<a href="#dom-dataset" title="dom-dataset">dataset</a> IDL 属性提供了一种方便的方式来访问元素上的所有 <a href="#attr-data-*">data-*</a> 属性。在获取时，<a href="#dom-dataset">dataset</a> IDL 属性必须返回一个 <a href="infrastructure.html#domstringmap-0">DOMStringMap</a> 对象，该对象与以下算法相关联，这些算法在其元素上公开这些属性

获取名称-值对列表的算法

让 list 是一个空的名称-值对列表。
对于元素上的每个内容属性，其前五个字符是字符串 "data-"，并且剩余字符（如果有）不包含任何 <a href="infrastructure.html#uppercase-ascii-letters">大写 ASCII 字母</a>，按照这些属性在元素属性列表中显示的顺序，将一个名称-值对添加到 list 中，其名称是该属性的名称，移除了前五个字符，其值为该属性的值。
对于 list 中的每个名称，对于名称中紧跟 <a href="infrastructure.html#lowercase-ascii-letters" title="lowercase ASCII letters">小写 ASCII 字母</a> 的每个 "-" (U+002D) 字符，移除 "-" (U+002D) 字符，并将紧随其后的字符替换为相同的字符 <a href="infrastructure.html#converted-to-ascii-uppercase">转换为 ASCII 大写</a>。
返回 list。

设置名称到特定值的算法

让 name 是传递给该算法的名称。
让 value 是传递给该算法的值。
如果 name 包含一个 "-" (U+002D) 字符，后跟一个 <a href="infrastructure.html#lowercase-ascii-letters" title="lowercase ASCII letters">小写 ASCII 字母</a>，则抛出一个 <a href="infrastructure.html#syntaxerror">SyntaxError</a> 异常并中止这些步骤。
对于 name 中的每个 <a href="infrastructure.html#uppercase-ascii-letters" title="uppercase ASCII letters">大写 ASCII 字母</a>，在该字符之前插入一个 "-" (U+002D) 字符，并将该字符替换为相同的字符 <a href="infrastructure.html#converted-to-ascii-lowercase">转换为 ASCII 小写</a>。
在 name 的前面插入字符串 data-。
将具有名称 name 的属性的值设置为 value，如果该属性已经存在则替换任何先前的值。如果 setAttribute() 在设置具有名称 name 的属性时会抛出异常，则必须抛出相同的异常。

删除名称的算法

让 name 是传递给该算法的名称。
对于 name 中的每个 <a href="infrastructure.html#uppercase-ascii-letters" title="uppercase ASCII letters">大写 ASCII 字母</a>，在该字符之前插入一个 "-" (U+002D) 字符，并将该字符替换为相同的字符 <a href="infrastructure.html#converted-to-ascii-lowercase">转换为 ASCII 小写</a>。
在 name 的前面插入字符串 data-。
如果存在这样的属性，则移除具有名称 name 的属性。否则，不执行任何操作。

每次都必须返回相同的对象。

如果一个网页希望一个元素表示一个宇宙飞船，例如作为游戏的一部分，它必须使用 <a href="#classes">class</a> 属性以及 <a href="#attr-data-*">data-*</a> 属性

<div class="spaceship" data-ship-id="92432"
     data-weapons="laser 2" data-shields="50%"
     data-x="30" data-y="10" data-z="90">
 <button class="fire"
         onclick="spaceships[this.parentNode.dataset.shipId].fire()">
  Fire
 </button>
</div>

注意带连字符的属性名称如何在 API 中变为驼峰式大小写。

作者应仔细设计这些扩展，以便在忽略属性并删除任何关联的 CSS 时，页面仍然可用。

用户代理不得从这些属性或值中推断任何实现行为。旨在用于用户代理的规范不得将这些属性定义为具有任何有意义的值。

JavaScript 库可以使用 <a href="#custom-data-attribute" title="custom data attribute">自定义数据属性</a>，因为它们被认为是它们所使用的页面的一部分。鼓励由许多作者重用的库的作者在属性名称中包含他们的名称，以减少冲突的风险。在有意义的情况下，库作者还应鼓励使属性名称中使用的确切名称可自定义，以便可以在同一页面上使用作者不知情地选择了相同名称的库，并且即使这些版本不相互兼容，也可以在同一页面上使用特定库的多个版本。

例如，一个名为“DoQuery”的库可以使用属性名称，如 data-doquery-range，一个名为“jJo”的库可以使用属性名称，如 data-jjo-range。jJo 库还可以提供一个 API 来设置要使用的前缀（例如 J.setDataPrefix('j2')，使属性名称变为 data-j2-range）。

参见

外部资源

导入自：<a href="https://w3org.cn/html/wg/drafts/html/master/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes">https://w3org.cn/html/wg/drafts/html/master/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes</a.