<input type="search">

<input> 元素的 search 类型是 专为用户输入搜索查询而设计的文本字段。功能上与 text 输入相同, 但是可以通过 user agent 进行不同样式的设置。

DOMString 代表搜索字段中包含的值。
事件 changeinput
支持的通用属性 autocomplete, list, maxlength, minlength, pattern, placeholder, required, size
IDL 属性 value
方法 select(), setRangeText() (en-US), setSelectionRange()

value 属性包含 DOMString 代表搜索字段中包含的值。 您可以在JavaScript使用 HTMLInputElement.value 属性。

searchTerms = mySearch.value;

如果没有针对输入的验证约束 (请参见 Validation),该值可以是任何文本字符串或空字符串 ("")。

其他属性

除了可在所有 <input> 上的属性(无论其类型)之外,搜索字段输入还支持以下属性:

属性 描述
list <datalist> 元素的ID,其中包含可选的预定义自动完成选项。
maxlength 输入应接受的最大字符数。
minlength 输入可以且仍被认为有效的最小字符数。
pattern 输入内容必须匹配的正则表达式才能有效。
placeholder 空时在输入字段中显示的示例值。
readonly 一个布尔属性,指示输入的内容是否应为只读。
size 一个数字,指示输入字段应宽多少个字符。
spellcheck 控制是否对输入字段启用拼写检查,或者是否应使用默认拼写检查配置。

{{page("/zh-CN/docs/Web/HTML/Element/input/text", "list", 0, 1, 2)}}

maxlength

用户可以在搜索字段中输入的最大字符数(以UTF-16代码为单位)。 必须为0或更高的整数。 如果未指定 maxlength 或指定了无效值,则搜索字段没有最大长度。 此值还必须大于或等于 minlength 的值。

如果输入到字段中的文本的长度大于 maxlength UTF-16代码单元的长度,则输入无法通过约束验证(constraint validation)。

minlength

用户可以在搜索字段中输入的最小字符数(以UTF-16代码为单位)。 该值必须是小于或等于 maxlength 指定的值的非负整数值。 如果未指定 minlength 或指定了无效值,则搜索输入没有最小长度。

如果在字段中输入的文本的长度小于 minlength UTF-16代码单元的长度,则搜索字段将无法通过约束验证(constraint validation)。

pattern

如果指定了 pattern 属性,则它是输入的 value 必须匹配正则表达式,以使该值通过约束验证(constraint validation)。它必须是 RegExp 类型使用有效 JavaScript 正则表达式,并且已在我们的正则表达式指南(guide on regular expressions)中进行了说明;在编译正则表达式时指定了 'u' 标志,因此该模式被视为Unicode代码点的序列,而不是ASCII。 模式文本周围不能指定正斜杠。

如果指定的模式未指定或无效,则不应用任何正则表达式,并且将完全忽略此属性。

提示:使用 title 属性指定大多数浏览器将显示为文本的工具提示,以说明与模式匹配的要求。 您还应该在附近添加其他说明性文字。

有关详细信息和示例,请参见 Specifying a pattern 部分。

{{page("/zh-CN/docs/Web/HTML/Element/input/text", "placeholder", 0, 1, 2)}}

{{page("/zh-CN/docs/Web/HTML/Element/input/text", "readonly", 0, 1, 2)}}

{{page("/zh-CN/docs/Web/HTML/Element/input/text", "size", 0, 1, 2)}}

spellcheck

{{page("/zh-CN/docs/Web/HTML/Element/input/text", "spellcheck-include")}}

非标准属性

以下非标准属性可用于搜索输入字段。 通常,除非没有帮助,否则应避免使用它们。

属性 描述
autocorrect 编辑此输入字段时是否允许自动更正。Safari only.
incremental 是否发送重复的 search 事件以允许在用户仍在编辑字段的值时更新实时搜索结果。WebKit and Blink only (Safari, Chrome, Opera, etc.).
mozactionhint 一个字符串,指示当用户在编辑字段时按 Enter 或 Return 键时将执行的操作类型; 用于确定虚拟键盘上该键的适当标签。Firefox for Android only.
results 先前搜索查询的下拉列表中应显示的最大项目数。Safari only.

autocorrect This API has not been standardized.

Safari扩展, the autocorrect 属性是一个字符串,它指示在用户编辑此字段时是否激活自动更正。 允许的值为:

on
启用拼写错误的自动更正,以及配置文本替换(如果已配置)的处理。
off
禁用自动更正和文本替换。

incremental This API has not been standardized.

布尔值 incremental 属性是 WebKit 和 Blink 扩展 (因此被 Safari, Opera, Chrome 等支持)如果存在,它会告诉 user agent 将输入作为实时搜索进行处理。 当用户编辑字段的值时,用户代理将 search 事件发送到代表搜索框的 HTMLInputElement 对象。这允许您的代码在用户编辑搜索时实时更新搜索结果。

如果 incremental 没有被指定,则仅当用户显式启动搜索时(例如,在编辑字段时按 Enter 或 Return )才发送 search 事件。

search 事件受速率限制,因此发送事件的频率不会超过实现定义的间隔。

mozactionhint This API has not been standardized.

一个Mozilla扩展程序,由Firefox for Android支持,它提供了一个提示,提示用户在编辑字段时按 Enter 或 Return 键将采取何种操作。 此信息用于确定在虚拟键盘上的 Enter 键上使用哪种标签。

注意: 注意:已将其标准化为全局属性 enterkeyhint,但尚未广泛实现。 要查看Firefox中正在实施的更改的状态,请参阅 bug 1490661.

允许的值为: go, done, next, search, 和 send. 浏览器使用此提示来决定在回车键上放置什么标签。

results This API has not been standardized.

results 属性是一个数字值(仅受Safari支持),可让您覆盖要在 <input> 元素的本机提供的先前搜索查询的下拉菜单中显示的最大条目数。

该值必须是非负十进制数字。 如果未提供或给出了无效值,则使用浏览器的默认最大条目数。

使用搜索输入

<input> 元素 search 类型与 text 类型的元素非常相似,不同之处在于它们专门用于处理搜索项。 它们的行为基本相同,但是用户代理可以默认选择不同的样式(当然,站点可以使用样式表向其应用自定义样式)。

基本例子

<form>
  <div>
    <input type="search" id="mySearch" name="q">
    <button>Search</button>
  </div>
</form>

如下:

q 是搜索输入中最常用 name ,尽管不是强制性的。提交后,发送到服务器的键值对数据将为 q=searchterm

你一定要记住设置 name 输入,否则不会提交任何内容。

搜索类型和文本类型之间的差异

主要的基本区别在于浏览器处理它们的方式。 首先要注意的是,某些浏览器显示一个十字图标,如果需要,可以单击该十字图标以立即删除搜索词。 以下屏幕截图来自Chrome:

此外,现代浏览器还倾向于自动存储先前在各个域中输入的搜索词,然后在该域的搜索输入中执行后续搜索时,这些搜索词会作为自动完成选项出现。 这有助于随着时间的流逝倾向于在相同或相似搜索查询上进行搜索的用户。 此屏幕截图来自Firefox:

现在,让我们看看可以应用于搜索表单的一些有用的技巧。

设置占位符

您可以在搜索输入中提供一个有用的占位符,使用placeholder 属性来提示要做什么。看下面的例子:

<form>
  <div>
    <input type="search" id="mySearch" name="q"
     placeholder="Search the site...">
    <button>Search</button>
  </div>
</form>

您可以在下面看到占位符的呈现方式:

搜索表单标签和辅助功能

搜索表单的一个问题是它们的可访问性。 常见的设计惯例是不为搜索字段提供标签(尽管可能会有放大镜图标或类似图标),因为由于放置位置的原因,搜索表单的目的通常对于视力正常的用户而言相当明显 (这个例子展示了一个典型的模式)。

但是,这可能会使屏幕阅读器用户感到困惑,因为他们不会对搜索输入内容有任何口头指示。 解决此问题而不会影响您的视觉设计的一种方法是使用 WAI-ARIA 功能:

  • <form> 元素上, search 值的 role 属性 使屏幕阅读器用户声明该表单是搜索表单。
  • 您还可以在 <input> 上使用 aria-label 属性。这应该是一个描述性的文本标签,屏幕阅读器会读出该标签; 它用作 <label>的非可视等效项。

让我们看一个例子:

<form role="search">
  <div>
    <input type="search" id="mySearch" name="q"
     placeholder="Search the site..."
     aria-label="Search through site content">
    <button>Search</button>
  </div>
</form>

您可以在下面看到它的呈现方式:

与上一个示例没有视觉上的区别,但是屏幕阅读器用户可以使用更多信息。

注意:有关此类辅助功能的更多信息,请参见 Signposts/Landmarks 。

输入框元素大小

可以使用 size 属性来控制输入框的尺寸。 使用它,您可以指定输入框一次可以显示的字符数。 例如,在此示例中,搜索框为30个字符宽:

<form>
  <div>
    <input type="search" id="mySearch" name="q"
    placeholder="Search the site..." size="30">
    <button>Search</button>
  </div>
</form>

结果是这个更宽的输入框:

验证方式

<input> 元素的 search 类型具有与常规文本 text 输入相同的验证功能。 通常,您不太可能希望对搜索框使用验证功能。 在许多情况下,应该只允许用户搜索任何内容,但是有几种情况需要考虑,例如搜索已知格式的数据。

注意:HTML表单验证不能替代确保输入数据格式正确的脚本。 对于某人来说,对HTML进行调整以使其绕过验证或完全删除验证太容易了。 有人也可以完全绕开您的HTML并将数据直接提交到您的服务器。 如果服务器端代码无法验证接收到的数据,则当将格式不正确的数据(或太大,类型错误的数据等等)输入数据库时,灾难可能会发生。

样式注意事项

有一些有用的伪类可用于设置有效/无效表单元素的样式: :valid:invalid。在本节中,我们将使用以下CSS,它将在包含有效值的输入旁边放置一个复选标记(勾号),并在包含无效值的输入旁边放置一个叉号。

input:invalid ~ span:after {
    content: '✖';
    padding-left: 5px;
    position: absolute;
}

input:valid ~ span:after {
    content: '✓';
    padding-left: 5px;
    position: absolute;
}

该技巧还需要将 <span> 元素放置在form元素之后,该form元素充当图标的持有者。 这是必要的,因为某些浏览器上的某些输入类型不能很好地显示直接位于其后的图标。

输入要求

您可以使用 required 属性作为在允许提交表单之前输入所需值的简单方法:

<form>
  <div>
    <input type="search" id="mySearch" name="q"
    placeholder="Search the site..." required>
    <button>Search</button>
    <span class="validity"></span>
  </div>
</form>

如下所示:

另外,如果您尝试在未输入搜索词的情况下提交表单,浏览器将显示一条消息。 以下示例来自Firefox:

form field with attached message that says Please fill out this field

当您尝试使用输入中包含的不同类型的无效数据提交表单时,将显示不同的消息; 请参阅以下示例。

输入值长度

您可以使用 minlength 属性为输入的值指定最小长度(以字符为单位); 同样,使用 maxlength 设置输入值的最大长度。

下面的示例要求输入的值的长度为4–8个字符。

<form>
  <div>
    <label for="mySearch">Search for user</label>
    <input type="search" id="mySearch" name="q"
    placeholder="User IDs are 4–8 characters in length" required
    size="30" minlength="4" maxlength="8">
    <button>Search</button>
    <span class="validity"></span>
  </div>
</form>

如下所示:

如果您尝试提交少于4个字符的表单,则会收到相应的错误消息(不同的浏览器会有所不同)。 如果尝试超过8个字符,浏览器将不允许您访问。

指定模式

您可以使用 pattern 属性指定一个正则表达式,输入值必须遵循该正则表达式才能被视为有效 (请参照 Validating against a regular expression).

让我们看一个例子。 假设我们想提供一个产品ID搜索表格,这些ID都是由两个字母和四个数字组成的代码。 以下示例对此进行了介绍:

<form>
  <div>
    <label for="mySearch">Search for product by ID:</label>
    <input type="search" id="mySearch" name="q"
    placeholder="two letters followed by four numbers" required
    size="30" pattern="[A-z]{2}[0-9]{4}">
    <button>Search</button>
    <span class="validity"></span>
  </div>
</form>

如下所示:

例子

您可以在我们的网站 website-aria-roles 示例中看到一个在上下文中使用搜索表单的一个好例子 (see it live).

规范

Specification Status Comment
HTML Living Standard
<input type="search">
Living Standard 初始化定义
HTML 5.1
<input type="search">
Recommendation 初始化定义

浏览器兼容性

BCD tables only load in the browser

参见