README

可访问的自动完成是一个组件，帮助用户从您提供的列表中选择答案。您还可以使用它来使用户得到的答案更加一致。

如果您要求用户提供他们的国家或地区，那么 govuk-country-and-territory-autocomplete 可能更合适。

accessible-autocomplete 是一个从头开始构建的可访问性 JavaScript 自动完成。设计目标是

• 可访问性：遵循 WAI-ARIA 最佳实践，并使用辅助技术进行测试。
• 用户体验：支持广泛的各种用户需求。
• 兼容性：与 推荐浏览器 和 辅助技术 兼容。

试试示例！

支持

GOV.UK 设计系统团队维护了可访问的自动完成作为一个独立的组件。然而，我们只能投入最少的工作来支持它。

阅读有关维护此组件的计划.

阅读有关我们可以提供的支持类型的更多信息.

安装/使用

使用 npm 和模块系统

运行以下命令来安装

npm install --save accessible-autocomplete

accessibleAutocomplete 函数将渲染一个自动完成的 <input> 以及其伴随的建议和 aria-live 区域。您的页面应提供一个 <label> 和一个容器元素

<label for="my-autocomplete">Select your country</label>
<div id="my-autocomplete-container"></div>

然后使用模块系统（如 Browserify / Webpack / Rollup）导入它，并调用 accessibleAutocomplete 函数，提供一个值数组

import accessibleAutocomplete from 'accessible-autocomplete'

const countries = [
  'France',
  'Germany',
  'United Kingdom'
]

accessibleAutocomplete({
  element: document.querySelector('#my-autocomplete-container'),
  id: 'my-autocomplete', // To match it to the existing <label>.
  source: countries
})

如果您想将其用作 <select> 元素的替代品，请阅读 渐进增强 部分。

作为纯 JavaScript 模块

您可以将 dist/accessible-autocomplete.min.js 文件复制到您的 JavaScript 文件夹中，并将其导入浏览器

<script type="text/javascript" src="assets/js/accessible-autocomplete.min.js"></script>

自动完成样式化

该包中包含一个样式表，位于 dist/accessible-autocomplete.min.css。

您可以将它复制到您的样式表文件夹中，并将其导入浏览器

<link rel="stylesheet" href="assets/css/accessible-autocomplete.min.css" />

您还可以使用 Sass 导入它

@import "accessible-autocomplete";

与 Preact 一起使用

如果您已经在您的应用程序中使用 Preact，您可以导入一个将使用它的包

import preact from 'preact'
import Autocomplete from 'accessible-autocomplete/preact'

preact.render(
  <Autocomplete id='autocomplete' source={suggest} />,
  document.querySelector('#container')
)

试试 Preact 示例！

与 React 一起使用

如果您已经在您的应用程序中使用 React，您可以导入一个将使用它的包

import React from 'react'
import ReactDOM from 'react-dom'
import Autocomplete from 'accessible-autocomplete/react'

ReactDOM.render(
  <Autocomplete id='autocomplete' source={suggest} />,
  document.querySelector('#container')
)

试试 React 示例！

React 版本

React v15.5.4 已测试与可访问自动完成一起工作 - 虽然请确保检查 记录的问题。

React v15.6.2 和 16.0 已不完全测试与可访问自动完成：尽管没有发现未记录的问题，但我们建议您在使用这些或更晚版本的 React 之前进行彻底的测试。

API 文档

必需的选项

元素

类型： HTMLElement

自动完成将被渲染的容器元素。

id

类型： string

分配给自动完成输入字段的 id，用于与 <label for=id> 一起使用。如果使用 enhanceSelectElement 则不是必需的。

来源

类型： Array | Function

当用户在输入字段中输入时用于搜索的值数组，或一个函数，该函数接收用户输入的内容并调用回调函数以显示结果。

值数组的示例

const countries = [
  'France',
  'Germany',
  'United Kingdom'
]

如果 source 是一个函数，则参数为： query: string, populateResults: Function

类似于 source 参数的 typeahead.js，建议的 backing 数据源。 query 是输入字段中输入的内容，它将回调到 populateResults，并同步返回要在菜单中显示的字符串结果数组。

简单建议引擎的示例

function suggest (query, populateResults) {
  const results = [
    'France',
    'Germany',
    'United Kingdom'
  ]
  const filteredResults = results.filter(result => result.indexOf(query) !== -1)
  populateResults(filteredResults)
}

其他选项

menuAttributes (默认： {})

类型： Object

在 menu 上设置 html 属性及其值。对于添加 aria-labelledby 并将现有标签的 id 属性值设置为，以便为辅助技术用户提供上下文非常有用。

autoselect (默认： false)

类型： Boolean

设置为 true 以在用户输入某些内容并接收到结果时突出显示第一个选项。按 enter 键将选择它。

confirmOnBlur (默认： true)

类型： Boolean

当用户在组件外部点击时，自动完成将确认当前选定的选项。设置为 false 以禁用。

cssNamespace (默认： 'autocomplete')

类型： string

使用此属性来覆盖 JavaScript 组件将使用的 BEM 块名称。您需要重写 CSS 类名称以使用指定的块名称。

defaultValue (默认： '')

类型： string

指定一个字符串以预先填充自动完成。

displayMenu (默认： 'inline')

类型： 'inline' | 'overlay'

可以设置此属性以指定菜单应出现的方式，是内联还是作为覆盖层。

minLength (默认： 0)

类型： number

在自动完成尝试建议选项之前应输入的最小字符数。当查询长度小于此值时，aria 状态区域还将向用户提供有用的文本，告诉他们应该输入更多。

name (默认： 'input-autocomplete')

类型： string

自动完成输入字段的 name，用于与父 <form> 一起使用。

onConfirm (默认： () => {})

类型： Function

参数： confirmed: Object

当用户确认一个选项时，将调用此函数，并带有他们确认的选项。

placeholder (默认： '') ⚠️ 不推荐 ⚠️

类型： string

此选项将填充输入元素的 placeholder 属性。

我们认为 占位符存在可用性问题，并且有 更好的输入占位符文本的替代方案，所以我们不推荐使用此选项。

required (默认： false)

类型： Boolean

输入字段将渲染为具有 required 属性，请参阅 W3C required 属性定义。

showAllValues (默认： false)

类型： Boolean

如果设置为true，则用户点击输入时将显示所有值。这与默认下拉列表类似，因此自动完成会渲染一个下拉箭头来传达这种行为。

showNoOptionsFound（默认：true）

类型： Boolean

当没有结果时，自动完成将显示“没有找到结果”模板。设置为false以禁用。

templates（默认：undefined）

类型

{
  inputValue: Function,
  suggestion: Function
}

该对象定义了用于显示自动完成部分的模板（函数）。

inputValue是一个接收一个参数的函数，即当前选定的建议。它返回要插入到输入中的字符串值。

suggestion是一个接收一个参数的函数，即要显示的建议。它用于渲染建议，并应返回一个可以包含HTML的字符串。

⚠️ 注意：由于此函数允许您输出任意HTML，您应该确保它是可信的，并且可访问。

如果您的模板包括具有定义的前景色或背景色的子元素，请检查它们是否在强制颜色模式下正确显示。例如，Windows高对比度模式。

dropdownArrow（默认：向下指的三角形）

类型： Function

一个函数，它接收一个具有className属性的对象（{ className: '' }），并应返回一个HTML字符串或（P）React元素。⚠️ 注意：由于此函数允许您输出任意HTML，您应该确保它是可信的，并且可访问。

国际化

tNoResults（默认：() => '没有找到结果'）

类型： Function

一个接收无参数的函数，应返回用于在下拉列表中指示没有结果的文本。

tStatusQueryTooShort（默认：(minQueryLength) => `输入${minQueryLength}个或更多字符以显示结果`）

类型： Function

一个接收一个参数的函数，该参数表示下拉列表触发所需的最小字符数，并应返回用于在辅助功能提示中指示查询太短的文本。

tStatusNoResults（默认：() => '没有搜索结果'）

类型： Function

一个接收无参数的函数，应返回用于在辅助功能提示中指示没有结果的文本。

tStatusSelectedOption（默认：(selectedOption, length, index) => `${selectedOption} ${index + 1} of ${length} is highlighted`）

类型： Function

一个接收两个参数的函数，即选定的选项和可用选项的数量，并应返回用于在辅助功能提示中指示哪个选项被选中的文本。

tStatusResults

默认

(length, contentSelectedOption) => {
  const words = {
    result: (length === 1) ? 'result' : 'results',
    is: (length === 1) ? 'is' : 'are'
  }

  return <span>{length} {words.result} {words.is} available. {contentSelectedOption}</span>
}

类型： Function

一个接收两个参数的函数，即可用选项的数量和tStatusSelectedOption的返回值，并应返回用于在辅助功能提示中指示哪些选项可用以及哪个被选中的文本。

tAssistiveHint（默认：() => '当自动完成结果可用时，使用上箭头和下箭头进行审查，并按回车键进行选择。触控设备用户，通过触控或滑动手势进行探索。'）

类型： Function

一个接收无参数的函数，应返回要分配给html input元素的aria描述的文本，通过aria-describedby属性。此文本旨在作为辅助技术用户的初始指令。当检测到用户输入时，自动删除aria-describedby属性，以减少屏幕阅读器的冗长。

渐进增强

如果您的自动完成是从一个小选项列表中选择（几百个选项），我们强烈建议您在服务器上渲染一个<select>菜单，并使用渐进增强。

如果您有以下HTML

<select id="location-picker">
  <option value="fr">France</option>
  <option value="de">Germany</option>
  <option value="gb">United Kingdom</option>
</select>

您可以使用 accessibleAutocomplete.enhanceSelectElement 函数将其增强为自动完成。

accessibleAutocomplete.enhanceSelectElement({
  selectElement: document.querySelector('#location-picker')
})

这将

• 在指定的 <select> 元素之后放置一个自动完成输入字段
• 将自动完成的 autoselect 默认设置为 true
• 将自动完成的 defaultValue 默认设置为选择框的 option[selected]
• 将自动完成的 id 默认设置为 <select> 的 id
• 将自动完成的 name 属性默认设置为 '' 以防止其在表单提交中被包含
• 将自动完成的 source 默认设置为使用现有 <option> 元素
• 使用内联 display: none 隐藏 <select>
• 将 <select> 的 id 设置为 ${id}-select 以解除与任何 <label> 的关联
• 在自动完成中确认一个值后，更新原始的 <select>

此函数接受与 accessibleAutocomplete 相同的选项，唯一的区别是它使用 selectElement 而不是 element，其中 element 需要是 HTMLSelectElement 的实例。

注意：accessibleAutocomplete.enhanceSelectElement 函数相对较轻量，并包装了 accessibleAutocomplete 的公共 API。如果您的用例不适用于上述默认值，请尝试 阅读源代码 并看看您是否可以编写自己的代码。

空选项

如果您的 <select> 元素有一个 "null" 选项（一个默认选项，没有值），则可以向 enhanceSelectElement 传递一个 defaultValue 选项，当选择此选项时将替换其标签。

使用以下 HTML

<select id="location-picker">
  <option value="">Select a country</option>
  <option value="fr">France</option>
  <option value="de">Germany</option>
  <option value="gb">United Kingdom</option>
</select>

然后传递一个 defaultValue 选项为 ''，如果选择空选项，则自动完成将留空。

accessibleAutocomplete.enhanceSelectElement({
  defaultValue: '',
  selectElement: document.querySelector('#location-picker')
})

任何空选项也将从用于填充自动完成元素 source 的选项中过滤出来。为了在自动完成中保留没有值的选项，请将 preserveNullOptions 标志传递为 true 到 enhanceSelectElement。

分析和跟踪

在自动完成的生命周期中，在输入元素上触发以下事件

• onConfirm - 当用户确认一个选项时，此函数将被调用，并带上他们选择的选项。

示例用法

accessibleAutocomplete({
  // additional options
  onConfirm: (val) => {
    track(val)
  }
})

为什么还需要另一个自动完成？

accessible-autocomplete 是在研究许多现有解决方案并创建补丁来修复用户体验或无障碍性问题后构建的。它受到了以下（以及许多其他）的启发

• ljwatson/design-patterns：优秀的无障碍体验
• corejavascript/corejs-typeahead：灵活的自动完成/建议引擎架构
• JamieAppleseed/selectToAutocomplete：易于使用

本地开发

查看 CONTRIBUTING 指南以获取说明。

如果您想帮忙并想更熟悉代码库，请从 "good for beginners" 问题开始。

许可

MIT.