diff --git a/files/zh-cn/web/html/element/input/search/index.md b/files/zh-cn/web/html/element/input/search/index.md index 7414cc9ab9ccfc..db0edfe132a12a 100644 --- a/files/zh-cn/web/html/element/input/search/index.md +++ b/files/zh-cn/web/html/element/input/search/index.md @@ -5,7 +5,7 @@ slug: Web/HTML/Element/Input/search {{HTMLSidebar}} -`{{HTMLElement("input")}}` 元素的 **`search`** 类型是 专为用户输入搜索查询而设计的文本字段。功能上与 [`text`](/zh-CN/docs/Web/HTML/Element/input/text) 输入相同，但是可以通过 `{{Glossary("user agent")}}` 进行不同样式的设置。 +**`search`** 类型的 {{HTMLElement("input")}} 是专为用户输入查询文本而设计的字段。功能上与 [`text`](/zh-CN/docs/Web/HTML/Element/Input/text) 输入相同，但是根据{{Glossary("user agent","用户代理")}}不同，可能会有不同的样式表现。 {{EmbedInteractiveExample("pages/tabbed/input-search.html", "tabbed-standard")}} @@ -13,7 +13,7 @@ slug: Web/HTML/Element/Input/search 值 - {{domxref("DOMString")}} 代表搜索字段中包含的值。 + 代表搜索字段中值的字符串。 事件 @@ -21,242 +21,280 @@ slug: Web/HTML/Element/Input/search 支持的通用属性 - {{htmlattrxref("autocomplete", "input")}}, {{htmlattrxref("list", "input")}}, {{htmlattrxref("maxlength", "input")}}, {{htmlattrxref("minlength", "input")}}, {{htmlattrxref("pattern", "input")}}, {{htmlattrxref("placeholder", "input")}}, {{htmlattrxref("required", "input")}}, {{htmlattrxref("size", "input")}}。 + {{htmlattrxref("autocomplete", "input")}}、{{htmlattrxref("list", "input")}}、{{htmlattrxref("maxlength", "input")}}、{{htmlattrxref("minlength", "input")}}、{{htmlattrxref("pattern", "input")}}、{{htmlattrxref("placeholder", "input")}}、{{htmlattrxref("required", "input")}}、{{htmlattrxref("size", "input")}}。 IDL 属性 value + + DOM 接口 +

{{domxref("HTMLInputElement")}}

+ 方法 - {{domxref("HTMLInputElement.select", "select()")}}, {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}}, {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}}。 + {{domxref("HTMLInputElement.select", "select()")}}、{{domxref("HTMLInputElement.setRangeText", "setRangeText()")}}、{{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}}。 ## 值 -`{{htmlattrxref("value", "input")}}` 属性包含 `{{domxref("DOMString")}}` 代表搜索字段中包含的值。您可以在 JavaScript 使用 `{{domxref("HTMLInputElement.value")}}` 属性。 +{{htmlattrxref("value", "input")}} 属性包含一个代表搜索字段中含有值的字符串。你可以使用 JavaScript 的 {{domxref("HTMLInputElement.value")}} 属性获取该值。 ```js searchTerms = mySearch.value; ``` -如果没有针对输入的验证约束 (请参见[验证方式](#验证方式))，该值可以是任何文本字符串或空字符串 (`""`)。 +如果没有针对该 input 的验证约束（请参见[验证方式](#验证方式)），该值可以是任何文本字符串或空字符串（`""`）。 ## 其他属性 -除了可在所有 `{{HTMLElement("input")}}` 上的属性（无论其类型）之外，搜索字段输入还支持以下属性： +除了可在所有 {{HTMLElement("input")}} 上应用的属性（无论其类型）之外，搜索字段输入还支持以下属性。 -| 属性 | 描述 | -| ----------------------------- | ---------------------------------------------------------------- | -| [`list`](#list) | `` 元素的 ID，其中包含可选的预定义自动完成选项。 | -| [`maxlength`](#maxlength) | 输入应接受的最大字符数。 | -| [`minlength`](#minlength) | 输入可以且仍被认为有效的最小字符数。 | -| [`pattern`](#pattern) | 输入内容必须匹配的正则表达式才能有效。 | -| [`placeholder`](#placeholder) | 空时在输入字段中显示的示例值。 | -| [`readonly`](#readonly) | 一个布尔属性，指示输入的内容是否应为只读。 | -| [`size`](#size) | 一个数字，指示输入字段应宽多少个字符。 | -| [`spellcheck`](#spellcheck) | 控制是否对输入字段启用拼写检查，或者是否应使用默认拼写检查配置。 | +### list -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "list", 0, 1, 2)}} +list 属性指定了一个 {{HTMLElement("datalist")}} 元素的 {{domxref("Element.id", "id")}}，用来提供输入建议。{{HTMLElement("datalist")}} 提供了一个预定义的值列表，向用户建议这个输入。列表中任何与 {{htmlattrxref("type", "input")}} 不兼容的值都不包括在建议选项中。所提供的值是建议，不是要求：用户可以从这个预定义的列表中选择，或者提供不同的值。 ### maxlength -用户可以在搜索字段中输入的最大字符数（以 UTF-16 代码为单位）。必须为 0 或更高的整数。如果未指定 `maxlength` 或指定了无效值，则搜索字段没有最大长度。此值还必须大于或等于 `minlength` 的值。 +用户可以在搜索字段中输入的最大字符数（以 UTF-16 码点为单位）。必须为 0 或更高的整数。如果未指定 `maxlength` 或指定了无效值，则搜索字段没有最大长度。此值还必须大于或等于 `minlength` 的值。 -如果输入到字段中的文本的长度大于 `maxlength` UTF-16 代码单元的长度，则输入无法通过约束验证（[constraint validation](/zh-CN/docs/Web/Guide/HTML/HTML5/Constraint_validation)）。 +如果输入到字段中的文本的长度大于 `maxlength` UTF-16 代码单元的长度，则输入无法通过[约束验证](/zh-CN/docs/Web/Guide/HTML/Constraint_validation)。 ### minlength -用户可以在搜索字段中输入的最小字符数（以 UTF-16 代码为单位）。该值必须是小于或等于 `maxlength` 指定的值的非负整数值。如果未指定 `minlength` 或指定了无效值，则搜索输入没有最小长度。 +用户可以在搜索字段中输入的最小字符数（以 UTF-16 码点为单位）。该值必须是小于或等于 `maxlength` 指定的值的非负整数值。如果未指定 `minlength` 或指定了无效值，则搜索输入没有最小长度。 -如果在字段中输入的文本的长度小于 `minlength` UTF-16 代码单元的长度，则搜索字段将无法通过约束验证（[constraint validation](/zh-CN/docs/Web/Guide/HTML/HTML5/Constraint_validation)）。 +如果在字段中输入的文本的长度小于 `minlength` UTF-16 代码单元的长度，则搜索字段将无法通过[约束验证](/zh-CN/docs/Web/Guide/HTML/Constraint_validation)。 ### pattern -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "pattern-include")}} +如果指定了 `pattern` 属性，为了使 `value` 通过[约束验证](/zh-CN/docs/Web/Guide/HTML/Constraint_validation)，必须满足该属性给定的正则表达式。它必须是 {{jsxref("RegExp")}} 类型的有效 JavaScript 正则表达式，并且已在我们的[正则表达式指南](/zh-CN/docs/Web/JavaScript/Guide/Regular_Expressions)中进行了说明；在编译正则表达式时指定了 `'u'` 标志，因此该模式被视为 Unicode 代码点的序列，而不是 ASCII。模式文本周围无需指定正斜杠。 + +如果模式未指定或无效，则不应用任何正则表达式，并且将完全忽略此属性。 + +> **备注：** 使用 {{htmlattrxref("title", "input")}} 属性指定大多数浏览器将显示为文本的工具提示，以说明与模式匹配的要求。你还应该在附近添加其他说明性文字。 + +请参照[指定模式](#指定模式)更多内容和例子。 + +### placeholder + +`placeholder` 属性是一个字符串，可向用户提供有关该字段中需要什么样的信息的简短提示。它应该是一个单词或短语来说明预期的数据类型，而不是说明性消息。文本中*不得*包含回车符或换行符。 + +如果控件的内容具有方向（{{Glossary("LTR")}} 或 {{Glossary("RTL")}}），但需要以相反的方向显示占位符，则可以使用 Unicode 双向算法来格式化字符，从而覆盖原有占位符的方向；请参见[如何针对双向文本使用 Unicode 控制符](https://www.w3.org/International/questions/qa-bidi-unicode-controls)获取更多信息。 + +> **备注：** 尽可能避免使用 `placeholder` 属性。它在语义上没有其他解释表单的方式有用，并且可能导致内容出现意外的问题。请参见 {{SectionOnPage("/zh-CN/docs/Web/HTML/Element/input", "标签与占位符")}} 以获取更多信息。 -有关详细信息和示例，请参见 [指定模式](#指定模式) 部分。 +### readonly -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "placeholder", 0, 1, 2)}} +一个布尔属性，如果存在，则表示该字段不能由用户编辑。但是，仍可以通过 JavaScript 代码直接设置 {{domxref("HTMLInputElement")}} 的 `value` 属性来更改。 -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "readonly", 0, 1, 2)}} +> **备注：** 因为只读字段不能有值，所以 `required` 对指定了 `readonly` 属性的输入没有任何影响。 -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "size", 0, 1, 2)}} +### size + +`size` 属性是一个数字值，指示输入字段应有多少个字符宽。该值必须是一个大于零的数字，默认值是 20。由于字符宽度各不相同，这可能是也可能不是精确的，不应依赖于此；结果输入可能比指定的字符数更窄或更宽，这取决于字符和字体（{{cssxref("font")}}使用中的设置）。 + +这并*不*限制用户可以在该字段中输入多少个字符，仅能指定一次可以看到多少个。要设置输入数据长度的上限，请使用 [`maxlength`](#maxlength) 属性。 ### spellcheck -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "spellcheck-include")}} +`spellcheck` 是一个全局属性，用于指示是否启用元素的拼写检查。它可以用于任何可编辑的内容，但是这里我们考虑在 {{HTMLElement("input")}} 元素上使用 `spellcheck` 的细节。 `spellcheck` 的允许值为： -## 非标准属性 +- `false` + - : 禁用此元素的拼写检查。 +- `true` + - : 对此元素启用拼写检查。 +- `""`（空字符串）或空值 + - : 遵循元素的默认行为进行拼写检查。这可能基于父元素 `spellcheck` 设置或其他因素。 + +如果输入字段没有设置 [readonly](#readonly) 属性且未禁用，则可以启用拼写检查。 -以下非标准属性可用于搜索输入字段。通常，除非没有帮助，否则应避免使用它们。 +如果{{Glossary("user agent", "用户代理的")}}首选项覆盖了设置，则通过读取 `spellcheck` 返回的值可能无法反映控件中拼写检查的实际状态。 -| 属性 | 描述 | -| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`autocorrect`](#autocorrect) | 编辑此输入字段时是否允许自动更正。**Safari only.** | -| [`incremental`](#incremental) | 是否发送重复的 {{domxref("HTMLInputElement/search_event", "search")}} 事件以允许在用户仍在编辑字段的值时更新实时搜索结果。**WebKit and Blink only (Safari, Chrome, Opera, etc.).** | -| [`mozactionhint`](#mozactionhint) | 一个字符串，指示当用户在编辑字段时按 Enter 或 Return 键时将执行的操作类型；用于确定虚拟键盘上该键的适当标签。**Firefox for Android only.** | -| [`results`](#results) | 先前搜索查询的下拉列表中应显示的最大项目数。**Safari only.** | +## 非标准属性 + +以下非标准属性在某些浏览器上对搜索输入字段也可用。一般来说，除非万不得已，否则你应该避免使用它们。 ### autocorrect -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "autocorrect-include")}} +Safari 扩展，`autocorrect` 属性是一个字符串，它指示在用户编辑此字段时是否激活自动更正。允许的值为： + +- `on` + - : 启用拼写错误的自动更正，以及配置文本替换（如果已配置）的处理。 +- `off` + - : 禁用自动更正和文本替换。 ### incremental -布尔值 `incremental` 属性是 WebKit 和 Blink 扩展（因此被 Safari, Opera, Chrome 等支持）如果存在，它会告诉 {{Glossary("user agent")}} 将输入作为实时搜索进行处理。当用户编辑字段的值时，用户代理将 {{domxref("HTMLInputElement/search_event", "search")}} 事件发送到代表搜索框的 `{{domxref("HTMLInputElement")}}` 对象。这允许您的代码在用户编辑搜索时实时更新搜索结果。 +布尔值属性 `incremental` 是 WebKit 和 Blink 的扩展（因此被 Safari、Opera、Chrome 等支持）。如果制定了它，它会告诉{{Glossary("user agent","用户代理")}}将输入作为实时搜索进行处理。当用户编辑字段的值时，用户代理将 {{domxref("HTMLInputElement/search_event", "search")}} 事件发送到代表搜索框的 {{domxref("HTMLInputElement")}} 对象。这允许你的代码在用户编辑搜索时实时更新搜索结果。 -如果 `incremental` 没有被指定，则仅当用户显式启动搜索时（例如，在编辑字段时按 Enter 或 Return ）才发送 {{domxref("HTMLInputElement/search_event", "search")}} 事件。 +如果没有指定 `incremental` ，则仅当用户显式启动搜索时（例如，在编辑字段时按 Enter 或 Return ）才发送 {{domxref("HTMLInputElement/search_event", "search")}} 事件。 `search` 事件受速率限制，因此发送事件的频率不会超过实现定义的间隔。 ### mozactionhint -{{page("/zh-CN/docs/Web/HTML/Element/input/text", "mozactionhint-include")}} +Mozilla 扩展，它提供了一个提示，提示用户在编辑字段时按 Enter 或 Return 键将采取何种操作。 + +此属性已经废弃：请使用全局属性 {{htmlattrxref("enterkeyhint")}} 作为替代。 ### results -`results` 属性是一个数字值（仅受 Safari 支持），可让您覆盖要在 `{{HTMLElement("input")}}` 元素的本机提供的先前搜索查询的下拉菜单中显示的最大条目数。 +`results` 属性是一个数字值（仅受 Safari 支持），可让你覆盖要在 {{HTMLElement("input")}} 元素原生提供的先前搜索查询的下拉菜单中所显示的最大条目数。 该值必须是非负十进制数字。如果未提供或给出了无效值，则使用浏览器的默认最大条目数。 ## 使用搜索输入 -`` 元素 `search` 类型与 `text` 类型的元素非常相似，不同之处在于它们专门用于处理搜索项。它们的行为基本相同，但是用户代理可以默认选择不同的样式（当然，站点可以使用样式表向其应用自定义样式）。 +`search` 类型的 `` 元素与 `text` 类型的元素非常相似，不同之处在于它们专门用于处理搜索条目。它们的行为基本相同，但是用户代理可以选择与默认样式不同的样式（当然，站点可以使用样式表向其应用自定义样式）。 -### 基本例子 +### 基本示例 ```html
- - + +
``` 如下： -{{EmbedLiveSample("Basic_example", 600, 40)}} +{{EmbedLiveSample("基本示例", 600, 40)}} -`q` 是搜索输入中最常用 `name` ，尽管不是强制性的。提交后，发送到服务器的键值对数据将为 `q=searchterm`。 +`q` 是搜索输入中最常用的 `name` 值，尽管不是强制性的。提交后，发送到服务器的键值对数据将为 `q=searchterm`。 -> **备注：** 你一定要记住设置 `{{htmlattrxref("name", "input")}}` 输入，否则不会提交任何内容。 +> **备注：** 一定要记住为你的 input 设置 {{htmlattrxref("name", "input")}}，否则不会提交任何内容。 ### 搜索类型和文本类型之间的差异 -主要的基本区别在于浏览器处理它们的方式。首先要注意的是，某些浏览器显示一个十字图标，如果需要，可以单击该十字图标以立即删除搜索词。以下屏幕截图来自 Chrome： +主要的基本区别在于浏览器处理它们的方式。首先要注意的是，某些浏览器显示一个十字图标，如果需要，可以单击该十字图标以立即删除搜索词。在 Chrome 中当按下 escape 键时也会触发这个动作。以下屏幕截图来自 Chrome： -![](chrome-cross-icon.png) +![Focused search input, with focus ring, with the text 'cats'. There is an x icon in the input abutting the right side.](chrome-cross-icon.png) -此外，现代浏览器还倾向于自动存储先前在各个域中输入的搜索词，然后在该域的搜索输入中执行后续搜索时，这些搜索词会作为自动完成选项出现。这有助于随着时间的流逝倾向于在相同或相似搜索查询上进行搜索的用户。此屏幕截图来自 Firefox： +此外，现代浏览器还倾向于自动存储先前在各个域中输入的搜索词，在该域的搜索输入中执行后续搜索时，这些搜索词会作为自动完成选项出现。这有助于随着时间的流逝倾向于在相同或相似搜索查询上进行搜索的用户。此屏幕截图来自 Firefox： -![](firefox-auto-complete.png)现在，让我们看看可以应用于搜索表单的一些有用的技巧。 +![An input in error state with a red focus ring. The user has entered the letter 'h'. A pop-up selection list is open directly under the input box with two options: hello and hermansje.](firefox-auto-complete.png)现在，让我们看看可以应用于搜索表单的一些有用的技巧。 ### 设置占位符 -您可以在搜索输入中提供一个有用的占位符，使用`{{htmlattrxref("placeholder","input")}}` 属性来提示要做什么。看下面的例子： +可以在搜索输入中提供一个有用的占位符，使用 {{htmlattrxref("placeholder","input")}} 属性来提示要做什么。看下面的示例： ```html
- - + +
``` -您可以在下面看到占位符的呈现方式： +可以在下面看到占位符的呈现方式： -{{EmbedLiveSample("Setting_placeholders", 600, 40)}} +{{EmbedLiveSample("设置占位符", 600, 40)}} -### 搜索表单标签和辅助功能 +### 搜索表单标签和无障碍 -搜索表单的一个问题是它们的无障碍。常见的设计惯例是不为搜索字段提供标签（尽管可能会有放大镜图标或类似图标），因为由于放置位置的原因，搜索表单的目的通常对于视力正常的用户而言相当明显（[这个例子展示了一个典型的模式](https://mdn.github.io/learning-area/accessibility/aria/website-aria-roles/)）。 +搜索表单的一个问题是它们的无障碍性。常见的设计惯例是不为搜索字段提供标签（尽管可能会有放大镜或类似图标），因为由于放置位置的原因，搜索表单的目的通常对于视力正常的用户而言相当明显（[这个例子展示了一个典型的模式](https://mdn.github.io/learning-area/accessibility/aria/website-aria-roles/)）。 -但是，这可能会使屏幕阅读器用户感到困惑，因为他们不会对搜索输入内容有任何口头指示。解决此问题而不会影响您的视觉设计的一种方法是使用 [WAI-ARIA](/zh-CN/docs/Learn/Accessibility/WAI-ARIA_basics) 功能： +但是，这可能会使屏幕阅读器用户感到困惑，因为它们不会对搜索输入内容有任何口头指示。解决此问题而不会影响您的视觉设计的一种方法是使用 [WAI-ARIA](/zh-CN/docs/Learn/Accessibility/WAI-ARIA_basics) 功能： -- `
` 元素上， `search` 值的 `role` 属性 使屏幕阅读器用户声明该表单是搜索表单。 -- 您还可以在 `{{HTMLElement("input")}}` 上使用 `aria-label` 属性。这应该是一个描述性的文本标签，屏幕阅读器会读出该标签；它用作 `