HTMLInputElement - 操作 <input> 元素的选项，布局和显示

HTMLInputElement 接口提供了特殊的属性和方法来操作 <input> 元素的选项，布局和显示。

属性

与父表单相关的属性

form 只读

一个 HTMLFormElement 对象，返回对父 <form> 元素的引用。

formAction

一个 string，返回 / 设置元素的 formaction 属性，其中包含处理该元素提交的信息的程序的 URI。它将覆盖父表单的 action 属性。

formEnctype

一个 string，返回 / 设置元素的 formenctype 属性，其中包含用于将表单提交给服务器的内容类型。它将覆盖父表单的 enctype 属性。

formMethod

一个 string，返回 / 设置元素的 formmethod 属性，包含浏览器用来提交表单的 HTTP 方法。它将覆盖父表单的 method 属性。

formNoValidate

一个 Boolean，返回 / 设置元素的 formnovalidate 属性，指示该表单不被验证已提交。它将覆盖父表单的 novalidate 属性。

formTarget

一个 string，返回 / 设置元素的 formtarget 属性，其中包含名称或关键字，指示提交表单后在何处显示收到的响应。它将覆盖父表单的 target 属性。

适用于任何类型的未隐藏输入元素的属性

name

一个 string，返回 / 设置元素的 name 属性，其中包含在提交表单时标识元素的名称。

type

一个 string，返回 / 设置元素的 type 属性，指示要显示的控件的类型。有关可能的值，请参见 <input> 的 type 属性。

disabled

一个 Boolean，返回 / 设置元素的 disabled 属性，指示该控件不可用于交互。输入值将不会与表单一起提交。另请参见 readonly。

autofocus

一个 Boolean，返回 / 设置元素的 autofocus 属性，该属性指定页面加载时表单控件应具有输入焦点（除非用户覆盖它，例如键入其他控件）。文档中只有一个表单元素可以具有 autofocus 属性。如果 type 属性设置为 hidden，则不能应用该方法（即，您不能将焦点自动设置为隐藏控件）。

required

一个 Boolean，返回 / 设置元素的 required 属性，指示用户必须先填写一个值，然后才能提交表单。

value

一个 string，返回 / 设置控件的当前值。

注意： 如果用户输入的值与预期值不同，则可能会返回一个空字符串。

validity 只读

一个 ValidityState object，返回元素的当前有效性状态。

validationMessage 只读

一个 string，返回描述该控件不满足的验证约束的本地化消息（如果有）。如果控件不是约束验证的候选者（willvalidate 为 false），或者控件满足约束，则为空字符串。

willValidate 只读

一个 Boolean，返回元素是否为约束验证的候选者。如果有任何条件禁止其进行约束验证，则为 false，包括：其 type 为 hidden，reset 或 button；它有一个 <datalist> 祖先元素；其 disabled 属性为 true。

仅适用于类型为 checkbox 或 radio 的元素的属性

checked

一个 Boolean，当 type 为 checkbox 或radio时，返回 / 设置元素的当前状态。|

defaultChecked

一个 Boolean，返回 / 设置创建该对象的 HTML 中最初指定的单选按钮或复选框的默认状态。

indeterminate

一个 Boolean，返回复选框或单选按钮是否处于不确定状态。对于复选框，其结果是复选框的外观以某种方式被遮盖 / 或显示为灰色，以表明其状态是不确定的（即不是选中，也不是未选中）。不影响 checked 属性的值，单击复选框会将值设置为 false。

仅适用于类型为 image 的元素的属性

alt

一个 string，返回 / 设置元素的 alt 属性，其中包含当 type 为 image 时要使用的替代文本。

height

一个 string，如果 type 是 image，返回 / 设置元素的 height 属性，该属性定义按钮显示的图像的高度。

src

一个 string，如果 type 是 image，返回 / 设置元素的 src 属性，该属性指定要在图形提交按钮上显示的图像位置的 URI， 如果不是将忽略该属性。

width

一个 string，如果 type 是 image，返回 / 设置元素的 width 属性，该属性定义按钮显示的图像的宽度。

仅适用于类型为 file 的元素的属性

accept

一个 string，当 type 是 file 时，返回 / 设置元素的 accept 属性，其值为逗号分隔的文件类型列表。

allowdirs

一个 Boolean，是非标准目录上载 API 的一部分；表示是否允许在文件列表中同时选择目录和文件。仅在 Firefox 中实现，需通过首选项开启。

files

返回 / 接受 FileList 对象，其中包含 File 对象的列表，这些对象表示选择上传的文件。

webkitdirectory

一个 Boolean，返回 webkitdirectory 属性；如果为 true，则文件系统选择器界面仅接受目录，而不接受文件。

webkitEntries

一个包含 FileSystemEntry 对象的数组，描述当前选定的文件或目录。

仅适用于文本 / 包含数字的元素的属性

autocomplete

一个 string，如果 type 属性的值是 hidden，checkbox，radio，file 或按钮类型（button，submit，reset，image），返回 / 设置元素的 autocomplete 属性，指示浏览器是否可以自动完成控件的值。可能的值是：

• on：浏览器可以使用先前存储的值自动完成值
• off：用户必须明确输入一个值

max

一个 string，返回 / 设置元素的 max 属性，其中包含此项的最大值（数字或日期时间），该值不得小于其最小值（min属性）值。

maxLength

一个 long，返回 / 设置元素的 maxlength 属性，其中包含该值可以具有的最大字符数（以 Unicode 代码点表示）。（如果将此值设置为负数，则将引发异常。）

min

一个 string，返回 / 设置元素的 min 属性，其中包含此项的最小值（数字或日期时间），该值不得大于其最大值（max属性）值。

minLength

一个 long，返回 / 设置元素的 minlength 属性，其中包含该值可以具有的最少字符数（以 Unicode 代码点表示）。（如果将此值设置为负数，则将引发异常。）

pattern

一个 string，返回 / 设置元素的 pattern 属性，包含一个用于检查控件值的正则表达式。使用 title 属性描述模式以帮助用户输入。当 type 属性的值是 text，search，tel，url 或 email 时，该属性适用。否则将被忽略。

placeholder

一个 string，返回 / 设置元素的 placeholder 属性，其中包含向用户提示可以在控件中输入的内容。占位符文本不得包含回车符或换行符。当 type 属性的值是 text，search，tel，url 或 email 时，该属性适用。否则将被忽略。

readOnly

一个 boolean，如果 type 属性的值是 hidden，range，color，checkbox，radio，file 或按钮类型，返回 / 设置元素的 readonly 属性，指示用户是否无法修改控件的值。

selectionStart

一个 unsigned long，返回 / 设置所选文本的起始索引。如果未选择任何内容，它将返回文本输入光标（插入符号）在 <input> 元素内部的位置。

selectionEnd

一个 unsigned long，返回 / 设置所选文本的结束索引。如果没有选择，它将返回当前文本输入光标位置之后的字符偏移量。

selectionDirection

一个 string，返回 / 设置选择发生的方向。可能的值为：

• forward：如果在当前语言环境的开始到结束方向上进行选择
• backward：如果为反向选择
• none：如果方向未知

size

一个 unsigned long，返回 / 设置元素的 size 属性，其中包含控件的可视大小。如果 type 的值为 text 或 password，它表示字符的个数，其他类型该值表示像素的长度。仅当 type 设置为 text ，password，text，search，tel 或 url 时适用；否则将被忽略。

尚未分类的属性

defaultValue

一个 string，返回 / 设置默认值，该默认值最初是在创建该对象的 HTML 中指定的。

dirName

一个 string，返回 / 设置元素的方向性。

accessKey

一个 *string，返回包含单个字符的字符串，该字符串在按下时会将输入焦点切换到控件。

list 只读

一个 HTMLElement object，返回 list 属性指向的元素。如果在同一树中没有找到 HTML 元素，则该属性可能是 null 。

multiple

一个 Boolean，返回 / 设置元素的 multiple 属性，指示是否可以使用多个值（例如，多个文件）。

files

一个 FileList array，返回所选文件的列表。

HTMLInputElement.labels 只读

一个 NodeList array，返回 <label> 元素的列表，这些元素是该元素的标签。

step

一个 string，返回 / 设置元素的 step 属性，它与 min 和 max 来限制可以设置数字或日期时间值的增量。它可以是字符串 any 或正浮点数。如果未将其设置为 any，则控件仅接受大于最小值的步进值倍数的值。

valueAsDate

一个 Date object，返回/设置元素的值，将其解释为日期；如果无法进行转换，则为 null。

valueAsNumber

一个 double，返回元素的值，按顺序解释为以下值之一：

• 时间值
• 数字
• 如果无法进行转换，则为 NaN

autocapitalize

一个 string，定义用户输入的大写行为。有效值为 none，off，characters（字符）, words（单词）或 sentences（句子）。

inputmode

向浏览器提供有关在编辑此元素或其内容时要使用的虚拟键盘配置类型的提示。

HTMLInputElement.align

一个 string，表示元素的对齐方式。请改用 CSS。

HTMLInputElement.useMap

一个 string，表示客户端图像映射。

方法

blur()

从输入元素上移开焦点；点击键盘将不会触发到任何元素。

click()

模拟对输入元素的单击。

focus()

聚焦于输入元素；点击键盘将随后转到此元素。

select()

选择输入元素中的所有文本，并将其聚焦，以便用户随后可以替换其所有内容。

setSelectionRange()

在输入元素中选择文本范围（但不使其聚焦）。

setRangeText()

用新文本替换输入元素中的文本范围。

setCustomValidity()

设置元素的自定义有效性消息。如果此消息不是空字符串，则表示该元素是自定义有效性错误状态，并且不通过验证。

checkValidity()

返回一个 Boolean，如果元素是约束验证的候选者并且不满足其约束，则返回 false。在这种情况下，它还会在元素上触发 invalid 事件。如果该元素不是约束验证的候选者，或者满足其约束，则返回 true。

reportValidity()

运行 checkValidity() 方法，如果返回 false（对于无效的输入或未提供 pattern 属性），则它将以与提交表单相同的方式向用户报告输入无效。

HTMLInputElement.stepDown()

将 value 减去（step * n），如果未指定，则 n 默认为 1。

以下情况将引发 INVALID_STATE_ERR 异常：

• 如果该方法不适用于当前的 type 值，
• 如果元素没有 step 值，
• 如果 value 无法转换为数字，
• 如果结果值高于 max 或低于 min。

HTMLInputElement.stepUp()

将 value 加上（step * n），如果未指定，则 n 默认为 1。

以下情况将引发 INVALID_STATE_ERR 异常：

• 如果该方法不适用于当前的 type 值，
• 如果元素没有 step 值，
• 如果 value 无法转换为数字，
• 如果结果值高于 max 或低于 min。

HTMLInputElement.mozSetFileArray()

将在输入上选择的文件设置为给定的 File 对象数组。这是可以在框架脚本中使用的 mozSetFileNameArray() 的替代方法：chrome 脚本可以将文件作为文件对象打开并通过消息管理器发送。

HTMLInputElement.mozGetFileNameArray()

返回输入中所有文件名的数组。

HTMLInputElement.mozSetFileNameArray()

设置在输入中选择的文件的文件名。不能在框架脚本中使用，因为它可以访问文件系统。

事件

使用 addEventListener() 或通过为此接口的 oneventname 属性分配事件监听器来监听这些事件：

input

当 <input>，<select> 或 <textarea> 元素的 value 被更改时触发。请注意，这实际上是在 HTMLElement 接口上触发的，并且也适用于 contenteditable 元素，但是我们在这里列出了它，因为它最常与表单输入元素一起使用。也可以通过 oninput事件处理程序属性处理。

invalid

当元素在约束验证期间不满足其约束时触发。
也可以通过 oninvalid 事件处理程序属性处理。

search

当在 type="search" 的 <input> 上启动搜索时触发。
也可以通过 onsearch 事件处理程序属性处理。

规范

规范	状态	备注
HTML Living Standard HTMLInputElement 的定义	现行的标准
HTML5 HTMLInputElement 的定义	推荐	从技术上讲，现在在 HTMLElement 上定义了 tabindex 和 accesskey 属性以及 blur()，click() 和 focus() 方法。 以下属性现已过时：align 和 useMap。添加了以下属性：align，autofocus，dirName，files，formAction，formEncType，formMethod，formNoValidate，formTarget，height，indeterminate，labels，list，max，min，multiple，pattern，placeholder，required，selectionDirection，selectionEnd，selectionStart，step，validationMessage，validity，valueAsDate，valueAsNumber，width 和 willValidate。 添加了以下方法：checkValidity()，setCustomValidity()，setSelectionRange()，stepUp() 和 stepDown()。
Document Object Model (DOM) Level 2 HTML Specification HTMLInputElement 的定义	已过时	size 属性现在为 unsigned long。type 属性必须全部使用小写字母。
Document Object Model (DOM) Level 1 Specification HTMLInputElement 的定义	已过时	初始定义。

桌面浏览器兼容性

移动浏览器兼容性

1. 该属性是只读的。

2. 实验性的，没有特定的 UI。最新规范仍然存在差异：bug 835773。

相关链接

• 实现此接口的 HTML 元素：<input>