EasyUI Combobox 核心屬性與常用方法速查手冊

EasyUI Combobox 核心屬性與常用方法速查手冊

EasyUI Combobox 是 Web 表單中最常用的下拉選擇組件。本文整理核心屬性、關鍵方法、數據加載方式與常見問題解決方案，供開發快速查閱。

一、核心屬性對照表

二、關鍵方法速查

三、數據加載三種方式

1. HTML 標籤聲明 (最簡單)

<select id="cc" class="easyui-combobox" name="dept" style="width:200px;">
    <option value="1" selected>部門一</option>
    <option value="2">部門二</option>
    <option value="3">部門三</option>
</select>

2. JavaScript 本地數據

$('#cc').combobox({
    valueField: 'id',
    textField: 'name',
    data: [
        {id: 1, name: '部門一'},
        {id: 2, name: '部門二'},
        {id: 3, name: '部門三'}
    ]
});

3. 遠程 JSON 數據源

$('#cc').combobox({
    valueField: 'id',
    textField: 'name',
    url: '/api/departments',  // 返回 [{id:1,name:'部門一'},...]
    method: 'get',
    onLoadSuccess: function(data) {
        console.log('加載完成，共 ' + data.length + ' 條');
    },
    onLoadError: function() {
        $.messager.alert('錯誤', '數據加載失敗');
    }
});

四、常見場景最佳實踐

1. 級聯下拉 (省市區)

$('#province').combobox({
    url: '/api/provinces',
    valueField: 'code',
    textField: 'name',
    onSelect: function(rec) {
        $('#city').combobox('reload', '/api/cities?provinceCode=' + rec.code);
        $('#city').combobox('clear');
        $('#district').combobox('clear');
    }
});

2. 多選標籤模式

$('#tags').combobox({
    multiple: true,
    valueField: 'id',
    textField: 'name',
    url: '/api/tags',
    formatter: function(row) {
        return '<span class="tag">' + row.name + '</span>';
    }
});

3. 可編輯搜索/遠程過濾

$('#search').combobox({
    editable: true,
    hasDownArrow: false,  // 隱藏下拉箭頭，純輸入框
    valueField: 'id',
    textField: 'name',
    url: '/api/search?q={q}',  // {q} 會被替換為用戶輸入
    mode: 'remote',  // 遠程過濾模式
    filter: function(q, row) {  // 本地過濾模式時生效
        return row.name.indexOf(q) >= 0;
    }
});

4. 表單提交獲取值

// 方式1: 直接獲取
var deptId = $('#dept').combobox('getValue');
var deptName = $('#dept').combobox('getText');

// 方式2: 表單序列化 (需 name 屬性)
var formData = $('#myForm').serialize();  // dept=1&name=xxx

// 方式3: easyui form 插件
$('#myForm').form('submit', {
    url: '/api/save',
    onSubmit: function() { return $(this).form('validate'); },
    success: function(data) { ... }
});

五、常見問題排查

六、事件鉤子完整列表

$('#cc').combobox({
    onLoadSuccess: function(data) { },      // 數據加載成功
    onLoadError: function() { },            // 數據加載失敗
    onSelect: function(record) { },         // 選中項目
    onUnselect: function(record) { },       // 取消選中
    onChange: function(newVal, oldVal) { }, // 值變化 (含程序設值)
    onBeforeLoad: function(param) { },      // 加載前 (可修改 param)
    onShowPanel: function() { },            // 下拉面板顯示
    onHidePanel: function() { },            // 下拉面板隱藏
    onClick: function(record) { }           // 點擊選項
});

核心提示：valueField 對應提交值 (數據庫 ID)，textField 對應顯示文本。獲取值用 getValue()，獲取文本用 getText()。設置值用 setValue()，設置文本用 setText()。遠程數據務必返回標準 JSON 數組，字段名與 valueField/textField 完全一致。

EasyUI Combobox 功能豐富，掌握核心屬性與方法，配合事件鉤子，可覆蓋 95% 表單下拉場景。建議項目中封裝通用 Combobox 組件，統一風格、驗證、錯誤處理。