Chosen是用来增强单选列表和多选列表的更佳选择。

示例

单项选择和多项选择

$('select.chosen-select').chosen({
    no_results_text: '没有找到',    // 当检索时没有找到匹配项时显示的提示文本
    disable_search_threshold: 10, // 10 个以下的选择项则不显示检索框
    search_contains: true         // 从任意位置开始检索
});

扩展检索

有时我们希望用户检索的更加开心,例如为汉语选项添加拼音检索支持。Chosen提供了扩展字段专门用来检索,只需要为<option>标签增加data-keys="*"属性。

data-keys属性可以用空格或英文逗号来分隔多个供检索的关键字。

提示

扩展检索本身并不提供拼音检索功能,如果你需要支持使用拼音检索时,需要你自己在chosen初始化之前在data-keys属性中写入拼音字符串。

用法

启动参数

参数 名称 可选值 说明
lang 界面语言
  • 'zh_cn'(默认),中文简体
  • 'zh_tw'中文繁体
  • 'en',英文
如果不设置此值,会自动优先从<html lang="">属性作为界面语言设置。
allow_single_deselect 允许取消单选
  • true 允许取消
  • false(默认) 不允许
如果允许单选取消,则会在用户选择选项之后,显示一个移除按钮,点击此按钮会移除用户选择的项目。
disable_search 禁用检索
  • false(默认) 不禁用
  • true 禁用
禁用检索功能,将不再现实搜索框来让用户检索选项。
disable_search_threshold 自动禁用的最大值 数字,默认为0 当可选选项数目小于或等于此值时,自动禁用检索选项。
inherit_select_classes 继承select的CLASS 默认为false 如果设置为true,chosen在初始化之后会获取原<select>上的CSS CLASS值并添加在chosen容器<div>上。
max_selected_options 最大选择数目 数字,默认为Infinity 仅多选生效;当用户选择的选项数目达到此值时,将会触发chosen:maxselected事件。
no_results_text 无结果时的文本 字符串,默认从语言配置获取 当用户检索时没有匹配的结果会显示此文本。
placeholder_text 空值占位文本 字符串,默认为"" 当用户没有选择选项时显示此文本;此选项也可以通过<select>data-placeholder属性来指定。
placeholder_text_multiple 多选空值占位文本 字符串,默认为"" 如果没有设置此选项,则会尝试读取placeholder_text选项的值。
placeholder_text_single 单选空值占位文本 字符串,默认为"" 如果没有设置此选项,则会尝试读取placeholder_text选项的值。
search_contains 启用任意位置检索 默认为false 默认情况下,仅仅会从选项或检索关键字的开始进行匹配,例如"he"仅仅能匹配"hello",不能匹配"ahead",如果启用此选项,则可以从关键的任意位置进行匹配。
single_backstroke_delete 启用退格键删除 默认为true 仅多选生效;启用此选项允许用户在多选时按退格键(Backspace)和删除键(Delete)来删除上一个选择项。
width 宽度 默认为原始<select>的宽度 默认chosen的宽度与原始的<select>一致,如果原始的<select>在chosen初始化之前不可见,可能需要手动指定一个宽度,否则chosen的宽度会为0;如果使用响应式布局,建议宽度设定为'100%'
display_disabled_options 显示不可选的选项 默认为true 默认情况下会在选项列表中显示不可选的选项,禁用此选项来隐藏不可选的选项。
display_selected_options 显示已选择的选项 默认为true 仅多选生效;禁用此选项则在选项列表中隐藏已选择的选项。
drop_direction 选项列表弹出方向
  • "auto"(默认) 自动决定
  • "down" 向下
  • "up" 向上
在自动决定情况下默认向下弹出,如果下方空间不够会自动改为向上弹出
事件

Chosen的事件绑定在原始<select>上,使用jQuery方法来监听事件。目前可以使用以下事件:

事件 说明
change 当选择的值发生改变时发生。
chosen:ready 当完成初始化之后触发。
chosen:maxselected 当达到最大选择数目(通过max_selected_options指定)时发生
chosen:showing_dropdown 当弹出显示选项列表时发生。
chosen:hiding_dropdown 当隐藏选项列表时发生。
chosen:no_results 当没有检索到匹配的选项时发生。
$('select.chosen-select').on('change', function(){
    // 用户改变了选择,快快处理
});
方法

可以通过触发事件来调用chosen的方法。

// 当原始select中的选项发生变化时通知chosen更新选项列表
$('select.chosen-select').trigger('chosen:updated');

所有可以通过事件触发的方法有:

触发事件 说明
chosen:updated 通知chosen重新从原始select中更新选项列表。
chosen:activate 让chosen激活并获取焦点;激活之后的chosen会捕获用户输入并执行操作。
chosen:open 打开(弹出)选项列表面板。
chosen:close 隐藏选项列表面板。

详细用法可以参考chosen官方文档

图标选择插件

示例

为方便选择漂亮的图标,依赖于Chosen新作了图标选择插件。

$('select.chosen-icons').chosenIcons(options);
提示

图标选择插件依赖chosen插件,且是单独提供的。也就是说如果你没有使用自定制版,不仅仅需要在HTML文件中加载chosen插件,还需要额外加载 [zui/lib/chosen/chosen.icons*.js, zui/lib/chosen/chosen.icons*.css] 文件。

用法

图标选择插件可以使用chosen的所有选项和方法。