Chosen是用来增强单选列表和多选列表的更佳选择。
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 |
界面语言 |
|
如果不设置此值,会自动优先从<html lang=""> 属性作为界面语言设置。 |
allow_single_deselect |
允许取消单选 |
|
如果允许单选取消,则会在用户选择选项之后,显示一个移除按钮,点击此按钮会移除用户选择的项目。 |
disable_search |
禁用检索 |
|
禁用检索功能,将不再现实搜索框来让用户检索选项。 |
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 |
选项列表弹出方向 |
|
在自动决定情况下默认向下弹出,如果下方空间不够会自动改为向上弹出 |
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的所有选项和方法。