@formio/choices.js

中文文档

11.0.3发布于 2025/08/30MITTypeScriptESM + CJS近 30 天下载 20.8万

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

文档目录101 节

TL; DR 数据
有兴趣写自己的 ES6 JavaScript 插件吗 ? 检查出来 ES6.io (英语) {\fn黑体\fs22\b…
发起人:
目录
安装
支助科/支助科
设置
术语
输入类型
配置选项
无声
项目
选择
选择限制
最大项目
关闭 Dropdown 选择
单模式多功能选择
添加选择
添加项目
删除项目
删除项目按钮
删除项目按钮对齐
编辑项目
允许 HTML
允许 Html 用户输入
重复项目
分隔符
粘贴
搜索已启用
搜索选择
搜索字段
搜索文件夹
搜索结果链接: 4,
阴影旋转
职位
重置滚动位置
添加项目过滤器
应索特
应保存项目
排序器
占位符
占位符数值
搜索 Placeholders 数值
预加值
附录
选定选择
装入文本
无结果文本
无选择图文
项目选择文本
添加项目文本
删除项目IconText
删除项目标签文本
最大项目文本
数值
标签编号
类名
回电
在Init上调用
召回 CreateTemplates( StretToEl : (stry: string) QQ HTML Elem…
活动
添加项目
删除项目
突出显示项目
未突出显示项目
选择
变动
搜索
显示向下
隐藏向下
突出显示选择
方法
销毁( c) ;
输入( i) ;
刷新( 用Events: boolean = false, 选择 First option: boolean = fa…
突出显示全部( E) ;
全部取消突出显示( I) ;
删除活动项目ByValue( 值: 字符串);
删除活动项目( 不包括? : 数目);
删除选择( 值: 字符串 ) ;
删除突出的项目( 运行事件 ?: 布尔) ;
显示 Dropdown( 预防输入焦点 ? : 布尔) ;
隐藏 Dropdown( 预防输入焦点 ? : 布尔) ;
setChoices(选择)Array OrFatcher ? : (输入选择 QQ输入组) [(选择 : 选择 ) …
清除选择( C) ;
获得Value( 仅值 ?: boolean): 字符串 [] QQ事件选择 [] QQ事件选择 ;
设置Value( 项: 字符串[ ] Q输入选择[ ] : 此;
设置 ChoiceByValue( 值: 字符串 QQ字符串 [] );
清除Store( );
清除输入( I) ;
禁用( t) ;
启用( );
浏览器兼容性
发展
剧作家
国家预防机制的任务
构建旗帜
有兴趣捐款吗?
许可证
网络组件
杂项

选择.js

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

演示

TL; DR 数据

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

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

发起人:

安装

与国家预防机制数字 :

npm install choices.js

与雅伦数字 :

yarn add choices.js

从a 光盘N数字 :

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

<!-- 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/[email protected]/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/[email protected]/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/[email protected]/public/assets/scripts/choices.min.js"></script>

或者直接包括选择:

<!-- 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中:

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

在.js/.ts中:

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

设置

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

  // 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">`	`text`
`<select>`	`select-one`
`<select 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

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

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 用于用户成功添加项目.

示例

// 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

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

示例

// 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,通过输入的占位符属性将用作占位符值.

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

<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 参数(见默认配置 ,或者通过字符串.

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

删除项目IconText

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

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

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

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

删除项目标签文本

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

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

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

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

最大项目文本

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

受影响的输入类型: text

用法 : 当用户关注输入但已经到达时显示的文本最大项数。要访问最大项数,请通过一个函数 maxItemCount 参数(见默认配置 ,或者通过字符串.

数值

类型 : Function 默认 : strict equality

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

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

示例

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 中的类. 默认类名跟随贝姆标注.

回电

说明: 每一次回电, 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各个组件的自定义模板(见术语). 选择要使用自定义模板, 您必须维护定义的各种数据属性这里。。。 . 如果您想要扩展一点原始模板, 您可以使用 Choices.defaults.templates 访问原始模板函数.

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

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

示例

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

或更复杂的:

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 对象.

示例

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 参数是选项。通过已受影响的元素对象.

方法

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

// 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:

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:

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:

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 只返回值,而不是值对象.

示例

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 选项,但可以在初始化选择后调用.

示例

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 可以是单个字符串,也可以是一系列字符串

示例

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

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

浏览器兼容性

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

用于演示的多填充示例 :

<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>

选择中使用的特性 :

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 页面存档备份,存于互联网档案馆

国家预防机制的任务

任务	使用量
`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 许可证

网络组件

想用选择作为网络组件吗 ? 你运气好阿迪达斯为自己的设计系统建造了一个可以找到的系统这里。。。 .

杂项

感谢 @mikefrancis (英语) 页:1 派我去打猎对于一个非 J 查询解决方案对于选择的框, 最终导致这个构建 !

版本与发布记录

@formio/choices.js 共发布 6 个版本，首次发布于 2021/04/20；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`11.0.3`latest	2025/08/30	1.2 年前
`11.0.3-rc.1`rc	2025/01/16	1.8 年前
`10.2.1`	2024/01/17	2 年前
`10.2.1-rc.1`	2024/01/03	2 年前
`10.2.0`	2023/01/25	3 年前
`9.0.1`	2021/04/20	5 年前

关于 @formio/choices.js 的常见问题

@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 和提交记录判断。

npm install @formio/choices.js

pnpmpnpm add @formio/choices.js
yarnyarn add @formio/choices.js
bunbun add @formio/choices.js

在你的项目目录中运行此命令。

近 30 天下载

207,953

约 20.8万次日均 6,932 次

统计周期 2026/10/16 – 2026/11/14
数据来自 npm 官方下载统计，今天更新

最新版本11.0.3发布于 1.2 年前

开源许可MIT宽松许可

包体积1.5 MB122 个文件 · 解压后

运行依赖1 个

模块格式ESM + CJS

TypeScript自带类型

发布版本6 个近 12 个月 0 个

首次发布2021/04/205 年前

元数据更新2025/08/30

每一个软件包背后，
都有分享与创造的人。