### ComboBox（下拉列表框）

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

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

####

#### 依赖关系

- combo

####

#### 使用案例

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

1. <select id="cc" class="easyui-combobox" name="dept" style="width:200px;">
2. <option value="aa">aitem1</option>
3. <option>bitem2</option>
4. <option>bitem3</option>
5. <option>ditem4</option>
6. <option>eitem5</option>
7. </select>

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

1. <input id="cc" class="easyui-combobox" name="dept"
2. data-options="valueField:'id',textField:'text',url:'get_data.php'" />

使用Javascript创建下拉列表框。

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

1. $('#cc').combobox({
2. url:'combobox_data.json',
3. valueField:'id',
4. textField:'text'
5. });

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

1. <input id="cc1" class="easyui-combobox" data-options="
2. valueField: 'id',
3. textField: 'text',
4. url: 'get_data1.php',
5. onSelect: function(rec){
6. var url = 'get_data2.php?id='+rec.id;
7. $('#cc2').combobox('reload', url);
8. }" />
9. <input id="cc2" class="easyui-combobox" data-options="valueField:'id',textField:'text'" />

JSON数据格式化例子：

1. [{
2. "id":1,
3. "text":"text1"
4. },{
5. "id":2,
6. "text":"text2"
7. },{
8. "id":3,
9. "text":"text3",
10. "selected":true
11. },{
12. "id":4,
13. "text":"text4"
14. },{
15. "id":5,
16. "text":"text5"
17. }]

#### 属性

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

属性名 | 属性值类型 | 描述 | 默认值
--- | --- | --- | ---
valueField | string | 基础数据值名称绑定到该下拉列表框。 | value
textField | string | 基础数据字段名称绑定到该下拉列表框。 | text
groupField | string | 指定分组的字段名称（译者注：分组的字段由数据源决定）。（该属性自1.3.4版开始可用） | null
groupFormatter | function(group) | 返回格式化后的分组标题文本，以显示分组项（该属性自1.3.4版开始可用） 代码示例：
    $('#cc').combobox({
    	groupFormatter: function(group){
    		return '<span style="color:red">' + group + '</span>';
    	}
    });
mode | string | 定义了当文本改变时如何读取列表数据。设置为'remote'时，下拉列表框将会从服务器加载数据。当设置为“remote”模式时，用户输入将被发送到名为'q'的HTTP请求参数到服务器检索新数据。 | local
url | string | 通过URL加载远程列表数据。 | null
method | string | HTTP方法检索数据(POST / GET)。 | post
data | array | 数据列表加载。 代码示例：
    <input class="easyui-combobox" data-options="
    		valueField: 'label',
    		textField: 'value',
    		data: [{
    			label: 'java',
    			value: 'Java'
    		},{
    			label: 'perl',
    			value: 'Perl'
    		},{
    			label: 'ruby',
    			value: 'Ruby'
    		}]" />
| null
queryParams | object | 在向远程服务器请求数据的时候可以通过该属性像服务器端发送额外的参数。（该属性自1.4.2版开始可用） 代码示例：
    $('#cc').combobox({
                    url : "127.0.0.1/xxx",
    	queryParams: {
    		"age" : 25,
                                    "order" : "desc"
    	}
    });
| post
limitToList | boolean | 设置为true时，输入的值只能是列表框中的内容。（该属性自1.5版开始可用） | false
showItemIcon | boolean | 设置为true时，显示选中项的图标。（该属性自1.4.5版开始可用） | false
groupPosition | string | 定位分组选项。可用值有：“static”和“sticky”。当设置为“sticky”时会将分组选项标签固顶在下拉栏中。（该属性自1.4.5版开始可用） | static
filter | function | 定义当'mode'设置为'local'时如何过滤本地数据，函数有2个参数： q：用户输入的文本。 row：列表行数据。 返回true的时候允许行显示。 代码示例：
    $('#cc').combobox({
    	filter: function(q, row){
    		var opts = $(this).combobox('options');
    		return row[opts.textField].indexOf(q) == 0;
    	}
    });
formatter | function | 定义如何渲染行。该函数接受1个参数：row。 代码示例：
    $('#cc').combobox({
    	formatter: function(row){
    		var opts = $(this).combobox('options');
    		return row[opts.textField];
    	}
    });
loader | function(param,success,error) | 定义了如何从远程服务器加载数据。返回false可以忽略该动作。该函数具备如下参数： param：传递到远程服务器的参数对象。 success(data)：在检索数据成功的时候调用该回调函数。 error()：在检索数据失败的时候调用该回调函数。 | json loader
loadFilter | function(data) | 返回过滤后的数据并显示。（该属性自1.3.3版开始可用） |

#### 事件

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

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

#### 方法

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

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