Skip to content

Latest commit

 

History

History
1274 lines (1251 loc) · 45.1 KB

File metadata and controls

1274 lines (1251 loc) · 45.1 KB
title slug
HTML 属性参考
Web/HTML/Attributes

{{HTMLSidebar("Attributes")}}

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

属性列表

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

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

bgcolor {{ HTMLElement("body") }}、{{ HTMLElement("col") }}、{{ HTMLElement("colgroup") }}、{{ HTMLElement("marquee") }}、{{ HTMLElement("table") }}、{{ HTMLElement("tbody") }}、{{ HTMLElement("tfoot") }}、{{ HTMLElement("td") }}、{{ HTMLElement("th") }}、{{ HTMLElement("tr") }}

元素的背景颜色。

备注:这是遗留属性。请使用 CSS {{ Cssxref("background-color") }} 属性代替。

border {{ HTMLElement("img") }}、{{ HTMLElement("object") }}、{{ HTMLElement("table") }}

边框宽度。

备注:这是遗留属性。请使用 CSS {{ Cssxref("border") }} 属性代替。

buffered {{ HTMLElement("audio") }}、{{ HTMLElement("video") }} 包含已缓存媒体的时间范围。
capture {{ HTMLElement("input") }} 来自 Media Capture 规范,指定一个新文件是否可以被捕获。
charset {{ HTMLElement("meta") }} 申明该页面或脚本的字符编码。
checked {{ HTMLElement("input") }} 指出该元素在页面加载后是否处于选中状态。
cite {{ HTMLElement("blockquote") }}、{{ HTMLElement("del") }}、{{ HTMLElement("ins") }}、{{ HTMLElement("q") }} 包含一个指明引用或修改的来源的 URI。
class 全局属性 通常和 CSS 配合使用,使用常用属性来为元素添加样式。
color {{ HTMLElement("font") }}、{{ HTMLElement("hr") }}

该属性为文本设置颜色,可以使用具名颜色或十六进制 #RRGGBB 格式的颜色。

备注:这是遗留属性。请使用 CSS {{ Cssxref("color") }} 属性代替。

cols {{ HTMLElement("textarea") }} 定义一个 textarea 中包含多少列。
colspan {{ HTMLElement("td") }}、{{ HTMLElement("th") }} colspan 属性定义了一个单元格跨越的列数。
content {{ HTMLElement("meta") }} http-equivname 关联的值,取决于上下文。
contenteditable 全局属性 指示该元素的内容是否可以被编辑。
controls {{ HTMLElement("audio") }}、{{ HTMLElement("video") }} 指示浏览器是否应该向用户显示播放控件。
coords {{ HTMLElement("area") }} 指定热点区域坐标的一组值。
crossorigin {{ HTMLElement("audio") }}、{{ HTMLElement("img") }}、{{ HTMLElement("link") }}、{{ HTMLElement("script") }}、{{ HTMLElement("video") }} 元素如何处理跨源请求。
csp {{experimental_inline}} {{ HTMLElement("iframe") }} 指定嵌入文档必须同意对自身强制执行的内容安全策略。
data {{ HTMLElement("object") }} 指定资源的 URL。
data-* 全局属性 允许你对一个 HTML 元素附加自定义的属性。
datetime {{ HTMLElement("del") }}、{{ HTMLElement("ins") }}、{{ HTMLElement("time") }} 指示与元素关联的日期和时间。
decoding {{ HTMLElement("img") }} 指示解码图像的首选方法。
default {{ HTMLElement("track") }} 指示应启用该轨道,除非与用户首选项指示的不同。
defer {{ HTMLElement("script") }} 指示该脚本应在页面解析后执行。
dir 全局属性 定义文本的方向。允许的值有 ltr(从左到右)或 rtl(从右到左)。
dirname {{ HTMLElement("input") }}、{{ HTMLElement("textarea") }}
disabled {{ HTMLElement("button") }}、{{ HTMLElement("fieldset") }}、{{ HTMLElement("input") }}、{{ HTMLElement("optgroup") }}、{{ HTMLElement("option") }}、{{ HTMLElement("select") }}、{{ HTMLElement("textarea") }} 指示用户是否可以与该元素交互。
download {{ HTMLElement("a") }}、{{ HTMLElement("area") }} 指示用于下载资源的超链接。
draggable 全局属性 定义元素是否可以被拖拽。
enctype {{ HTMLElement("form") }} 定义 method 为 POST 时,表单数据的内容类型。
enterkeyhint {{experimental_inline}} {{ HTMLElement("textarea") }}, contenteditable enterkeyhint 指定在虚拟键盘上显示的回车键的动作标签(或图标)。该属性可用于表单控件(例如 textarea 元素的值),或者在可编辑宿主中的元素(例如使用 contenteditable 属性)。
for {{ HTMLElement("label") }}、{{ HTMLElement("output") }} 描述与当前元素绑定的元素。
form {{ HTMLElement("button") }}、{{ HTMLElement("fieldset") }}、{{ HTMLElement("input") }}、{{ HTMLElement("label") }}、{{ HTMLElement("meter") }}、{{ HTMLElement("object") }}、{{ HTMLElement("output") }}、{{ HTMLElement("progress") }}、{{ HTMLElement("select") }}、{{ HTMLElement("textarea") }} 指示该元素所属的表单。
formaction {{ HTMLElement("input") }}、{{ HTMLElement("button") }} 指示元素的动作,覆盖 {{ HTMLElement("form") }} 中定义的动作。
formenctype {{ HTMLElement("button") }}、{{ HTMLElement("input") }} 如果按钮/输入是{{Glossary("submit button", "提交按钮")}}(例如,type="submit"),该属性用于设置表单提交时要使用的编码类型。如果指定了该属性,则会覆盖按钮所属的 formenctype 属性。
formmethod {{ HTMLElement("button") }}、{{ HTMLElement("input") }} 如果按钮/输入是{{Glossary("submit button", "提交按钮")}}(例如,type="submit"),该属性用于设置表单提交时要使用的提交方法(GETPOST 等)。如果指定了该属性,则会覆盖按钮所属的 formmethod 属性。
formnovalidate {{ HTMLElement("button") }}、{{ HTMLElement("input") }} 如果按钮/输入是{{Glossary("submit button", "提交按钮")}}(例如,type="submit"),该布尔属性用于指示在提交表单时不进行验证。如果指定了该属性,则会覆盖按钮所属的 formnovalidate 属性。
formtarget {{ HTMLElement("button") }}、{{ HTMLElement("input") }} 如果按钮/输入是{{Glossary("submit button", "提交按钮")}}(例如,type="submit"),该属性用于指定提交表单后接收到的响应在哪个浏览上下文(例如,标签页、窗口或内联框架)中显示。如果指定了该属性,则会覆盖按钮所属的 formtarget 属性。
headers {{ HTMLElement("td") }}、{{ HTMLElement("th") }} 应用于 <th> 元素的 ID。
height {{ HTMLElement("canvas") }}、{{ HTMLElement("embed") }}、{{ HTMLElement("iframe") }}、{{ HTMLElement("img") }}、{{ HTMLElement("input") }}、{{ HTMLElement("object") }}、{{ HTMLElement("video") }}

指定此处列出的元素的高度。对于其他所有元素,请使用 CSS {{cssxref("height")}} 属性。

备注:对于某些实例,例如 {{ HTMLElement("div") }},这是一个遗留属性,对于这些实例应使用 CSS {{ Cssxref("height") }} 属性代替。

hidden 全局属性 阻止对给定元素的渲染,同时保持子元素(例如脚本元素)处于激活状态。
high {{ HTMLElement("meter") }} 指示高值区间的下限值。
href {{ HTMLElement("a") }}、{{ HTMLElement("area") }}、{{ HTMLElement("base") }}、{{ HTMLElement("link") }} 关联资源的 URL。
hreflang {{ HTMLElement("a") }}、{{ HTMLElement("link") }} 指定关联资源的语言。
http-equiv {{ HTMLElement("meta") }} 定义编译程序指令(pragma directive)。
id 全局属性 通常与 CSS 一起使用,以为特定元素添加样式。此属性的值必须是唯一的。
integrity {{ HTMLElement("link") }}、{{ HTMLElement("script") }} 指定子资源完整性值,允许浏览器验证它们获取的内容。
intrinsicsize {{deprecated_inline}} {{ HTMLElement("img") }} 此属性指示浏览器忽略图像的实际的固有大小,并假设它是属性中指定的大小。
inputmode {{ HTMLElement("textarea") }}, contenteditable 提供一个提示,指示用户在编辑元素或其内容时可能输入的数据类型。该属性可用于表单控件(例如 textarea 元素的值),或者在可编辑宿主中的元素(例如使用了 contenteditable 属性的)。
ismap {{ HTMLElement("img") }} 指示图像是服务器端图像映射(image map)的一部分。
itemprop 全局属性
kind {{ HTMLElement("track") }} 指定文本字幕的类型。
label {{ HTMLElement("optgroup") }}、{{ HTMLElement("option") }}、{{ HTMLElement("track") }} 为元素指定用户可读的标题。
lang 全局属性 定义元素中使用的语言。
language {{deprecated_inline}} {{ HTMLElement("script") }} 定义元素中使用的脚本语言。
loading {{experimental_inline}} {{ HTMLElement("img") }}、{{ HTMLElement("iframe") }} 指示元素是否应该被懒加载(loading="lazy")或立即加载(loading="eager")。
list {{ HTMLElement("input") }} 指示建议用户输入的预定义选项列表。
loop {{ HTMLElement("audio") }}、{{ HTMLElement("marquee") }}、{{ HTMLElement("video") }} 指示媒体在播放结束时是否应从头开始播放。
low {{ HTMLElement("meter") }} 指示低值区间的上限值。
max {{ HTMLElement("input") }}、{{ HTMLElement("meter") }}、{{ HTMLElement("progress") }} 指示允许的最大值。
maxlength {{ HTMLElement("input") }}、{{ HTMLElement("textarea") }} 定义元素中允许的最大字符数。
minlength {{ HTMLElement("input") }}、{{ HTMLElement("textarea") }} 定义元素中允许的最小字符数。
media {{ HTMLElement("a") }}、{{ HTMLElement("area") }}、{{ HTMLElement("link") }}、{{ HTMLElement("source") }}、{{ HTMLElement("style") }} 指定链接资源所设计的媒体的提示。
method {{ HTMLElement("form") }} POST. 定义用于提交表单的 HTTP 方法。可以是 GET(默认)或 POST
min {{ HTMLElement("input") }}、{{ HTMLElement("meter") }} 指示允许的最小值。
multiple {{ HTMLElement("input") }}、{{ HTMLElement("select") }} 指示是否可以在 emailfile 类型的输入中输入多个值。
muted {{ HTMLElement("audio") }}、{{ HTMLElement("video") }} 指示页面加载时音频是否会被静音。
name {{ HTMLElement("button") }}、{{ HTMLElement("form") }}、{{ HTMLElement("fieldset") }}、{{ HTMLElement("iframe") }}、{{ HTMLElement("input") }}、{{ HTMLElement("object") }}、{{ HTMLElement("output") }}、{{ HTMLElement("select") }}、{{ HTMLElement("textarea") }}、{{ HTMLElement("map") }}、{{ HTMLElement("meta") }}、{{ HTMLElement("param") }} 元素的名称。例如,用于服务器标识表单提交中的字段。
novalidate {{ HTMLElement("form") }} 此属性指示在提交表单时不应验证表单。
open {{ HTMLElement("details") }}、{{ HTMLElement("dialog") }} 指示内容目前是否可见(若用于 <details> 元素)或对话框是否处于活动状态且可以与之交互(若用于 <dialog> 元素)。
optimum {{ HTMLElement("meter") }} 指示最佳数值。
pattern {{ HTMLElement("input") }} 定义用于验证元素值的正则表达式。
ping {{ HTMLElement("a") }}、{{ HTMLElement("area") }} ping 属性指定一个用空格分隔的 URL 列表,以便在用户访问超链接时通知这些 URL。
placeholder {{ HTMLElement("input") }}、{{ HTMLElement("textarea") }} 提供用于告诉用户可以在字段中输入什么的提示。
playsinline {{ HTMLElement("video") }} 布尔属性,指示视频是否要“内嵌”播放;也就是说,在元素的播放区域内播放。请注意,该属性的缺失并不意味着视频将始终以全屏模式播放。
poster {{ HTMLElement("video") }} 用于指示在用户播放或搜索之前要显示的海报帧的 URL。
preload {{ HTMLElement("audio") }}、{{ HTMLElement("video") }} 指示是否应预加载整个资源、部分资源或者不预加载。
readonly {{ HTMLElement("input") }}、{{ HTMLElement("textarea") }} 指示元素是否可以被编辑。
referrerpolicy {{ HTMLElement("a") }}、{{ HTMLElement("area") }}、{{ HTMLElement("iframe") }}、{{ HTMLElement("img") }}、{{ HTMLElement("link") }}、{{ HTMLElement("script") }} 指定在获取资源时发送哪个引荐来源(referrer)。
rel {{ HTMLElement("a") }}、{{ HTMLElement("area") }}、{{ HTMLElement("link") }} 指示目标对象与链接对象的关系。
required {{ HTMLElement("input") }}、{{ HTMLElement("select") }}、{{ HTMLElement("textarea") }} 指示是否必须填写此元素。
reversed {{ HTMLElement("ol") }} 指示列表是否应以降序而不是升序显示。
role 全局属性 定义元素的显式角色,供辅助技术使用。
rows {{ HTMLElement("textarea") }} 定义文本区域的行数。
rowspan {{ HTMLElement("td") }}、{{ HTMLElement("th") }} 定义表格单元格应跨越的行数。
sandbox {{ HTMLElement("iframe") }} 阻止在 iframe 中加载的文档使用某些特性(例如提交表单或打开新窗口)。
scope {{ HTMLElement("th") }} 定义表头单元格(在 th 元素中定义)所关联的单元格。
scoped {{non-standard_inline}} {{deprecated_inline}} {{ HTMLElement("style") }}
selected {{ HTMLElement("option") }} 定义页面加载时将被选中的值。
shape {{ HTMLElement("a") }}、{{ HTMLElement("area") }}
size {{ HTMLElement("input") }}、{{ HTMLElement("select") }} 定义元素的宽度(以像素为单位)。如果元素的 type 属性是 textpassword,则它是字符数。
sizes {{ HTMLElement("link") }}、{{ HTMLElement("img") }}、{{ HTMLElement("source") }}
slot 全局属性 为影子 DOM(shadow DOM)影子树中的插槽分配一个元素。
span {{ HTMLElement("col") }}、{{ HTMLElement("colgroup") }}
spellcheck 全局属性 指示是否允许对元素进行拼写检查。
src {{ HTMLElement("audio") }}、{{ HTMLElement("embed") }}、{{ HTMLElement("iframe") }}、{{ HTMLElement("img") }}、{{ HTMLElement("input") }}、{{ HTMLElement("script") }}、{{ HTMLElement("source") }}、{{ HTMLElement("track") }}、{{ HTMLElement("video") }} 可嵌入内容的 URL。
srcdoc {{ HTMLElement("iframe") }}
srclang {{ HTMLElement("track") }}
srcset {{ HTMLElement("img") }}、{{ HTMLElement("source") }} 一个或多个响应式图像候选项。
start {{ HTMLElement("ol") }} 定义除 1 以外的第一个数字。
step {{ HTMLElement("input") }}
style 全局属性 定义将覆盖先前设置的 CSS 样式。
summary {{deprecated_inline}} {{ HTMLElement("table") }}
tabindex 全局属性 使用指定的聚焦(tab)顺序覆盖浏览器的默认聚焦顺序。
target {{ HTMLElement("a") }}、{{ HTMLElement("area") }}、{{ HTMLElement("base") }}、{{ HTMLElement("form") }} 指定打开链接文档的位置(若用于 <a> 元素)或显示接收到的响应的位置(若用于 <form> 元素)。
title 全局属性 在鼠标悬停在元素上时显示的提示文本。
translate 全局属性 指定当页面本地化时,元素的属性值和其文本节点后代的值是否应该被翻译,或者是否应该保持不变。
type {{ HTMLElement("button") }}、{{ HTMLElement("input") }}、{{ HTMLElement("embed") }}、{{ HTMLElement("object") }}、{{ HTMLElement("ol") }}、{{ HTMLElement("script") }}、{{ HTMLElement("source") }}、{{ HTMLElement("style") }}、{{ HTMLElement("menu") }}、{{ HTMLElement("link") }} 定义元素的类型。
usemap {{ HTMLElement("img") }}、{{ HTMLElement("input") }}、{{ HTMLElement("object") }}
value {{ HTMLElement("button") }}、{{ HTMLElement("data") }}、{{ HTMLElement("input") }}、{{ HTMLElement("li") }}、{{ HTMLElement("meter") }}、{{ HTMLElement("option") }}、{{ HTMLElement("progress") }}、{{ HTMLElement("param") }} 定义页面加载时元素中显示的默认值。
width {{ HTMLElement("canvas") }}、{{ HTMLElement("embed") }}、{{ HTMLElement("iframe") }}、{{ HTMLElement("img") }}、{{ HTMLElement("input") }}、{{ HTMLElement("object") }}、{{ HTMLElement("video") }}

确定此处所列元素的宽度。

备注:对于其他所有实例,例如 {{ HTMLElement("div") }},这是一个遗留属性,对于这些实例应使用 CSS {{ Cssxref("height") }} 属性代替。

wrap {{ HTMLElement("textarea") }} 指示文本是否应该换行。

内容属性和 IDL 属性

在 HTML 中,大多数属性都有两个方面:内容属性IDL(接口描述语言)属性

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

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

大多数时候,IDL 属性会返回元素实际使用的值。例如,{{HTMLElement("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 字符串,该字符串与属性名严格相同,前后都没有空格。以下示例是为一个布尔值属性取值的几个有效方式。

<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,因为这个属性出现了。

事件处理器属性

Warning

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

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

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

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

参见