@accessible-components/tag-input 中文文档教程

Question

Tag Input

用于创建标签的简单且易于访问的组件。 查看演示页面。

Features

• Tags can be added both manually and dynamically.
• Fully accessible for keyboard and assistive technologies.
• Cusomisable styles.

Browser support

所有现代浏览器。 IE11 不受支持。

Tested in

OS	Browser	Screen reader
macOS	Safari	VoiceOver
iOS	Safari	VoiceOver
Windows	Chrome	JAWS
Windows	Firefox	NVDA
Android	Chrome	Talkback

Installation

npm

npm install @accessible-components/tag-input

然后从 node_modules 导入 build/tag-input.min.js 和 build/tag-input.min.css。

Static sites

将 build/tag-input.min.js 和 build/tag-input.min.css 复制到您的项目并将它们包含在您的 HTML 中：

<link rel="stylesheet" href="./path/to/file/tag-input.min.css" />
...
<script src="./path/to/file/tag-input.min.js"></script>

Locally

git clone https://github.com/accessible-components/tag-input.git
cd tag-input/
npm install
npm start

打开 http://localhost :8080/ 在浏览器中打开演示页面。

Keyboard support

一旦专注于输入字段，可以使用以下键盘快捷键：

Shortcut	Input field	Tag selected	Action
ArrowLeft, ArrowRight	Empty	-	Navigate through tags if they exist. Selected tag is visually highlighted as well as anounced for screen reader users.
Delete	Empty	No	Deletes the last tag.
Enter	Empty	Yes	Makes selected tag editable.
ESC	Empty	Yes	Resets edited tag (before it saved) to the prevous state.
Enter, Tab	Filled	No	Creates a new tag.

Some thoughts to Backspace key

尽管许多类似的标签输入组件使用 Backspace 键删除标签（如果输入字段为空），在测试 TagInput 对于盲人用户，我们决定不支持此快捷方式，原因如下：

• 许多屏幕阅读器用户曾经关注输入字段，希望确保它是空的（通常一些示例文本已经预填）。 为此，他们不是阅读内容，而是简单地使用 Backspace 键将其删除，因此使用此键进行其他操作可能会使屏幕阅读器用户感到困惑。

• 一些盲人测试人员使用带有所谓的 Perkins 盲文键盘 的设备，其中 SwipeLeft 触发 Backspace，这可能会导致意外行为。

要删除标签，请使用 Delete 键。

Accessibility

TagInput 完全可用于键盘、屏幕阅读器和其他辅助技术。 它由每天使用这些技术的人进行测试。

Usage

创建一个空元素：

<div id="colors"></div>

创建TagInput 实例：

const colors = document.getElementById('colors');

const colorsTagInput = new TagInput(colors, {
  tags: ['red', 'green', 'blue'],
  label: 'Colors',
  placeholder: 'Add colors',
  // other options

  onTagAdd: (tag, tags) => {
    // do something
  },
  onTagRemove: (tag, tags) => {
    // do something
  },
  onTagUpdate: (oldTag, newTag, tags) => {
    // do something
  },
});

Custom styles

您可以轻松调整TagInput 样式。

要更改颜色，您可以简单地更新以下 CSS 自定义变量：

.tag-input {
  /* input */
  --text: inherit;
  --bg: #fff;
  --bg-disabled: #f9f9f9;
  --border: rgba(121, 121, 121, 0.23);
  --border-hover: rgba(121, 121, 121, 0.4);
  --border-focus: rgba(45, 146, 255, 0.7);
  --border-focus-light: rgba(190, 221, 255, 0.5);

  /* tag */
  --tag-text: #164172;
  --tag-bg: #e5f1ff;
  --tag-border: #e5f1ff;
  --tag-remove-button: transparent;
  --tag-remove-icon: #2e91fd;

  ...
}

查看 tag-input.css 中的所有 CSS 属性。

要更新其他样式（paddings、margins 等），您可以简单地覆盖 css 样式。 TagInput 具有以下 HTML 结构：

<div class="tag-input-container">
  <label class="tag-input-label">Colors</label>
  <div class="tag-input">
    <div class="tag-input__tag">
      <span class="tag-input__text">red</span> <!-- Shown -->
      <input class="tag-input__edit" /> <!-- Hidden -->
      <button class="tag-input__remove">
        <svg class="tag-input__remove-icon">...</svg>
      </button>
    </div>
    <div class="tag-input__tag tag-input__tag--editable">
      <span class="tag-input__text">green</span> <!-- Hidden -->
      <input class="tag-input__edit" /> <!-- Shown -->
      <button class="tag-input__remove">
        <svg class="tag-input__remove-icon">...</svg>
      </button>
    </div>
    <div class="tag-input__tag">
      <span class="tag-input__text">blue</span> <!-- Shown -->
      <input class="tag-input__edit" /> <!-- Hidden -->
      <button class="tag-input__remove">
        <svg class="tag-input__remove-icon">...</svg>
      </button>
    </div>
    <input class="tag-input__input" placeholder="Add colors" />
  </div>
</div>

Options

Option	Type	Default	Description
tags	String[]	[]	Tags provided on initialization.
prefix	Type	tag-input	Unique prefix for class names and IDs inside the component.
disabled	Boolean	false	disabled attribute for the input element. Also makes tags not editable.
name	String	tag-input	name atribute for the input field to be accessed on form submit.
placeholder	String	Add tags	placeholder attribute for the input element.
label	String	Tags	Label text.
hiddenLabel	Boolean	false	Hides the label visually, but keeps it accessible for screen readers.
onInit	Function	undefined	Runs after tag input init. Parameters: tags (list of tags).
onTagAdd	Function	undefined	Runs after a new tag was added. Parameters: tag (added tag), tags (list of tags after adding).
onTagUpdate	Function	undefined	Runs after a tag was updated. Parameters: oldTag (a tag before update), newTag (a tag after update), tags (list of tags after updating).
onTagRemove	Function	undefined	Runs after a tag was removed. Parameters: tag (removed tag), tags (list of tags after removing).
ariaTag	String	Tag {{TAG}}.	Adds aria-label to the tag element.
ariaEditTag	String	Edit tag.	Adds label text to the editable tag.
ariaDeleteTag	String	Delete tag {{TAG}}.	Adds aria-label to the tag delete button.
ariaTagAdded	String	Tag {{TAG}} added.	Will be pronounced to screen reader users after a new tag was created.
ariaTagUpdated	String	Tag updated to {{TAG}}.	Will be pronounced to screen reader users after a tag was updated.
ariaTagDeleted	String	Tag {{TAG}} deleted.	Will be pronounced to screen reader users after a tag was deleted.
ariaTagSelected	String	Tag {{TAG}} selected. Press enter to edit, delete to delete.	Will be pronounced to screen reader users after a tag was selected (by bavigating with arrow keys).
ariaNoTagsSelected	String	No tags selected.	Will be pronounced to screen reader users after a selected tag was unselected (by clicking on ESC key, for example).
ariaInputLabel	String	{{TAGS}} tags. Use left and right arrow keys to navigate, enter or tab to create, delete to delete tags.	Will be pronounced to screen reader users once the input element is focused.

带有前缀 aria 的选项将 ARIA 属性添加到某些元素，并为屏幕阅读器用户提供说明和其他有价值的信息。 ARIA 文本不可见。

请保持 {{TAG}} 或 {{TAGS}} 等占位符文本不变。 它将被替换为适当的文本。

Methods

Method	Argument	Return	Description
addTag	String	undefined	Adds a new tag. No duplicates allowed.
removeTag	String	undefined	Removes a tag if it exists.
getTags	-	String[]	Gets the tag array.

Contributing

欢迎大家贡献。

• If you found a bug or have an idea how to improve the component, please submit an issue.
• You may test our component on different devices and give us your feedback.

Ideas for the next features

• Min/max tags specified vis options.
• Custom tag validation before addTag
• Tag autocomplete
• Custome remove tag icon provided via options.
• Translate ARIA and other text and provide downloadable JSON files with translations.

License

麻省理工学院