ComboBox(下拉列表框)
扩展自$.bo.defaults。使用$.bobox.defaults重写默认值对象。
下拉列表框显示一个可编辑文本框和下拉式列表,用户可以选择一个值或多个值。用户可以直接输入文本到列表顶部或选择一个或多个当前列表中的值。
依赖关系
示例
通过元素创建一个预定义结构的下拉列表框。
aitem1
bitem2
bitem3
ditem4
eitem5
通过标签创建下拉列表框。
data-options="valueField:'id',textField:'text',url:'get_data.php'"/>
使用Javascript创建下拉列表框。
$('#cc').combobox({
url:'combobox_data.json',
valueField:'id',
textField:'text'
});
创建2个有依赖关系的下拉列表框。
valueField:'id',
textField:'text',
url:'get_data1.php',
onSelect:function(rec){
varurl='get_data2.php?id='+rec.id;
$('#cc2').combobox('reload',url);
}"/>
JSON数据格式化例子:
[{
"id":1,
"text":"text1"
},{
"id":2,
"text":"text2"
},{
"id":3,
"text":"text3",
"selected":true
},{
"id":4,
"text":"text4"
},{
"id":5,
"text":"text5"
}]
属性
属性名
属性值类型
描述
默认值
valueField
string
基础数据值名称绑定到该下拉列表框。
value
textField
string
基础数据字段名称绑定到该下拉列表框。
text
groupField
string
指定分组的字段名称(译者注:分组的字段由数据源决定)。(该属性自1.3.4版开始可用)
null
groupFormatter
function(group)
返回格式化后的分组标题文本,以显示分组项(该属性自1.3.4版开始可用)
代码示例:$('#cc').combobox({
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
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版开始可用)
事件
事件名
事件参数
描述
onBeforeLoad
param
在请求加载数据之前触发,返回false取消该加载动作。
代码示例:// 在加载服务器数据之前改变http请求参数的值
$('#cc').combobox({
onBeforeLoad: function(param){
param.id = 2;
param.language = 'js';
}
});
onLoadSuccess
none
在加载远程数据成功的时候触发。
onLoadError
none
在加载远程数据失败的时候触发。
onSelect
record
在用户选择列表项的时候触发。
onUnselect
record
在用户取消选择列表项的时候触发。
方法
方法名
方法参数
描述
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
取消选择指定项。