ComboBox（下拉列表框）

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

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

依赖关系

• combo

使用案例

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

<select id="cc" data-toggle="topjui-combobox" name="dept" data-options="width:200">
    <option value="aa">aitem1</option>
    <option>bitem2</option>
    <option>bitem3</option>
    <option>ditem4</option>
    <option>eitem5</option>
</select>

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

<input id="cc" data-toggle="topjui-combobox" name="dept" data-options="valueField:'id',textField:'text',url:'get_data.php'">

使用Javascript创建下拉列表框。

<input id="cc" name="dept" value="aa">

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

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

<input id="cc1" data-toggle="topjui-combobox" data-options="
        valueField: 'id',
        textField: 'text',
        url: 'get_data1.php',
        onSelect: function(rec){
            var url = 'get_data2.php?id='+rec.id;
            $('#cc2').iCombobox('reload', url);
        }">
<input id="cc2" data-toggle="topjui-combobox" data-options="valueField:'id',textField:'text'">

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

属性代码示例

groupFormatter属性示例：

$('#cc').iCombobox({
    groupFormatter: function(group){
        return '<span style="color:red">' + group + '</span>';
    }
});

data属性示例：

<input data-toggle="topjui-combobox" data-options="
valueField: 'label',
textField: 'value',
data: [{
    label: 'java',
    value: 'Java'
},{
    label: 'perl',
    value: 'Perl'
},{
    label: 'ruby',
    value: 'Ruby'
}]">

queryParams属性示例：

$('#cc').iCombobox({
    url : "127.0.0.1/xxx",
    queryParams: {
        "age" : 25,
        "order" : "desc"
    }
});

filter属性示例：

$('#cc').iCombobox({
    filter: function(q, row){
        var opts = $(this).iCombobox('options');
        return row[opts.textField].indexOf(q) == 0;
    }
});

formatter属性示例：

$('#cc').iCombobox({
    formatter: function(row){
        var opts = $(this).iCombobox('options');
        return row[opts.textField];
    }
});

事件

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

事件名	事件参数	描述
onBeforeLoad	param	在请求加载数据之前触发，返回false取消该加载动作。见下方代码示例。
onLoadSuccess	none	在加载远程数据成功的时候触发。
onLoadError	none	在加载远程数据失败的时候触发。
onChange	newValue,oldValue	在字段值发生更改的时候触发。
onClick	record	在用户点击列表项的时候触发。
onSelect	record	在用户选择列表项的时候触发。
onUnselect	record	在用户取消选择列表项的时候触发。

事件代码示例

onBeforeLoad事件示例：

// 在加载服务器数据之前改变http请求参数的值
$('#cc').iCombobox({
    onBeforeLoad: function(param){
        param.id = 2;
        param.language = 'js';
    }
});

方法

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

方法名	方法参数	描述
options	none	返回属性对象。
getData	none	返回加载数据。
loadData	data	读取本地列表数据。
reload	url	请求远程列表数据。通过'url'参数重写原始URL值。见下方代码示例。
setValues	values	设置下拉列表框值数组。见下方代码示例。
setValue	value	设置下拉列表框的值。见下方代码示例。
clear	none	清除下拉列表框的值。
select	value	选择指定项。
unselect	value	取消选择指定项。

方法代码示例

reload方法示例：

$('#cc').iCombobox('reload');      // 使用旧的URL重新载入列表数据
$('#cc').iCombobox('reload','get_data.php');  // 使用新的URL重新载入列表数据

setValues方法示例：

$('#cc').iCombobox('setValues', ['001','002']);

setValue方法示例：

$('#cc').iCombobox('setValue', '001');