jquery.sumoselect是一款跨设备、跨浏览器的jQuery下拉列表框插件。该jQuery下拉列表框插件可以单选,也可以多选。它的样式可以通过CSS文件来自定义。它的最大特点是可以跨设备使用,所有设备上功能都是一致的。

该jQuery下拉列表框插件的特点有:

  • 可以进行单选,也可以进行多选。
  • 可以通过CSS文件来自定义样式。
  • 支持绝大多数的设备。
  • 根据设备智能渲染。
  • 在Android、IOS、Windows和其它设备上会自动渲染出该设备原生样式的下拉列表框。
  • 可以自定义提交数据的格式(多选可以通过 csv 或默认形式来提交)。
  • 支持Selected、Disabled和占位文本。
  • 易扩展,开发者可以很容易的创建新的组件。
  • 使用基本方法间隙管理如添加选项、删除选项、禁用、选择等。

该jQuery下拉列表框插件需要使用jQuery 1.8.3+版本,建议使用最新版本的jQuery。

浏览器和设备的支持

  • IE8+, Firefox 4+, Chrome, Safari 4+, Opera 11+(其它浏览器应该也能工作,但未经测试)
  • iOs 3+, Android 2.1+ , Windows Mobile(其它设备应该也可以工作,但未经测试)

使用方法

使用方法非常简单,可以在页面加载之后调用默认的调用方法:

$(document).ready(function () {
      $('.SlectBox').SumoSelect();
});                
              

也可以使用插件提供的参数来进行控制:

$(document).ready(function () {
  $('.SlectBox').SumoSelect({
    placeholder: 'This is a placeholder',
    csvDispCount: 3 
  });
});                
              

配置参数

下面是该jQuery下拉列表框插件的可用参数:

参数 类型 描述
placeholder string 显示在select下拉列表框中的占位文本
csvDispCount int 要显示的多个项的编号,使用逗号分隔。设置为0表示全选
captionFormat string 当选择的项大于csvDispCount设置的数目时显示的文本。默认为{0} Selected{0}会被替换为选择的项的总数
floatWidth int 最小的设备宽度,如果小于这个宽度,下拉列表框将渲染为浮动弹出的效果
forceCustomRendering boolean Force the custom modal ( Floating list ) on all devices below floatWidth resolution.
nativeOnDevice Array[string] 从用户代理字符串中获取识别移动手机的关键字
outputAsCSV boolean 设置为true则使用csv来提交数据
csvSepChar string 如果outputAsCSV设置为true,该选项用作它的分割符。
okCancelInMulti boolean 在桌面模式中是否允许OK/Cancel按钮为多选模式。
triggerChangeCombined boolean In Multiselect mode whether to trigger change event on individual selection of each item or on combined selection ( pressing of OK or Cancel button ).

插件的默认设置如下:

{
    placeholder: 'Select Here',
    csvDispCount: 3,
    captionFormat: '{0} Selected',
    floatWidth: 500,
    forceCustomRendering: false,
    nativeOnDevice: ['Android', 'BlackBerry', 'iPhone', 'iPad', 'iPod', 'Opera Mini', 'IEMobile', 'Silk'],
    outputAsCSV : false,
    csvSepChar : ',', 
    okCancelInMulti: true, 
    triggerChangeCombined : true
}                
              

方法

要调用方法,你首先要插件SumoSelect对象:

var MySelect;
$(document).ready(function () {
  MySelect = $('.SlectBox').SumoSelect();
});                
              

或者可以直接从select元素中获取它的实例:

var MySelect = $('select.SlectBox')[0].sumo;                
              

注意:SumoSelect对象是绑定在原生的select元素上的,而不是jQuery对象。

下面是可以使用的方法:

  • .unload():停用SumoSelect插件,使用原生的select列表框。
    $('select.SlectBox')[0].sumo.unload();
    
  • .add(value [,text][,index]):在给定的位置插入一个新的列表项,如果未指定位置,则在最后插入。位置为0表示在开始处插入。
    // adds a option with value and html set to 'india' at the last.
    $('select.SlectBox')[0].sumo.add('india');
    
    // adds a option with value and html set to 'india' at index no 3.
    $('select.SlectBox')[0].sumo.add('india',3);
    
    // adds a option with value = 'india' and html = 'Indian' at the last.
    $('select.SlectBox')[0].sumo.add('india','Indian');
    
    // adds a option with value and html set to 'india' at index no 0.
    $('select.SlectBox')[0].sumo.add('india','Indian',0);
    
  • .remove(index):删除指定位置的列表项。
    $('select.SlectBox')[0].sumo.remove(2);
    
  • .selectItem(index):选择指定位置的列表项。可以进行多选。
    //selects the item at index 2
     $('select.SlectBox')[0].sumo.selectItem(2);
    
  • .unSelectItem(index):取消某个下拉列表项的选择。
    //unselects the item at index 2
     $('select.SlectBox')[0].sumo.unSelectItem(2);
    
  • .disableItem(index):禁用下拉列表中的某个列表项。
    //disables the item at index 2
     $('select.SlectBox')[0].sumo.disableItem(2);
    
  • .enableItem(index):启用下拉列表中的某个列表项。
    //enables the item at index 2
     $('select.SlectBox')[0].sumo.enableItem(2);
    
  • .disabled = true/false:这是一个SumoSelect启用和禁用控制的选项。
    // Disables the control
     $('select.SlectBox')[0].sumo.disabled = true;
    
    // Enables the control
     $('select.SlectBox')[0].sumo.disabled = true;
    
    // Prints current state of control
    console.log( $('select.SlectBox')[0].sumo.disabled )