HTML 属性参考
=========

HTML 中的元素拥有**属性**（attribute）；这些额外的值可以配置元素或者以各种方式来调整元素的行为，进而满足用户所需的标准。

属性列表
----

| 属性名 | 元素 | 描述 |
| --- | --- | --- |
| `accept (en-US)` | `<form>`、`<input>` | 服务器接受内容（通常是文件类型）的列表。 |
| `accept-charset` | `<form>` | 支持的字符集列表。 |
| `accesskey` | 全局属性 | 用于激活或聚焦元素的键盘快捷键。 |
| `action` | `<form>` | 处理通过表单提交的信息的程序的 URI。 |
| `align` 
已弃用
 | `<caption>`、`<col>`、`<colgroup>`、`<hr>`、`<iframe>`、`<img>`、`<table>`、`<tbody>`、`<td>` (en-US)、`<tfoot>`、`<th>`、`<thead>`、`<tr>` | 指定元素水平对齐的方式。 |
| `allow` | `<iframe>` | 指定 iframe 的特性策略。 |
| `alt` | `<area>`、`<img>`、`<input>` | 在图片无法显示时展示的替代文本。 |
| `async` | `<script>` | 异步执行该脚本。 |
| `autocapitalize` | 全局属性 | 设置用户输入时是否自动大写。 |
| `autocomplete` | `<form>`、`<input>`、`<select>`、`<textarea>` | 指示浏览器是否可以自动填充表单中的值。 |
| `autofocus` | `<button>`、`<input>`、`<select>`、`<textarea>` | 页面加载后，该元素应自动获得焦点。 |
| `autoplay` | `<audio>`、`<video>` | 音视频应该自动播放。 |
| `background` | `<body>`、`<table>`、`<td>` (en-US)、`<th>` | 指定图像文件的 URL。


**备注：**虽然浏览器和电子邮件客户端可能仍然支持此属性，但它已经过时。请使用
 CSS `background-image` 代替。

 |
| `bgcolor` | `<body>`、`<col>`、`<colgroup>`、`<marquee>`、`<table>`、`<tbody>`、`<tfoot>`、`<td>` (en-US)、`<th>`、`<tr>` | 元素的背景颜色。

**备注：**这是遗留属性。请使用
 CSS `background-color` 属性代替。

 |
| `border` | `<img>`、`<object>`、`<table>` | 边框宽度。

**备注：**这是遗留属性。请使用
 CSS `border` 属性代替。

 |
| `buffered` | `<audio>`、`<video>` | 包含已缓存媒体的时间范围。 |
| `capture (en-US)` | `<input>` | 来自 Media Capture 规范，指定一个新文件是否可以被捕获。 |
| `charset` | `<meta>` | 申明该页面或脚本的字符编码。 |
| `checked` | `<input>` | 指出该元素在页面加载后是否处于选中状态。 |
| `cite` | `<blockquote>`、`<del>`、`<ins>`、`<q>` | 包含一个指明引用或修改的来源的 URI。 |
| `class` | 全局属性 | 通常和 CSS 配合使用，使用常用属性来为元素添加样式。 |
| `color` | `<font>`、`<hr>` | 该属性为文本设置颜色，可以使用具名颜色或十六进制 #RRGGBB 格式的颜色。

**备注：**这是遗留属性。请使用
 CSS `color` 属性代替。

 |
| `cols` | `<textarea>` | 定义一个 textarea 中包含多少列。 |
| `colspan` | `<td>` (en-US)、`<th>` | colspan 属性定义了一个单元格跨越的列数。 |
| `content` | `<meta>` | 
 与 `http-equiv` 或 `name`
 关联的值，取决于上下文。
  |
| `contenteditable` | 全局属性 | 指示该元素的内容是否可以被编辑。 |
| `contextmenu` 
非标准

已弃用
 | 全局属性 | 定义将用作元素上下文菜单的 `<menu>` 元素的 ID。 |
| `controls` | `<audio>`、`<video>` | 指示浏览器是否应该向用户显示播放控件。 |
| `coords` | `<area>` | 指定热点区域坐标的一组值。 |
| `crossorigin` | `<audio>`、`<img>`、`<link>`、`<script>`、`<video>` | 元素如何处理跨源请求。 |
| `csp (en-US)`

实验性
 | `<iframe>` | 指定嵌入文档必须同意对自身强制执行的内容安全策略。 |
| `data` | `<object>` | 指定资源的 URL。 |
| `data-\*` | 全局属性 | 允许你对一个 HTML 元素附加自定义的属性。 |
| `datetime` | `<del>`、`<ins>`、`<time>` | 指示与元素关联的日期和时间。 |
| `decoding` | `<img>` | 指示解码图像的首选方法。 |
| `default` | `<track>` | 指示应启用该轨道，除非与用户首选项指示的不同。 |
| `defer` | `<script>` | 指示该脚本应在页面解析后执行。 |
| `dir` | 全局属性 | 定义文本的方向。允许的值有 ltr（从左到右）或 rtl（从右到左）。 |
| `dirname (en-US)` | `<input>`、`<textarea>` |  |
| `disabled` | `<button>`、`<fieldset>`、`<input>`、`<optgroup>`、`<option>`、`<select>`、`<textarea>` | 指示用户是否可以与该元素交互。 |
| `download` | `<a>`、`<area>` | 指示用于下载资源的超链接。 |
| `draggable` | 全局属性 | 定义元素是否可以被拖拽。 |
| `enctype` | `<form>` | 定义 `method` 为 POST 时，表单数据的内容类型。 |
| `enterkeyhint`

实验性
 | `<textarea>`,
 `contenteditable` | `enterkeyhint`
 指定在虚拟键盘上显示的回车键的动作标签（或图标）。该属性可用于表单控件（例如
 `textarea` 元素的值），或者在可编辑宿主中的元素（例如使用
 `contenteditable` 属性）。
  |
| `for (en-US)` | `<label>`、`<output>` | 描述与当前元素绑定的元素。 |
| `form` | `<button>`、`<fieldset>`、`<input>`、`<label>`、`<meter>`、`<object>`、`<output>`、`<progress>`、`<select>`、`<textarea>` | 指示该元素所属的表单。 |
| `formaction` | `<input>`、`<button>` | 指示元素的动作，覆盖 `<form>` 中定义的动作。 |
| `formenctype` | `<button>`、`<input>` | 
 如果按钮/输入是提交按钮 (en-US)（例如，`type="submit"`），该属性用于设置表单提交时要使用的编码类型。如果指定了该属性，则会覆盖按钮所属的
 form 的 `enctype` 属性。
  |
| `formmethod` | `<button>`、`<input>` | 
 如果按钮/输入是提交按钮 (en-US)（例如，`type="submit"`），该属性用于设置表单提交时要使用的提交方法（`GET`、`POST`
 等）。如果指定了该属性，则会覆盖按钮所属的
 form 的 `method` 属性。
  |
| `formnovalidate` | `<button>`、`<input>` | 
 如果按钮/输入是提交按钮 (en-US)（例如，`type="submit"`），该布尔属性用于指示在提交表单时不进行验证。如果指定了该属性，则会覆盖按钮所属的
 form 的 `novalidate` 属性。
  |
| `formtarget` | `<button>`、`<input>` | 
 如果按钮/输入是提交按钮 (en-US)（例如，`type="submit"`），该属性用于指定提交表单后接收到的响应在哪个浏览上下文（例如，标签页、窗口或内联框架）中显示。如果指定了该属性，则会覆盖按钮所属的
 form 的 `target` 属性。
  |
| `headers` | `<td>` (en-US)、`<th>` | 应用于 `<th>` 元素的 ID。 |
| `height` | `<canvas>`、`<embed>`、`<iframe>`、`<img>`、`<input>`、`<object>`、`<video>` | 
 指定此处列出的元素的高度。对于其他所有元素，请使用
 CSS `height` 属性。


**备注：**对于某些实例，例如
 `<div>`，这是一个遗留属性，对于这些实例应使用
 CSS `height` 属性代替。

 |
| `hidden` | 全局属性 | 阻止对给定元素的渲染，同时保持子元素（例如脚本元素）处于激活状态。 |
| `high` | `<meter>` | 指示高值区间的下限值。 |
| `href` | `<a>`、`<area>`、`<base>`、`<link>` | 关联资源的 URL。 |
| `hreflang` | `<a>`、`<link>` | 指定关联资源的语言。 |
| `http-equiv` | `<meta>` | 定义编译程序指令（pragma directive）。 |
| `id` | 全局属性 | 通常与 CSS 一起使用，以为特定元素添加样式。此属性的值必须是唯一的。 |
| `integrity` | `<link>`、`<script>` | 指定子资源完整性值，允许浏览器验证它们获取的内容。 |
| `intrinsicsize`

已弃用
 | `<img>` | 此属性指示浏览器忽略图像的实际的固有大小，并假设它是属性中指定的大小。 |
| `inputmode` | `<textarea>`,
 `contenteditable` | 
 提供一个提示，指示用户在编辑元素或其内容时可能输入的数据类型。该属性可用于表单控件（例如
 `textarea` 元素的值），或者在可编辑宿主中的元素（例如使用了
 `contenteditable` 属性的）。
  |
| `ismap` | `<img>` | 指示图像是服务器端图像映射（image map）的一部分。 |
| `itemprop` | 全局属性 |  |
| `kind` | `<track>` | 指定文本字幕的类型。 |
| `label` | `<optgroup>`、`<option>`、`<track>` | 为元素指定用户可读的标题。 |
| `lang` | 全局属性 | 定义元素中使用的语言。 |
| `language`

已弃用
 | `<script>` | 定义元素中使用的脚本语言。 |
| `loading` 
实验性
 | `<img>`、`<iframe>` | 指示元素是否应该被懒加载（`loading="lazy"`）或立即加载（`loading="eager"`）。 |
| `list` | `<input>` | 指示建议用户输入的预定义选项列表。 |
| `loop` | `<audio>`、`<marquee>`、`<video>` | 指示媒体在播放结束时是否应从头开始播放。 |
| `low` | `<meter>` | 指示低值区间的上限值。 |
| `manifest`

已弃用
 | `<html>` | 指定文档的缓存清单的 URL。


**备注：**该属性已过时，请使用
 `<link rel="manifest">`
 代替。

 |
| `max (en-US)` | `<input>`、`<meter>`、`<progress>` | 指示允许的最大值。 |
| `maxlength (en-US)` | `<input>`、`<textarea>` | 定义元素中允许的最大字符数。 |
| `minlength (en-US)` | `<input>`、`<textarea>` | 定义元素中允许的最小字符数。 |
| `media` | `<a>`、`<area>`、`<link>`、`<source>`、`<style>` | 指定链接资源所设计的媒体的提示。 |
| `method` | `<form>` | `POST`.
 定义用于提交表单的 HTTP
 方法。可以是 `GET`（默认）或 `POST`。
  |
| `min (en-US)` | `<input>`、`<meter>` | 指示允许的最小值。 |
| `multiple (en-US)` | `<input>`、`<select>` | 
 指示是否可以在 `email` 或 `file`
 类型的输入中输入多个值。
  |
| `muted` | `<audio>`、`<video>` | 指示页面加载时音频是否会被静音。 |
| `name` | `<button>`、`<form>`、`<fieldset>`、`<iframe>`、`<input>`、`<object>`、`<output>`、`<select>`、`<textarea>`、`<map>`、`<meta>`、`<param>` | 元素的名称。例如，用于服务器标识表单提交中的字段。 |
| `novalidate` | `<form>` | 此属性指示在提交表单时不应验证表单。 |
| `open` | `<details>`、`<dialog>` | 
 指示内容目前是否可见（若用于 `<details>`
 元素）或对话框是否处于活动状态且可以与之交互（若用于
 `<dialog>` 元素）。
  |
| `optimum` | `<meter>` | 指示最佳数值。 |
| `pattern` | `<input>` | 定义用于验证元素值的正则表达式。 |
| `ping` | `<a>`、`<area>` | `ping` 属性指定一个用空格分隔的 URL
 列表，以便在用户访问超链接时通知这些 URL。
  |
| `placeholder (en-US)` | `<input>`、`<textarea>` | 提供用于告诉用户可以在字段中输入什么的提示。 |
| `playsinline` | `<video>` | 布尔属性，指示视频是否要“内嵌”播放；也就是说，在元素的播放区域内播放。请注意，该属性的缺失并不意味着视频将始终以全屏模式播放。 |
| `poster` | `<video>` | 用于指示在用户播放或搜索之前要显示的海报帧的 URL。 |
| `preload` | `<audio>`、`<video>` | 指示是否应预加载整个资源、部分资源或者不预加载。 |
| `readonly` | `<input>`、`<textarea>` | 指示元素是否可以被编辑。 |
| `referrerpolicy` | `<a>`、`<area>`、`<iframe>`、`<img>`、`<link>`、`<script>` | 指定在获取资源时发送哪个引荐来源（referrer）。 |
| `rel` | `<a>`、`<area>`、`<link>` | 指示目标对象与链接对象的关系。 |
| `required (en-US)` | `<input>`、`<select>`、`<textarea>` | 指示是否必须填写此元素。 |
| `reversed` | `<ol>` | 指示列表是否应以降序而不是升序显示。 |
| `role` | 全局属性 | 定义元素的显式角色，供辅助技术使用。 |
| `rows` | `<textarea>` | 定义文本区域的行数。 |
| `rowspan` | `<td>` (en-US)、`<th>` | 定义表格单元格应跨越的行数。 |
| `sandbox` | `<iframe>` | 阻止在 iframe 中加载的文档使用某些特性（例如提交表单或打开新窗口）。 |
| `scope` | `<th>` | 定义表头单元格（在 `th` 元素中定义）所关联的单元格。 |
| `scoped`

非标准

已弃用
 | `<style>` |  |
| `selected` | `<option>` | 定义页面加载时将被选中的值。 |
| `shape` | `<a>`、`<area>` |  |
| `size (en-US)` | `<input>`、`<select>` | 
 定义元素的宽度（以像素为单位）。如果元素的 `type`
 属性是 `text` 或 `password`，则它是字符数。
  |
| `sizes` | `<link>`、`<img>`、`<source>` |  |
| `slot` | 全局属性 | 为影子 DOM（shadow DOM）影子树中的插槽分配一个元素。 |
| `span` | `<col>`、`<colgroup>` |  |
| `spellcheck` | 全局属性 | 指示是否允许对元素进行拼写检查。 |
| `src` | `<audio>`、`<embed>`、`<iframe>`、`<img>`、`<input>`、`<script>`、`<source>`、`<track>`、`<video>` | 可嵌入内容的 URL。 |
| `srcdoc` | `<iframe>` |  |
| `srclang` | `<track>` |  |
| `srcset` | `<img>`、`<source>` | 一个或多个响应式图像候选项。 |
| `start` | `<ol>` | 定义除 1 以外的第一个数字。 |
| `step (en-US)` | `<input>` |  |
| `style` | 全局属性 | 定义将覆盖先前设置的 CSS 样式。 |
| `summary`

已弃用
 | `<table>` |  |
| `tabindex` | 全局属性 | 使用指定的聚焦（tab）顺序覆盖浏览器的默认聚焦顺序。 |
| `target` | `<a>`、`<area>`、`<base>`、`<form>` | 
 指定打开链接文档的位置（若用于 `<a>`
 元素）或显示接收到的响应的位置（若用于
 `<form>` 元素）。
  |
| `title` | 全局属性 | 在鼠标悬停在元素上时显示的提示文本。 |
| `translate` | 全局属性 | 指定当页面本地化时，元素的属性值和其文本节点后代的值是否应该被翻译，或者是否应该保持不变。 |
| `type` | `<button>`、`<input>`、`<embed>`、`<object>`、`<ol>`、`<script>`、`<source>`、`<style>`、`<menu>`、`<link>` | 定义元素的类型。 |
| `usemap` | `<img>`、`<input>`、`<object>` |  |
| `value` | `<button>`、`<data>`、`<input>`、`<li>`、`<meter>`、`<option>`、`<progress>`、`<param>` | 定义页面加载时元素中显示的默认值。 |
| `width` | `<canvas>`、`<embed>`、`<iframe>`、`<img>`、`<input>`、`<object>`、`<video>` | 确定此处所列元素的宽度。

**备注：**对于其他所有实例，例如
 `<div>`，这是一个遗留属性，对于这些实例应使用
 CSS `height` 属性代替。

 |
| `wrap` | `<textarea>` | 指示文本是否应该换行。 |

内容属性和 IDL 属性
------------

在 HTML 中，大多数属性都有两个方面：**内容属性**和 **IDL（接口描述语言）属性**。

内容属性需要你在内容（HTML 代码）中设置，而且可以通过 `element.setAttribute()` 或 `element.getAttribute()` 来设置。内容属性总是一个字符串，即使里面的值是一个整数。例如，要将 `<input>` 元素的 `maxlength` 设置为 42，你需要在元素上调用 `setAttribute("maxlength", "42")`。

IDL 属性（attribute）也就是 JavaScript 属性（property）。你可以使用 JavaScript 属性如 `element.foo` 来设置这些属性。当你需要获取 IDL 属性的值时，IDL 属性总会使用隐含的内容属性的值（可能先经过转换）来返回一个值。同样地，当你设置这个值时，这个值会保存在内容属性中。换句话说，IDL 属性本质上反映了内容属性。

大多数时候，IDL 属性会返回元素实际使用的值。例如，`<input>` 的默认 `type` 是“text”，所以如果你设置 `input.type="foobar"`，`<input>` 元素仍然会是文本类型（在外观上和表现上），但 `type` 内容属性的值是“foobar”。然而，`type` IDL 属性依旧会返回字符串“text”。

IDL 属性并不总是字符串；例如 `input.maxlength` 是一个数字（有符号长整型）。使用 IDL 属性时，你读取或设置值的类型都是要求的类型。所以 `input.maxlength` 总会返回一个数字，而如果你要设置 `input.maxlength`，也需要使用数字。如果你传入了别的类型，则会根据标准 JavaScript 的类型转换规则被转换为数字。

IDL 属性可以反映其他类型，如无符号长整型、URL、布尔类型，等。不幸的是，并没有清晰的规则定义一个属性的 IDL 属性与对应的内容属性如何关联。大多数时候，这会遵守规范中列出的规则，但有时并不遵守。HTML 规范尝试将这件事尽可能变得对开发者友好，但由于很多原因（大多是历史原因），一些属性表现得很奇怪（例如 `select.size`），你就需要阅读规范以理解它们实际是如何表现的。

布尔属性
----

一些内容属性（例如 `required`、`readonly`、`disabled`）是布尔属性。如果一个布尔值属性存在，则其值为**真**（true），如果不存在，其值为**假**（false）。

HTML 定义了布尔属性允许的取值：如果属性存在，其值必须是一个空字符串（或未给该属性赋值），或者是一个大小写无关的 ASCII 字符串，该字符串与属性名严格相同，前后都没有空格。以下示例是为一个布尔值属性取值的几个有效方式。


```html
<div itemscope>这是一个有效的 HTML，但不是有效的 XML。</div>
<div itemscope=itemscope>这也是有效的 HTML，但不是有效的 XML。</div>
<div itemscope="">这是有效的 HTML，也是有效的 XML。</div>
<div itemscope="itemscope">这也是有效的 HTML 或 XML，但可能有点冗长。</div>
```


再明确一点，布尔值属性不能取值为 `"true"` 和 `"false"`。如果需要表示假值，布尔值属性需要整个忽略不写。这个限制消除了一些常见的误解：比如在元素中设置 `checked="false"`，元素的 `checked` 属性会被解析为 **true**，因为这个属性出现了。

事件处理器属性
-------

**警告：** 不建议使用事件处理器属性。将 HTML 和 JavaScript 代码混合在一起通常会产生难以维护的代码，而且事件处理器属性的执行也可能会被内容安全策略阻止。

除了上表中列出的属性，全局事件处理器（例如 `onclick`）也可以作为内容属性在所有元素上指定。

所有事件处理器属性都接受字符串值。字符串将用于合成 JavaScript 函数，例如 `function name(/*args*/) {body}`，其中，`name` 为属性名，`body` 为属性值。处理器接收与其 JavaScript 事件处理器对应项相同的参数——大多数处理器只接收一个 `event` 参数，而 `onerror` 接收五个参数：`event`、`source`、`lineno`、`colno`、`error`。这意味着你通常可以在属性中使用 `event` 变量。


```html
<div onclick="console.log(event)">点击这里！</div>
<!-- 合成的处理器具有名称，你可以引用处理器本身 -->
<div onclick="console.log(onclick)">点击这里！</div>
```

参见
--

* HTML 元素