HTML 属性参考

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

属性列表

属性名 元素 描述
accept <form><input> 服务器接受内容(通常是文件类型)的列表。
accept-charset <form> 字符集,必须为 "UTF-8"(如果提供)。
accesskey 全局属性 用于激活或聚焦元素的键盘快捷键。
action <form> 处理通过表单提交的信息的程序的 URI。
align 已弃用 <caption><col><colgroup><hr><iframe><img><table><tbody><td><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><th> 指定图像文件的 URL。

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

bgcolor <body><col><colgroup><marquee><table><tbody><tfoot><td><th><tr>

元素的背景颜色。

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

border <img><object><table>

边框宽度。

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

buffered <audio><video> 包含已缓存媒体的时间范围。
capture <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><th> colspan 属性定义了一个单元格跨越的列数。
content <meta> http-equivname 关联的值,取决于上下文。
contenteditable 全局属性 指示该元素的内容是否可以被编辑。
controls <audio><video> 指示浏览器是否应该向用户显示播放控件。
coords <area> 指定热点区域坐标的一组值。
crossorigin <audio><img><link><script><video> 元素如何处理跨源请求。
csp 实验性 <iframe> 指定嵌入文档必须同意对自身强制执行的内容安全策略。
data <object> 指定资源的 URL。
data-* 全局属性 允许你对一个 HTML 元素附加自定义的属性。
datetime <del><ins><time> 指示与元素关联的日期和时间。
decoding <img> 指示解码图像的首选方法。
default <track> 指示应启用该轨道,除非与用户首选项指示的不同。
defer <script> 指示该脚本应在页面解析后执行。
dir 全局属性 定义文本的方向。允许的值有 ltr(从左到右)或 rtl(从右到左)。
dirname <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 <label><output> 描述与当前元素绑定的元素。
form <button><fieldset><input><label><meter><object><output><progress><select><textarea> 指示该元素所属的表单。
formaction <input><button> 指示元素的动作,覆盖 <form> 中定义的动作。
formenctype <button><input> 如果按钮/输入是提交按钮(例如,type="submit"),该属性用于设置表单提交时要使用的编码类型。如果指定了该属性,则会覆盖按钮所属的 formenctype 属性。
formmethod <button><input> 如果按钮/输入是提交按钮(例如,type="submit"),该属性用于设置表单提交时要使用的提交方法(GETPOST 等)。如果指定了该属性,则会覆盖按钮所属的 formmethod 属性。
formnovalidate <button><input> 如果按钮/输入是提交按钮(例如,type="submit"),该布尔属性用于指示在提交表单时不进行验证。如果指定了该属性,则会覆盖按钮所属的 formnovalidate 属性。
formtarget <button><input> 如果按钮/输入是提交按钮(例如,type="submit"),该属性用于指定提交表单后接收到的响应在哪个浏览上下文(例如,标签页、窗口或内联框架)中显示。如果指定了该属性,则会覆盖按钮所属的 formtarget 属性。
headers <td><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> 指示低值区间的上限值。
max <input><meter><progress> 指示允许的最大值。
maxlength <input><textarea> 定义元素中允许的最大字符数。
minlength <input><textarea> 定义元素中允许的最小字符数。
media <a><area><link><source><style> 指定链接资源所设计的媒体的提示。
method <form> POST. 定义用于提交表单的 HTTP 方法。可以是 GET(默认)或 POST
min <input><meter> 指示允许的最小值。
multiple <input><select> 指示是否可以在 emailfile 类型的输入中输入多个值。
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 <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 <input><select><textarea> 指示是否必须填写此元素。
reversed <ol> 指示列表是否应以降序而不是升序显示。
role 全局属性 定义元素的显式角色,供辅助技术使用。
rows <textarea> 定义文本区域的行数。
rowspan <td><th> 定义表格单元格应跨越的行数。
sandbox <iframe> 阻止在 iframe 中加载的文档使用某些特性(例如提交表单或打开新窗口)。
scope <th> 定义表头单元格(在 th 元素中定义)所关联的单元格。
scoped 非标准 已弃用 <style>
selected <option> 定义页面加载时将被选中的值。
shape <a><area>
size <input><select> 定义元素的宽度(以像素为单位)。如果元素的 type 属性是 textpassword,则它是字符数。
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 <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),你就需要阅读规范以理解它们实际是如何表现的。

布尔属性

一些内容属性(例如 requiredreadonlydisabled)是布尔属性。如果一个布尔值属性存在,则其值为(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 接收五个参数:eventsourcelinenocolnoerror。这意味着你通常可以在属性中使用 event 变量。

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

参见