HTML 属性参考

¥Attribute list

¥Content versus IDL attributes

在 HTML 中，大多数属性都有两个面孔：内容属性和 IDL（接口定义语言）属性。

¥In HTML, most attributes have two faces: the content attribute and the IDL (Interface Definition Language) attribute.

内容属性是你从内容（HTML 代码）中设置的属性，你可以通过 element.setAttribute() 或 element.getAttribute() 设置或获取它。即使预期值应该是整数，内容属性也始终是字符串。例如，要使用内容属性将 <input> 元素的 maxlength 设置为 42，你必须在该元素上调用 setAttribute("maxlength", "42")。

¥The content attribute is the attribute as you set it from the content (the HTML code) and you can set it or get it via element.setAttribute() or element.getAttribute(). The content attribute is always a string even when the expected value should be an integer. For example, to set an <input> element's maxlength to 42 using the content attribute, you have to call setAttribute("maxlength", "42") on that element.

IDL 属性也称为 JavaScript 属性。这些是你可以使用 JavaScript 属性（例如 element.foo）读取或设置的属性。当你获取它时，IDL 属性始终会使用（但可能会转换）底层内容属性来返回一个值，并且当你设置它时，它会在内容属性中保存一些内容。换句话说，IDL 属性本质上反映了内容属性。

¥The IDL attribute is also known as a JavaScript property. These are the attributes you can read or set using JavaScript properties like element.foo. The IDL attribute is always going to use (but might transform) the underlying content attribute to return a value when you get it and is going to save something in the content attribute when you set it. In other words, the IDL attributes, in essence, reflect the content attributes.

大多数时候，IDL 属性会返回实际使用时的值。例如，<input> 元素的默认 type 是 "text"，因此如果设置 input.type="foobar"，<input> 元素将是文本类型（在外观和行为上），但 "type" 内容属性的值将为 "foobar"。但是，type IDL 属性将返回字符串 "text"。

¥Most of the time, IDL attributes will return their values as they are really used. For example, the default type for <input> elements is "text", so if you set input.type="foobar", the <input> element will be of type text (in the appearance and the behavior) but the "type" content attribute's value will be "foobar". However, the type IDL attribute will return the string "text".

IDL 属性并不总是字符串；例如，input.maxlength 是一个数字（有符号长整型）。使用 IDL 属性时，你读取或设置所需类型的值，因此 input.maxlength 始终会返回一个数字，而当你设置 input.maxlength 时，它需要一个数字。如果传递其他类型，它会自动转换为标准 JavaScript 类型转换规则指定的数字。

¥IDL attributes are not always strings; for example, input.maxlength is a number (a signed long). When using IDL attributes, you read or set values of the desired type, so input.maxlength is always going to return a number and when you set input.maxlength, it wants a number. If you pass another type, it is automatically converted to a number as specified by the standard JavaScript rules for type conversion.

IDL 属性可以是 反映其他类型，例如无符号长整型、URL、布尔值等。不幸的是，没有明确的规则，并且 IDL 属性与其相应的内容属性结合使用的方式取决于属性。大多数时候，它会跟随 规范中规定的规则，但有时却不会。HTML 规范试图使其尽可能对开发者友好，但由于各种原因（主要是历史原因），某些属性的行为很奇怪（例如 select.size），你应该阅读规范以了解它们的行为到底如何。

¥IDL attributes can reflect other types such as unsigned long, URLs, booleans, etc. Unfortunately, there are no clear rules and the way IDL attributes behave in conjunction with their corresponding content attributes depends on the attribute. Most of the time, it will follow the rules laid out in the specification, but sometimes it doesn't. HTML specifications try to make this as developer-friendly as possible, but for various reasons (mostly historical), some attributes behave oddly (select.size, for example) and you should read the specifications to understand how exactly they behave.

¥Boolean Attributes

某些内容属性（例如 required、readonly、disabled）称为 布尔属性。如果存在布尔属性，则其值为 true，如果不存在，则其值为 false。

¥Some content attributes (e.g. required, readonly, disabled) are called boolean attributes. If a boolean attribute is present, its value is true, and if it's absent, its value is false.

HTML 定义了对布尔属性允许值的限制：如果该属性存在，则其值必须是空字符串（等效地，该属性可能具有未分配的值），或者是与该属性的规范名称匹配的 ASCII 不区分大小写的值，且没有前导或尾随空格。以下示例是标记布尔属性的有效方法：

¥HTML defines restrictions on the allowed values of boolean attributes: If the attribute is present, its value must either be the empty string (equivalently, the attribute may have an unassigned value), or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace. The following examples are valid ways to mark up a boolean attribute:

<div itemscope>This is valid HTML but invalid XML.</div>
<div itemscope=itemscope>This is also valid HTML but invalid XML.</div>
<div itemscope="">This is valid HTML and also valid XML.</div>
<div itemscope="itemscope">
  This is also valid HTML and XML, but perhaps a bit verbose.
</div>

需要明确的是，布尔属性上不允许使用值“true”和“false”。要表示假值，必须完全省略该属性。这一限制消除了一些常见的误解：以 checked="false" 为例，元素的 checked 属性将被解释为 true，因为该属性存在。

¥To be clear, the values "true" and "false" are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether. This restriction clears up some common misunderstandings: With checked="false" for example, the element's checked attribute would be interpreted as true because the attribute is present.

¥Event handler attributes

警告：不鼓励使用事件处理程序内容属性。HTML 和 JavaScript 的混合通常会产生不可维护的代码，并且事件处理程序属性的执行也可能被内容安全策略阻止。

¥Warning: The use of event handler content attributes is discouraged. The mix of HTML and JavaScript often produces unmaintainable code, and the execution of event handler attributes may also be blocked by content security policies.

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

¥In addition to the attributes listed in the table above, global event handlers — such as onclick — can also be specified as content attributes on all elements.

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

¥All event handler attributes accept a string. The string will be used to synthesize a JavaScript function like function name(/*args*/) {body}, where name is the attribute's name, and body is the attribute's value. The handler receives the same parameters as its JavaScript event handler counterpart — most handlers receive only one event parameter, while onerror receives five: event, source, lineno, colno, error. This means you can, in general, use the event variable within the attribute.

<div onclick="console.log(event)">Click me!</div>
<!-- The synthesized handler has a name; you can reference itself -->
<div onclick="console.log(onclick)">Click me!</div>

¥See also

• HTML 元素