# @formio/choices\.js 中文文档

规范地址：https://npmcn.com/package/%40formio/choices.js/

版本：11\.0\.3
npm 元数据更新时间：2025-08-29T19:58:57.055Z
中文译文更新时间：2026-11-15T09:02:59.111Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40formio/choices.js
原文对照：https://npmcn.com/package/%40formio/choices.js/?lang=original
项目主页：https://github.com/jshjohnson/Choices#readme
源码仓库：https://github.com/jshjohnson/Choices

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，122 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-04-19T17:48:22.928Z
- 最新版本发布：2025-08-29T19:58:56.710Z
- 近 30 天下载量：207953（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

香草 JS 可自定义文本输入/ 选择框插件

## 安装

```sh
npm install @formio/choices.js
```

也可以使用：`pnpm add @formio/choices.js`、`yarn add @formio/choices.js`、`bun add @formio/choices.js`

## README

# 选择.js [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Build%20and%20test/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Bundle%20size%20checks/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![npm](https://img.shields.io/npm/v/choices.js.svg)](https://www.npmjs.com/package/choices.js)

一个香草,轻量级(~20kb gzipped QQ),可配置的选择框/文本输入插件. 类似于 Celect2 并选择大小,但不依赖 jQuery .

[演示](https://choices-js.github.io/Choices/)

## TL; DR 数据

-   轻巧
-   没有 j 查询依赖性
-   可配置排序
-   弹性样式
-   快速搜索/过滤
-   清洁 API
-   从右到左支持
-   自定义模板

* * *

### 有兴趣写自己的 ES6 JavaScript 插件吗 ? 检查出来 [ES6.io (英语)](https://es6.io/friend/JOHNSON) {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}对伟大的教程来说

### 发起人:

[![Sufficient Velocity](https://forums.sufficientvelocity.com/data/assets/static_light_logo.svg)](https://forums.sufficientvelocity.com/)

[![Wanderer Maps logo](https://cdn.shopify.com/s/files/1/0614/3357/7715/files/Logo_BlackWithBackground_200x.png?v=1644802773)](https://wanderermaps.com/)

* * *

## 目录

-   [安装](https://npmcn.com/package/%40formio/choices.js/#readme-installation)
-   [设置](https://npmcn.com/package/%40formio/choices.js/#readme-setup)
-   [术语](https://npmcn.com/package/%40formio/choices.js/#readme-terminology)
-   [输入类型](https://npmcn.com/package/%40formio/choices.js/#readme-input-types)
-   [配置选项](https://npmcn.com/package/%40formio/choices.js/#readme-configuration-options)
-   [回电](https://npmcn.com/package/%40formio/choices.js/#readme-callbacks)
-   [活动](https://npmcn.com/package/%40formio/choices.js/#readme-events)
-   [方法](https://npmcn.com/package/%40formio/choices.js/#readme-methods)
-   [发展](https://npmcn.com/package/%40formio/choices.js/#readme-development)
-   [许可证](https://npmcn.com/package/%40formio/choices.js/#readme-license)

## 安装

与 [国家预防机制](https://www.npmjs.com/package/choices.js)数字 :

```zsh
npm install choices.js
```

与 [雅伦](https://yarnpkg.com/)数字 :

```zsh
yarn add choices.js
```

从a [光盘N](https://www.jsdelivr.com/package/npm/choices.js)数字 :

**说明:** 在CDN上反映最新版本"Choices"时有时会出现延迟.

```html
<!-- Include base CSS (optional) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js/public/assets/styles/base.min.css"
/>
<!-- Or versioned -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js@9.0.1/public/assets/styles/base.min.css"
/>

<!-- Include Choices CSS -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js/public/assets/styles/choices.min.css"
/>
<!-- Or versioned -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js@9.0.1/public/assets/styles/choices.min.css"
/>

<!-- Include Choices JavaScript (latest) -->
<script src="https://cdn.jsdelivr.net/npm/choices.js/public/assets/scripts/choices.min.js"></script>
<!-- Or versioned -->
<script src="https://cdn.jsdelivr.net/npm/choices.js@9.0.1/public/assets/scripts/choices.min.js"></script>
```

或者直接包括选择:

```html
<!-- Include base CSS (optional) -->
<link rel="stylesheet" href="public/assets/styles/base.min.css" />
<!-- Include Choices CSS -->
<link rel="stylesheet" href="public/assets/styles/choices.min.css" />
<!-- Include Choices JavaScript -->
<script src="/public/assets/scripts/choices.min.js"></script>
```

### 支助科/支助科

使用 `import` cs/css由网页包支持.

在.css中:

```scss
@import "choices.js/src/styles/choices";
```

在.js/.ts中:

```javascript
import "choices.js/public/assets/styles/choices.css";
```

## 设置

**说明:** 如果您通过了针对多个元素的选择器,则将使用第一个匹配元素。 8.x.x之前的版本会返回多个选择例.

```js
  // Pass single element
  const element = document.querySelector('.js-choice');
  const choices = new Choices(element);

  // Pass reference
  const choices = new Choices('[data-trigger]');
  const choices = new Choices('.js-choice');

  // Pass jQuery element
  const choices = new Choices($('.js-choice')[0]);

  // Passing options (with default options)
  const choices = new Choices(element, {
    silent: false,
    items: [],
    choices: [],
    renderChoiceLimit: -1,
    maxItemCount: -1,
    closeDropdownOnSelect: 'auto',
    singleModeForMultiSelect: false,
    addChoices: false,
    addItems: true,
    addItemFilter: (value) => !!value && value !== '',
    removeItems: true,
    removeItemButton: false,
    removeItemButtonAlignLeft: false,
    editItems: false,
    allowHTML: false,
    allowHtmlUserInput: false,
    duplicateItemsAllowed: true,
    delimiter: ',',
    paste: true,
    searchEnabled: true,
    searchChoices: true,
    searchFloor: 1,
    searchResultLimit: 4,
    searchFields: ['label', 'value'],
    position: 'auto',
    resetScrollPosition: true,
    shouldSort: true,
    shouldSortItems: false,
    sorter: () => {...},
    shadowRoot: null,
    placeholder: true,
    placeholderValue: null,
    searchPlaceholderValue: null,
    prependValue: null,
    appendValue: null,
    renderSelectedChoices: 'auto',
    loadingText: 'Loading...',
    noResultsText: 'No results found',
    noChoicesText: 'No choices to choose from',
    itemSelectText: 'Press to select',
    uniqueItemText: 'Only unique values can be added',
    customAddItemText: 'Only values matching specific conditions can be added',
    addItemText: (value) => {
      return `Press Enter to add <b>"${value}"</b>`;
    },
    removeItemIconText: () => `Remove item`,
    removeItemLabelText: (value) => `Remove item: ${value}`,
    maxItemText: (maxItemCount) => {
      return `Only ${maxItemCount} values can be added`;
    },
    valueComparer: (value1, value2) => {
      return value1 === value2;
    },
    classNames: {
      containerOuter: ['choices'],
      containerInner: ['choices__inner'],
      input: ['choices__input'],
      inputCloned: ['choices__input--cloned'],
      list: ['choices__list'],
      listItems: ['choices__list--multiple'],
      listSingle: ['choices__list--single'],
      listDropdown: ['choices__list--dropdown'],
      item: ['choices__item'],
      itemSelectable: ['choices__item--selectable'],
      itemDisabled: ['choices__item--disabled'],
      itemChoice: ['choices__item--choice'],
      description: ['choices__description'],
      placeholder: ['choices__placeholder'],
      group: ['choices__group'],
      groupHeading: ['choices__heading'],
      button: ['choices__button'],
      activeState: ['is-active'],
      focusState: ['is-focused'],
      openState: ['is-open'],
      disabledState: ['is-disabled'],
      highlightedState: ['is-highlighted'],
      selectedState: ['is-selected'],
      flippedState: ['is-flipped'],
      loadingState: ['is-loading'],
      notice: ['choices__notice'],
      addChoice: ['choices__item--selectable', 'add-choice'],
      noResults: ['has-no-results'],
      noChoices: ['has-no-choices'],
    },
    // Choices uses the great Fuse library for searching. You
    // can find more options here: https://fusejs.io/api/options.html
    fuseOptions: {
      includeScore: true
    },
    labelId: '',
    callbackOnInit: null,
    callbackOnCreateTemplates: null,
    appendGroupInSearch: false,
  });
```

## 术语

| 单词 | 定义 |
| --- | --- |
| 选择 | 一个选择是用户可以选择的值. 选择相当于 `<option></option>` 选定输入中的元素. |
| 组 | 一个团体是一个选择的集合。 应将一个集团视为相当于 `<optgroup></optgroup>` 选定输入中的元素. |
| 项目 | 项目是输入值(文本输入)或选定的选择(选择元素)。 在选定要素中,项目相当于选定选项要素: `<option value="Hello" selected></option>` 在文本输入中,项目相当于 `<input type="text" value="Hello">` |

## 输入类型

选择与以下输入类型有关,如上所注,参考文件.

| HTML 元素 | 文档“输入类型” |
| --- | --- |
| [`<input type="text">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) | `text` |
| [`<select>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) | `select-one` |
| [`<select multiple>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple) | `select-multiple` |

## 配置选项

### 无声

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 可选地压制控制台错误和警告.

### 项目

**类型 :** `Array` **默认 :** `[]`

**受影响的输入类型:** `text`

**用法 :** 在文本输入中添加预选项目(见术语).

通过一系列字符串 :

`['value 1', 'value 2', 'value 3']`

通过一系列对象 :

```
[{
  value: 'Value 1',
  label: 'Label 1',
  id: 1
},
{
  value: 'Value 2',
  label: 'Label 2',
  id: 2,
  customProperties: {
    random: 'I am a custom property'
  }
}]
```

### 选择

**类型 :** `Array` **默认 :** `[]`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 添加选择( 见名词) 来选择输入 .

通过一系列对象 :

```
[{
  value: 'Option 1',
  label: 'Option 1',
  selected: true,
  disabled: false,
},
{
  value: 'Option 2',
  label: 'Option 2',
  selected: false,
  disabled: true,
  customProperties: {
    description: 'Custom description about Option 2',
    random: 'Another random custom property'
  },
},
{
  label: 'Group 1',
  choices: [{
    value: 'Option 3',
    label: 'Option 4',
    selected: true,
    disabled: false,
  },
  {
    value: 'Option 2',
    label: 'Option 2',
    selected: false,
    disabled: true,
    customProperties: {
      description: 'Custom description about Option 2',
      random: 'Another random custom property'
    }
  }]
}]
```

### 选择限制

**类型 :** `Number` **默认 :** `-1`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 在下拉列表("-1")中要作出的选择数量表示没有限制. 如果您有许多选择, 用户可以更容易地使用搜索区域来找到选择, 这将会很有用 .

### 最大项目

**类型 :** `Number` **默认 :** `-1`

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 用户可以输入/选择的项目数量 ("-1") 表示没有限制.

### 关闭 Dropdown 选择

**类型 :** `Boolean` "自动" **默认 :** `auto`

**受影响的输入类型:** 选择一个, 选择多个

**用法 :** 控制下拉在选择选取一或选取多部分后如何关闭 .

-   基于备份元素类型的自动默认值 :
-   选择一:真实
-   选择- 复数: 假

### 单模式多功能选择

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** 选择一个, 选择多个

**用法 :** 以最大项数为1的选定复数, 类似于选定复数。 选择一个项目会自动关闭下拉, 并将任何已有项目交换到刚刚选中的选择 。 如果应用到选取一,则其功能为上而不是标准选取一.

### 添加选择

**类型**数字 : `Boolean` **默认 :** `false`

**受影响的输入类型:** `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 用户是否可以动态添加选择 .

**说明:** `addItems` 也必须是 `true`

### 添加项目

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `text`

**用法 :** 用户是否可以添加项目 .

### 删除项目

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 用户是否可以删除项目 .

### 删除项目按钮

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 每个项目是否应该有一个删除按钮 .

### 删除项目按钮对齐

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 对齐项去掉左键对右键

### 编辑项目

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`

**用法 :** 用户是否可以编辑项目 。 一个项的值可以通过按后空格来编辑 .

### 允许 HTML

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 是否在所有选择元素中提供 HTML 。 若为 `false`,所有元素(占位符、项目等)将被视为纯文本。 若为 `true`,这可用于执行 XSS 脚本攻击,如果您从远程源装入选择.

### 允许 Html 用户输入

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** HTML 是否在输入时被忽略 `addItems` 或者说 `addChoices` 这是真的。 若为 `false`,用户输入将被视为纯文本。 若为 `true`,这可用于执行 XSS 脚本攻击,如果您从远程源装入选择.

### 重复项目

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `text`

**用法 :** 是否允许重复输入/选择项目

### 分隔符

**类型 :** `String` **默认 :** `,`

**受影响的输入类型:** `text`

**用法 :** 何为分出各值. 默认分隔符用逗号分隔每个值: `"Value 1, Value 2, Value 3"`。 。 。 .

### 粘贴

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 用户是否可以粘贴到输入中 .

### 搜索已启用

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 是否显示搜索区域 .

### 搜索选择

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `select-one`

**用法 :** 是否应该通过输入过滤选择 。 若为 `false`,搜索事件仍然会发出,但选择不会被过滤.

### 搜索字段

**类型 :** `Array/String` **默认 :** `['label', 'value']`

**受影响的输入类型:**`select-one`, (中文(简体) ), `select-multiple`

**用法 :** 指定用户搜索时应当使用的字段。 如果您在选择中添加了自定义属性, 您可以添加这些值 : `['label', 'value', 'customProperties.example']`。 。 。 .

### 搜索文件夹

**类型 :** `Number` **默认 :** `1`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 搜索值在搜索选择之前的最小长度 .

### 搜索结果链接: 4,

**类型 :** `Number` **默认 :** `4`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 显示("-1")的最大搜索结果量表示无限制.

### 阴影旋转

**类型 :** 文档元素 **默认 :** 无效

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 你可以像这样从申请中传出阴影路.

```js
var shadowRoot = document
  .getElementById('wrapper')
  .attachShadow({ mode: 'open' });
...
var el = shadowRoot.querySelector(...);
var choices = new Choices(el, {
  shadowRoot: shadowRoot,
});
```

### 职位

**类型 :** `String` **默认 :** `auto`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 是否应当在上方显示下降(`top`)或以下(中文(简体))`bottom`)输入. 默认情况下,如果窗口内空间不足,下拉会出现在输入上方,否则会出现在下.

### 重置滚动位置

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `select-multiple`

**用法 :** 是否在添加项目后重置滚动位置 .

### 添加项目过滤器

**类型 :** `string | RegExp | Function` **默认 :** `null`

**受影响的输入类型:** `text`

**用法 :** 需要返回的 RegExp 或字符串( 将在内部传递给 RegExp 构造器) 或过滤器功能 `true` 用于用户成功添加项目.

**示例**

```js
// Only adds items matching the text test
new Choices(element, {
  addItemFilter: (value) => {
    return ['orange', 'apple', 'banana'].includes(value);
  };
});

// only items ending to `-red`
new Choices(element, {
  addItemFilter: '-red$';
});

```

### 应索特

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 是否应该对选择和群体进行排序。 如果错误,选择/组会按照给出的顺序出现.

### 应保存项目

**类型 :** `Boolean` **默认 :** `false`

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 是否应排序项目 。 如果错误, 将按所选顺序显示项目 .

### 排序器

**类型 :** `Function` **默认 :** 分类

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 选择和项目显示前排序的函数( 除非用户正在搜索) 。 默认选择和项目按字母顺序排序.

**示例**

```js
// Sorting via length of label from largest to smallest
const example = new Choices(element, {
  sorter: function(a, b) {
    return b.label.length - a.label.length;
  },
};
```

### 占位符

**类型 :** `Boolean` **默认 :** `true`

**受影响的输入类型:** `text`

**用法 :** 输入是否显示占位符 。 与 `placeholderValue`如果 `placeholder` 被设定为真实,没有向 `placeholderValue`,通过输入的占位符属性将用作占位符值.

**说明:** 对于选定的框,建议添加占位符的方式如下:

```html
<select data-placeholder="This is a placeholder">
  <option>...</option>
  <option>...</option>
  <option>...</option>
</select>
```

对于后向兼容, `<option value="">This is a placeholder</option>` 财务报告和审定财务报表 `<option placeholder>This is a placeholder</option>` 也得到支持.

### 占位符数值

**类型 :** `String` **默认 :** `null`

**受影响的输入类型:** `text`

**用法 :** 输入占位符的值 .

### 搜索 Placeholders 数值

**类型 :** `String` **默认 :** `null`

**受影响的输入类型:** `select-one`

**用法 :** 搜索输入占位符的值 .

### 预加值

**类型 :** `String` **默认 :** `null`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 在每个添加/选择的项目上预置一个值.

### 附录

**类型 :** `String` **默认 :** `null`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 在每个添加/选中的项目上添加一个值.

### 选定选择

**类型 :** `String` **默认 :** `auto`

**受影响的输入类型:** `select-multiple`

**用法 :** 是否应当从列表中删除选定的选择 。 默认选择在多个选择框中选择时被删除。 总是让选择通过 `always`。 。 。 .

### 装入文本

**类型 :** `String` **默认 :** `Loading...`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 选择时通过AJAX显示的文本.

### 无结果文本

**类型 :** `String/Function` **默认 :** `No results found`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 用户搜索未返回结果时显示的文本 。 可选通过函数返回字符串 .

### 无选择图文

**类型 :** `String/Function` **默认 :** `No choices to choose from`

**受影响的输入类型:** `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 当用户选择了所有可能的选项, 或者不存在选项时显示的文本 。 可选通过函数返回字符串 .

### 项目选择文本

**类型 :** `String` **默认 :** `Press to select`

**受影响的输入类型:** `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 当用户在可选择的选择上徘徊时显示的文本 。 设置为空, 不为此文本保留空格 .

### 添加项目文本

**类型 :** `String/Function` **默认 :** `Press Enter to add "${value}"`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 用户输入新项目但未按下输入键时显示的文本 。 要访问当前输入值,请通过一个带有 `value` 参数(见 [默认配置](https://github.com/jshjohnson/Choices#setup) ,或者通过字符串.

返回类型必须安全地插入到 HTML( 使用 sanitied 第 1 个参数)

### 删除项目IconText

**类型 :** `String/Function` **默认 :** `Remove item"`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 删除按钮的文本/icon 。 要访问项目值, 请通过一个带有 `value` 参数(见 **默认配置** \[[https://github.com/jshjohnson/Choices#设置](https://github.com/jshjohnson/Choices#setup)举例来说),否则会传递一个字符串.

返回类型必须安全地插入到 HTML( 使用 sanitied 第 1 个参数)

### 删除项目标签文本

**类型 :** `String/Function` **默认 :** `Remove item: ${value}"`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 删除按钮的文本是 aria 标签 。 要访问项目值, 请通过一个带有 `value` 参数(见 **默认配置** \[[https://github.com/jshjohnson/Choices#设置](https://github.com/jshjohnson/Choices#setup)举例来说),否则会传递一个字符串.

返回类型必须安全地插入到 HTML( 使用 sanitied 第 1 个参数)

### 最大项目文本

**类型 :** `String/Function` **默认 :** `Only ${maxItemCount} values can be added`

**受影响的输入类型:** `text`

**用法 :** 当用户关注输入但已经到达时显示的文本 [最大项数](https://github.com/jshjohnson/Choices#maxitemcount)。要访问最大项数,请通过一个函数 `maxItemCount` 参数(见 [默认配置](https://github.com/jshjohnson/Choices#setup) ,或者通过字符串.

### 数值

**类型 :** `Function` **默认 :** `strict equality`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 按值查找选择时使用的自定义函数比较( 使用 `setChoiceByValue`) (中文(简体) ).

**示例**

```js
const example = new Choices(element, {
  valueComparer: (a, b) => value.trim() === b.trim(),
};
```

### 标签编号

**类型 :** `String` **默认 :** \`\`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 标签可以改善无障碍性。 如果设定了, 它会在选择元素中添加 aria- labledby .

### 类名

**类型 :** `Object` **默认 :**

```
classNames: {
  containerOuter: ['choices'],
  containerInner: ['choices__inner'],
  input: ['choices__input'],
  inputCloned: ['choices__input--cloned'],
  list: ['choices__list'],
  listItems: ['choices__list--multiple'],
  listSingle: ['choices__list--single'],
  listDropdown: ['choices__list--dropdown'],
  item: ['choices__item'],
  itemSelectable: ['choices__item--selectable'],
  itemDisabled: ['choices__item--disabled'],
  itemChoice: ['choices__item--choice'],
  description: ['choices__description'],
  placeholder: ['choices__placeholder'],
  group: ['choices__group'],
  groupHeading: ['choices__heading'],
  button: ['choices__button'],
  activeState: ['is-active'],
  focusState: ['is-focused'],
  openState: ['is-open'],
  disabledState: ['is-disabled'],
  highlightedState: ['is-highlighted'],
  selectedState: ['is-selected'],
  flippedState: ['is-flipped'],
  loadingState: ['is-loading'],
  notice: ['choices__notice'],
  addChoice: ['choices__item--selectable', 'add-choice'],
  noResults: ['has-no-results'],
  noChoices: ['has-no-choices'],
}
```

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 由 Choices 生成的添加到 HTML 中的类. 默认类名跟随 [贝姆](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) 标注.

## 回电

**说明:** 每一次回电, `this` 指当前选择的例子。 如果您需要获得方法(`this.disable()`)或配置对象(`this.config`) (中文(简体) ).

### 在Init上调用

**类型 :** `Function` **默认 :** `null`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 功能一旦选中便运行 .

### 召回 CreateTemplates( StretToEl : (stry: string) QQ HTML Element, executForTemplate :(ALLHTML : boolean, s: String Unliced QQ String PreEscoped QQQ 字符串) QQ 字符串, 获得Class 名:(s: Array QQ 字符串) XQ 字符串

**类型 :** `Function` **默认 :** `null` **参数 :** `strToEl`, (中文(简体) ), `escapeForTemplate`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 要运行在模板创建上的函数 。 通过这种回调,可以提供Choices各个组件的自定义模板(见术语). 选择要使用自定义模板, 您必须维护定义的各种数据属性 [这里](https://github.com/Choices-js/Choices/blob/master/src/scripts/templates.ts)。 。 。 . 如果您想要扩展一点原始模板, 您可以使用 `Choices.defaults.templates` 访问 原始模板函数.

模板接收全部选择配置作为任意模板的第一个参数,这使得您可以根据指定的选项有条件地显示事物.

@ 注释 每一次回电, `this` 指当前选择的例子。 如果您需要访问方法, 这可能有用 `(this.disable())`。 。 。 .

**示例**

```js
const example = new Choices(element, {
  callbackOnCreateTemplates: (strToEl, escapeForTemplate, getClassNames) => ({
    input: (...args) =>
      Object.assign(Choices.defaults.templates.input.call(this, ...args), {
        type: 'email',
      }),
  }),
});
```

或更复杂的:

```js
const example = new Choices(element, {
  callbackOnCreateTemplates: function(strToEl, escapeForTemplate, getClassNames) {
    return {
      item: ({ classNames }, data) => {
        return template(`
          <div class="${getClassNames(classNames.item).join(' ')} ${
          getClassNames(data.highlighted
            ? classNames.highlightedState
            : classNames.itemSelectable).join(' ')
        } ${
          data.placeholder ? classNames.placeholder : ''
        }" data-item data-id="${data.id}" data-value="${escapeForTemplate(data.value)}" ${
          data.active ? 'aria-selected="true"' : ''
        } ${data.disabled ? 'aria-disabled="true"' : ''}>
            <span>&bigstar;</span> ${escapeForTemplate(data.label)}
          </div>
        `);
      },
      choice: ({ classNames }, data) => {
        return template(`
          <div class="${getClassNames(classNames.item).join(' ')} ${getClassNames(classNames.itemChoice).join(' ')} ${
          getClassNames(data.disabled ? classNames.itemDisabled : classNames.itemSelectable).join(' ')
        }" data-select-text="${this.config.itemSelectText}" data-choice ${
          data.disabled
            ? 'data-choice-disabled aria-disabled="true"'
            : 'data-choice-selectable'
        } data-id="${data.id}" data-value="${escapeForTemplate(data.value)}" ${
          data.groupId > 0 ? 'role="treeitem"' : 'role="option"'
        }>
            <span>&bigstar;</span> ${escapeForTemplate(data.label)}
          </div>
        `);
      },
    };
  },
});
```

## 活动

**说明:** Choices发射的事件行为与标准事件相同. 每个事件在传递给Choices的元素上被触发(可通过 `this.passedElement`参数可在 `event.detail` 对象.

**示例**

```js
const element = document.getElementById('example');
const example = new Choices(element);

element.addEventListener(
  'addItem',
  function(event) {
    // do something creative here...
    console.log(event.detail.id);
    console.log(event.detail.value);
    console.log(event.detail.label);
    console.log(event.detail.customProperties);
    console.log(event.detail.groupValue);
  },
  false,
);

// or
const example = new Choices(document.getElementById('example'));

example.passedElement.element.addEventListener(
  'addItem',
  function(event) {
    // do something creative here...
    console.log(event.detail.id);
    console.log(event.detail.value);
    console.log(event.detail.label);
    console.log(event.detail.customProperties);
    console.log(event.detail.groupValue);
  },
  false,
);
```

### 添加项目

**有效载荷 :** `id, highlighted, labelClass, labelDescription, customProperties, disabled, active, label, placeholder, value, groupValue, element, keyCode`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 每次添加一个项目(按程序或用户)时触发.

### 删除项目

**有效载荷 :** `id, highlighted, labelClass, labelDescription, customProperties, disabled, active, label, placeholder, value, groupValue, element, keyCode`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 每次删除某个项目(程序或用户)时都会触发.

### 突出显示项目

**有效载荷 :** `id, highlighted, labelClass, labelDescription, customProperties, disabled, active, label, placeholder, value, groupValue, element, keyCode`

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 每次突出显示项目时触发 .

### 未突出显示项目

**有效载荷 :** `id, highlighted, labelClass, labelDescription, customProperties, disabled, active, label, placeholder, value, groupValue, element, keyCode`

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 每次项目未突出时触发 .

### 选择

**有效载荷 :** `id, highlighted, labelClass, labelDescription, customProperties, disabled, active, label, placeholder, value, groupValue, element, keyCode`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 每次选择时触发 **用户**,无论是否改变输入值. `choice` 这里是一个选择对象(参见术语或打字文件)

### 变动

**有效载荷 :** `value: string`

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 每次添加/删除项目时触发 **用户**。 。 。 .

### 搜索

**有效载荷 :** `value: string`, (中文(简体) ), `resultCount: number`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 当一个用户输入一个输入来搜索选择时触发. 当搜索结束时,会触发一个没有结果的空值的搜索事件.

### 显示向下

**有效载荷 :** - 说吧

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 显示下拉时触发 .

### 隐藏向下

**有效载荷 :** - 说吧

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 倒地被隐藏时触发.

### 突出显示选择

**有效载荷 :** `el`

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 当突出显示从下降中选择时触发 . 这个 `el` 参数是选项。通过已受影响的元素对象.

## 方法

方法可以直接取名,也可以用链条取名:

```js
// Calling a method by chaining
const choices = new Choices(element, {
  addItems: false,
  removeItems: false,
})
  .setValue(['Set value 1', 'Set value 2'])
  .disable();

// Calling a method directly
const choices = new Choices(element, {
  addItems: false,
  removeItems: false,
});

choices.setValue(['Set value 1', 'Set value 2']);
choices.disable();
```

### 销毁( c) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 关闭“ Choices” 实例,删除所有事件听众,并将输入返回初始状态.

### 输入( i) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 创建新“选择”实例,添加事件倾听器,创建模板,并使“选择”元素成为DOM.

**说明:** 这在创建新的选择实例时被隐含地称为"选择". 在“选择”实例已被销毁(使用 `destroy()`) (中文(简体) ).

### 刷新( 用Events: boolean = false, 选择 First option: boolean = false) ;

**受影响的输入类型:** `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 从备份读取选项 `<select>` 元素,并重新创建选择。 现有物品得到保存。 何时 `withEvents` 只有事实 `addItem` 生成事件.

### 突出显示全部( E) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 突出显示每个选中的项目( 可以删除选中的项目) .

### 全部取消突出显示( I) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 未突出显示每个选中的项目 .

### 删除活动项目ByValue( 值: 字符串);

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 以给定值删除每个项目.

### 删除活动项目( 不包括? : 数目);

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 删除每个可选项目.

## 删除选择( 值: 字符串 ) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`, (中文(简体) ), `select-one`

**用法 :** 按数值删除一个选项/项目

### 删除突出的项目( 运行事件 ?: 布尔) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-multiple`

**用法 :** 删除用户选择的每个项目 .

### 显示 Dropdown( 预防输入焦点 ? : 布尔) ;

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 显示列表下拉 .

### 隐藏 Dropdown( 预防输入焦点 ? : 布尔) ;

**受影响的输入类型:** 选择一个`,` 选择-多

**用法 :** 隐藏选项列表下拉 .

### setChoices(选择)Array OrFatcher ? : (输入选择 QQ输入组) \[(选择 : 选择 ) \[(选择 QQ输入组) \[\] , 值 : 字符串 : 无效, 标签 : 字符串, 替换选择 ? : 布尔 : 此承诺 ;

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 通过一系列对象(或返回对象的数组或承诺的函数)、一个值字段名称和一个标签字段名称来设定选择的输入.

这表现得类似于通过 `choices` 选项,但可以在初始化选择后调用。 也可以用于添加选择的组合(例3); 可选通过一个真 `replaceChoices` 以删除任何现有选择。 可选通过 a `customProperties` 对象将添加到您的选择中(在搜索/过滤等时有用)。 通过一个空数组作为第一个参数和一个真数 `replaceChoices` 跟打电话一样 `clearChoices` (见下文).

**示例1:**

```js
const example = new Choices(element);

example.setChoices(
  [
    { value: 'One', label: 'Label One', disabled: true },
    { value: 'Two', label: 'Label Two', selected: true },
    { value: 'Three', label: 'Label Three' },
  ],
  'value',
  'label',
  false,
);
```

**实例2:**

```js
const example = new Choices(element);

// Passing a function that returns Promise of choices
example.setChoices(async () => {
  try {
    const items = await fetch('/items');
    return items.json();
  } catch (err) {
    console.error(err);
  }
});
```

**实例3:**

```js
const example = new Choices(element);

example.setChoices(
  [
    {
      label: 'Group one',
      disabled: false,
      choices: [
        { value: 'Child One', label: 'Child One', selected: true },
        { value: 'Child Two', label: 'Child Two', disabled: true },
        { value: 'Child Three', label: 'Child Three' },
      ],
    },
    {
      label: 'Group two',
      disabled: false,
      choices: [
        { value: 'Child Four', label: 'Child Four', disabled: true },
        { value: 'Child Five', label: 'Child Five' },
        {
          value: 'Child Six',
          label: 'Child Six',
          customProperties: {
            description: 'Custom description about child six',
            random: 'Another random custom property',
          },
        },
      ],
    },
  ],
  'value',
  'label',
  false,
);
```

### 清除选择( C) ;

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 从选中清除所有选项 。 对 **没有** 重设搜索状态.

### 获得Value( 仅值 ?: boolean): 字符串 \[\] QQ事件选择 \[\] QQ事件选择 ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 获取输入值( 即输入项( 文本) 或选择( 选择) ) 。 可选通过一个论点: `true` 只返回值,而不是值对象.

**示例**

```js
const example = new Choices(element);
const values = example.getValue(true); // returns ['value 1', 'value 2'];
const valueArray = example.getValue(); // returns [{ active: true, choiceId: 1, highlighted: false, id: 1, label: 'Label 1', value: 'Value 1'},  { active: true, choiceId: 2, highlighted: false, id: 2, label: 'Label 2', value: 'Value 2'}];
```

### 设置Value( 项: 字符串\[ \] Q输入选择\[ \] : 此;

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 基于一系列对象或字符串设定输入值。 这与通过 `items` 选项,但可以在初始化选择后调用.

**示例**

```js
const example = new Choices(element);

// via an array of objects
example.setValue([
  { value: 'One', label: 'Label One' },
  { value: 'Two', label: 'Label Two' },
  { value: 'Three', label: 'Label Three' },
]);

// or via an array of strings
example.setValue(['Four', 'Five', 'Six']);
```

### 设置 ChoiceByValue( 值: 字符串 QQ字符串 \[\] );

**受影响的输入类型:** `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 根据现有的选择设置输入值. `value` 可以是单个字符串,也可以是一系列字符串

**示例**

```js
const example = new Choices(element, {
  choices: [
    { value: 'One', label: 'Label One' },
    { value: 'Two', label: 'Label Two', disabled: true },
    { value: 'Three', label: 'Label Three' },
  ],
});

example.setChoiceByValue('Two'); // Choice with value of 'Two' has now been selected.
```

### 清除Store( );

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 删除所有项目、选择和组。 恢复搜索状态 。 谨慎使用.

### 清除输入( I) ;

**受影响的输入类型:** `text`

**用法 :** 明确输入任何用户输入的文本 .

### 禁用( t) ;

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 禁用输入接受新值/ 选择更多选择 .

### 启用( );

**受影响的输入类型:** `text`, (中文(简体) ), `select-one`, (中文(简体) ), `select-multiple`

**用法 :** 允许输入接受新值/选择进一步选择 .

## 浏览器兼容性

选择使用 [宝贝](https://babeljs.io/) 目标浏览器 [全球使用量的1%以上](https://github.com/jshjohnson/Choices/blob/master/.browserslistrc) 并期望这一特点 [名单如下:](https://github.com/jshjohnson/Choices/blob/master/.eslintrc.json#L62) 在浏览器中可用或多填充. 您可以通过运行查看目标浏览器的确切列表 `npm exec browserslist` 在此寄存器文件夹中. 如果您需要支持一个没有下列特性之一的浏览器, 我建议加入一个来自 [cdnjs.cloudflare.com/polyfill (中文(简体) )](https://cdnjs.cloudflare.com/polyfill)数字 :

**用于演示的多填充示例 :**

```html
<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?version=4.8.0&features=Array.from%2CArray.prototype.find%2CArray.prototype.includes%2CSymbol%2CSymbol.iterator%2CDOMTokenList%2CObject.assign%2CCustomEvent%2CElement.prototype.classList%2CElement.prototype.closest%2CElement.prototype.dataset%2CElement.prototype.replaceChildren"></script>
```

**选择中使用的特性 :**

```polyfills
Array.from
Array.prototype.find
Array.prototype.includes
Symbol
Symbol.iterator
DOMTokenList
Object.assign
CustomEvent
Element.prototype.classList
Element.prototype.closest
Element.prototype.dataset
Element.prototype.replaceChildren
```

## 发展

要设置本地环境: 复制此 repo, 在终端窗口中导航到其目录并运行以下命令 :

`npm install`

### 剧作家

e2e(端到端)测试使用剧作家进行,这需要很可能在OS支持下安装.

`npx playwright install` `npx playwright install-deps`

对于JetBrain IDE来说 `Test automation` 建议插件 : [https://www.jetbrains.com/help/phpstorm/playwright.html 页面存档备份,存于互联网档案馆](https://www.jetbrains.com/help/phpstorm/playwright.html)

### 国家预防机制的任务

| 任务 | 使用量 |
| --- | --- |
| `npm run start` | 启动本地服务器用于开发 |
| `npm run test:unit` | 运行测试序列一次 |
| `npm run test:unit:watch` | 启动测试服务器并在文件更改时重新测试 |
| `npm run test:e2e` | 运行 e2e 测试的序列( 附带本地服务器) |
| `npm run test` | 进行单位测试和e2e测试 |
| `npm run playwright:gui` | 运行 Playwright e2e 测试( GUI) |
| `npm run playwright:cli` | 运行 Playwright e2e 测试( CLI) |
| `npm run js:build` | 将选择编译为丑化的 JavaScript 文件 |
| `npm run css:watch` | 监视 SCSS 文件更改 。 改变时,运行构建进程 |
| `npm run css:build` | 将 SCSS 文件编译、修改和前缀为 CSS |

### 构建旗帜

选择支持各种环境变量作为构建-旗来启用/失效特性. 被预建的捆绑会使用这些特性集,而树摇会使用非被使用的部分.

#### (中文(简体) )

**数值 :** `full` 编号 : `basic` 编号 : `null` **默认 :** `full`

Fuse.js 支持 a (中文(简体) ) `full`编号 :`basic` 简介. `full` 添加附加逻辑操作,与 Choices 不默认使用. 这个 `null` 选项将 Fuse.js 降为依赖,而是使用简单的前缀只搜索功能.

#### (简体中文)

**数值 :** `1` 编号 : `0` **默认 :** `1`

允许将选择加载到非浏览器环境中 .

### 有兴趣捐款吗?

我们总是有兴趣有更积极的维护者。 如果你有兴趣,请联系我

## 许可证

MIT 许可证

## 网络组件

想用选择作为网络组件吗 ? 你运气好 阿迪达斯为自己的设计系统 建造了一个可以找到的系统 [这里](https://github.com/adidas/choicesjs-stencil)。 。 。 .

## 杂项

感谢 [@mikefrancis (英语)](https://github.com/mikefrancis/) 页:1 [派我去打猎](https://twitter.com/_mikefrancis/status/701797835826667520) 对于一个非 J 查询解决方案 对于选择的框, 最终导致这个构建 !

## 常见问题

### @formio/choices\.js 是什么？

香草 JS 可自定义文本输入/ 选择框插件

### 如何安装 @formio/choices\.js？

在项目目录运行 npm install @formio/choices\.js，或使用 pnpm add / yarn add / bun add。

### @formio/choices\.js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @formio/choices\.js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @formio/choices\.js 可以商用吗？

@formio/choices\.js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @formio/choices\.js 的下载量有多少？

根据 npm 官方下载统计，@formio/choices\.js 在 2026/10/16 – 2026/11/14 这 30 天内被下载 207,953 次，日均约 6,932 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @formio/choices\.js 还在维护吗？

最新版本 11\.0\.3 发布于 2025/08/30（1\.2 年前）；至今共发布 6 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/04/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。