佐佑时代

ComboBox（下拉列表框）

扩展自$.fn.iCombo.defaults。使用$.fn.iCombobox.defaults重写默认值对象。


下拉列表框显示一个可编辑文本框和下拉式列表，用户可以选择一个值或多个值。用户可以直接输入文本到列表顶部或选择一个或多个当前列表中的值。


依赖关系

•   combo

使用案例

通过< select>元素创建一个预定义结构的下拉列表框。

通过< input>标签创建下拉列表框。

使用Javascript创建下拉列表框。

                
        
                $('#cc').iCombobox({
                    url:'combobox_data.json',
                    valueField:'id',
                    textField:'text'
                });

创建2个有依赖关系的下拉列表框。

JSON数据格式化例子：

                [{
                    "id":1,
                    "text":"text1"
                },{
                    "id":2,
                    "text":"text2"
                },{
                    "id":3,
                    "text":"text3",
                    "selected":true
                },{
                    "id":4,
                    "text":"text4"
                },{
                    "id":5,
                    "text":"text5"
                }]
属性

下拉列表框属性扩展自combo(自定义下拉框)，下拉列表框新增的属性如下：

属性名 属性值类型 描述 默认值
valueField string 基础数据值名称绑定到该下拉列表框。 value
textField string 基础数据字段名称绑定到该下拉列表框。 text
groupField string 指定分组的字段名称 null
groupFormatter function(group) 返回格式化后的分组标题文本，以显示分组项
代码示例：
                            $('#cc').iCombobox({
                                groupFormatter: function(group){
                                    return '' + group + '';
                                }
                            });

mode string 定义了当文本改变时如何读取列表数据。设置为'remote'时，下拉列表框将会从服务器加载数据。当设置为“remote”模式时，用户输入将被发送到名为'q'的HTTP请求参数到服务器检索新数据。 local
url string 通过URL加载远程列表数据。 null
method string HTTP方法检索数据(POST / GET)。 post
data array 数据列表加载。
代码示例：
null
queryParams object 在向远程服务器请求数据的时候可以通过该属性像服务器端发送额外的参数。
代码示例：
                            $('#cc').iCombobox({
                                url : "127.0.0.1/xxx",
                                queryParams: {
                                "age" : 25,
                                "order" : "desc"
                                }
                            });
post
limitToList boolean 设置为true时，输入的值只能是列表框中的内容。 FALSE
showItemIcon boolean 设置为true时，显示选中项的图标。 FALSE
groupPosition string 定位分组选项。可用值有：“static”和“sticky”。当设置为“sticky”时会将分组选项标签固顶在下拉栏中。 static
filter function 定义当'mode'设置为'local'时如何过滤本地数据，函数有2个参数：
q：用户输入的文本。
row：列表行数据。
返回true的时候允许行显示。
代码示例：
                                    $('#cc').iCombobox({
                                        filter: function(q, row){
                                            var opts = $(this).iCombobox('options');
                                            return row[opts.textField].indexOf(q) == 0;
                                        }
                                    });
formatter function 定义如何渲染行。该函数接受1个参数：row。
代码示例：
                            $('#cc').iCombobox({
                                formatter: function(row){
                                    var opts = $(this).iCombobox('options');
                                    return row[opts.textField];
                                }
                            });
loader function(param,success,error) 定义了如何从远程服务器加载数据。返回false可以忽略该动作。该函数具备如下参数：
param：>传递到远程服务器的参数对象。
success(data)：在检索数据成功的时候调用该回调函数。
error()：在检索数据失败的时候调用该回调函数。
 json loader
loadFilter function(data) 返回过滤后的数据并显示。
事件

下拉列表框事件继承自combo(自定义下拉框)，下拉列表框新增的事件如下：

事件名 事件参数 描述
onBeforeLoad param 在请求加载数据之前触发，返回false取消该加载动作。
代码示例：
                            // 在加载服务器数据之前改变http请求参数的值
                            $('#cc').iCombobox({
                                onBeforeLoad: function(param){
                                    param.id = 2;
                                    param.language = 'js';
                                }
                            });
onLoadSuccess none 在加载远程数据成功的时候触发。
onLoadError none 在加载远程数据失败的时候触发。
onChange newValue,oldValue 在字段值发生更改的时候触发。
onClick record 在用户点击列表项的时候触发。
onSelect record 在用户选择列表项的时候触发。
onUnselect record 在用户取消选择列表项的时候触发。
方法

下拉列表框扩展自combo(自定义下拉框)，下拉列表框新增或重写的方法如下：

方法名 方法参数 描述
options none 返回属性对象。
getData none 返回加载数据。
loadData data 读取本地列表数据。
reload url 请求远程列表数据。通过'url'参数重写原始URL值。
代码示例：
                            $('#cc').iCombobox('reload');      // 使用旧的URL重新载入列表数据
                            $('#cc').iCombobox('reload','get_data.php');  // 使用新的URL重新载入列表数据
setValues values 设置下拉列表框值数组。
代码示例：
                            $('#cc').iCombobox('setValues', ['001','002']);
setValue value 设置下拉列表框的值。
代码示例：
                            $('#cc').iCombobox('setValue', '001');
clear none 清除下拉列表框的值。
select value 选择指定项。
unselect value 取消选择指定项。