---
title: "Ext.form.field.ComboBox"
description: "xtype 为 combobox 的 Ext JS 原生组件参考。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag.879818327.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Ext.form.field.ComboBox

源码定义：`ext-all-debug.js:104735`。分类：表单与字段。

## 创建示例

```javascript
var component = Ext.create("Ext.form.field.ComboBox", {
  xtype: "combobox",
  allQuery: '',
  anyMatch: false,
  ariaRole: 'combobox',
  autoSelect: true,
  renderTo: Ext.getBody()
});
```

## 属性

| 属性 | 类型 | 默认值 | 说明 | 配置示例 |
| --- | --- | --- | --- | --- |
| `allQuery` | `String` | `''` | 配置组件的 `allQuery` 选项。 | `allQuery: ''` |
| `anyMatch` | `Boolean` | `false` | 控制是否启用 `anyMatch` 行为。 | `anyMatch: false` |
| `ariaRole` | `String` | `'combobox'` | 组件在辅助技术中的 ARIA 角色。 | `ariaRole: 'combobox'` |
| `autoSelect` | `Boolean` | `true` | 控制是否启用 `autoSelect` 行为。 | `autoSelect: true` |
| `caseSensitive` | `Boolean` | `false` | 控制是否启用 `caseSensitive` 行为。 | `caseSensitive: false` |
| `clearFilterOnBlur` | `Boolean` | `true` | 控制是否启用 `clearFilterOnBlur` 行为。 | `clearFilterOnBlur: true` |
| `componentLayout` | `String` | `'combobox'` | 组件采用的内部布局策略。 | `componentLayout: 'combobox'` |
| `defaultListConfig` | `Object` | `{` | 配置组件的 `defaultListConfig` 选项。 | `defaultListConfig: {` |
| `displayField` | `String` | `'text'` | 下拉或选择组件显示给用户的记录字段。 | `displayField: 'text'` |
| `fieldSubTpl` | `Array` | `[` | 字段 HTML 的子模板片段。 | `fieldSubTpl: [` |
| `forceSelection` | `Boolean` | `false` | 控制输入值是否必须匹配数据源中的记录。 | `forceSelection: false` |
| `growToLongestValue` | `Boolean` | `true` | 控制是否启用 `growToLongestValue` 行为。 | `growToLongestValue: true` |
| `hiddenDataCls` | `Mixed` | `Ext.baseCSSPrefix + 'hide-display ' + Ext.bas...` | 配置 `hiddenDataCls` 对应的 CSS 类名。 | `hiddenDataCls: Ext.baseCSSPrefix + 'hide-display ' + Ext.bas...` |
| `hiddenName` | `String` | `''` | 配置组件的 `hiddenName` 选项。 | `hiddenName: ''` |
| `ignoreSelection` | `Number` | `0` | 配置组件的 `ignoreSelection` 选项。 | `ignoreSelection: 0` |
| `multiSelect` | `Boolean` | `false` | 控制是否允许同时选择多个值。 | `multiSelect: false` |
| `pageSize` | `Number` | `0` | 配置组件的 `pageSize` 选项。 | `pageSize: 0` |
| `pickerCls` | `String` | `''` | 配置 `pickerCls` 对应的 CSS 类名。 | `pickerCls: ''` |
| `queryCaching` | `Boolean` | `false` | 控制是否启用 `queryCaching` 行为。 | `queryCaching: false` |
| `queryMode` | `String` | `'remote'` | 配置组件的 `queryMode` 选项。 | `queryMode: 'remote'` |
| `queryParam` | `String` | `'query'` | 配置组件的 `queryParam` 选项。 | `queryParam: 'query'` |
| `removingRecords` | `Object/null` | `null` | 配置组件的 `removingRecords` 选项。 | `removingRecords: null` |
| `resetToDefault` | `Mixed` | `Ext.emptyFn` | 配置组件的 `resetToDefault` 选项。 | `resetToDefault: Ext.emptyFn` |
| `selectOnTab` | `Boolean` | `true` | 控制是否启用 `selectOnTab` 行为。 | `selectOnTab: true` |
| `transformInPlace` | `Boolean` | `true` | 控制是否启用 `transformInPlace` 行为。 | `transformInPlace: true` |
| `triggerAction` | `String` | `'all'` | 配置组件的 `triggerAction` 选项。 | `triggerAction: 'all'` |
| `triggerCls` | `Mixed` | `Ext.baseCSSPrefix + 'form-arrow-trigger'` | 配置 `triggerCls` 对应的 CSS 类名。 | `triggerCls: Ext.baseCSSPrefix + 'form-arrow-trigger'` |
| `typeAhead` | `Boolean` | `false` | 控制是否启用 `typeAhead` 行为。 | `typeAhead: false` |
| `typeAheadDelay` | `Number` | `250` | 配置组件的 `typeAheadDelay` 选项。 | `typeAheadDelay: 250` |

## 方法

| 方法 | 参数 | 说明 | 调用示例 |
| --- | --- | --- | --- |
| `getSubTplData` | `` | 读取并返回 `subTplData`。 执行时会保留父类默认行为。源码涉及 `callParent()`。 | `component.getSubTplData()` |
| `afterRender` | `` | 生成 `after` 的渲染结果。 执行时会保留父类默认行为。源码涉及 `callParent()`、`setHiddenValue()`。 | `component.afterRender()` |
| `resizeComboToGrow` | `` | 将 `resizeCombo` 转换为 `grow`。 | `component.resizeComboToGrow()` |
| `initComponent` | `` | 初始化组件及其子项。 执行时会保留父类默认行为、更新组件值、更新 `name`、`value` 状态。源码涉及 `addEvents()`、`bindStore()`、`callParent()`、`setValue()`。 | `component.initComponent()` |
| `getTextValue` | `` | 读取并返回 `textValue`。 | `component.getTextValue()` |
| `getStore` | `` | 读取并返回 `store`。 | `component.getStore()` |
| `beforeBlur` | `` | 在 `blur` 前执行预处理。源码涉及 `assertValue()`。 | `component.beforeBlur()` |
| `onFocus` | `` | 处理 `focus` 回调。 执行时会保留父类默认行为。源码涉及 `callParent()`、`doRawQuery()`。 | `component.onFocus()` |
| `assertValue` | `` | 处理 `assertValue` 操作。 执行时会更新组件值。源码涉及 `getRawValue()`、`setValue()`、`collapse()`、`getDisplayValue()`。 | `component.assertValue()` |
| `onTypeAhead` | `` | 处理 `typeAhead` 回调。 执行时会更新组件值。源码涉及 `getRawValue()`、`getPicker()`、`setRawValue()`、`selectText()`。 | `component.onTypeAhead()` |
| `beforeReset` | `` | 在 `reset` 前执行预处理。 执行时会保留父类默认行为。源码涉及 `callParent()`。 | `component.beforeReset()` |
| `onUnbindStore` | `store` | 处理 `unbindStore` 回调。 | `component.onUnbindStore(...)` |
| `onBindStore` | `store, initial` | 处理 `bindStore` 回调。源码涉及 `resetToDefault()`。 | `component.onBindStore(...)` |
| `bindStore` | `store, preventFilter,  initial` | 绑定 `store`。源码涉及 `getStore()`。 | `component.bindStore(...)` |
| `getStoreListeners` | `` | 读取并返回 `storeListeners`。 | `component.getStoreListeners()` |
| `onBeforeLoad` | `` | 处理 `beforeLoad` 回调。 | `component.onBeforeLoad()` |
| `onDataChanged` | `` | 处理 `dataChanged` 回调。 执行时会刷新界面或布局。源码涉及 `resizeComboToGrow()`、`updateLayout()`。 | `component.onDataChanged()` |
| `onClear` | `` | 处理 `clear` 回调。 执行时会更新 `removingRecords` 状态。源码涉及 `resizeComboToGrow()`、`onDataChanged()`。 | `component.onClear()` |
| `onRemove` | `` | 处理 `remove` 回调。 执行时会更新 `removingRecords` 状态。源码涉及 `resizeComboToGrow()`。 | `component.onRemove()` |
| `onException` | `` | 处理 `exception` 回调。源码涉及 `collapse()`。 | `component.onException()` |
| `onLoad` | `store, records, success` | 处理 `load` 回调。 执行时会更新组件值。源码涉及 `doAutoSelect()`、`setValue()`。 | `component.onLoad(...)` |
| `doRawQuery` | `` | 执行 `rawQuery` 操作。源码涉及 `doQuery()`、`getRawValue()`。 | `component.doRawQuery()` |
| `doQuery` | `queryString, forceAll, rawQuery` | 执行 `query` 操作。 执行时会更新 `lastQuery` 状态。源码涉及 `beforeQuery()`、`getPicker()`、`expand()`、`doAutoSelect()`。 | `component.doQuery(...)` |
| `beforeQuery` | `queryPlan` | 在 `query` 前执行预处理。 执行时会派发 `beforequery` 事件。源码涉及 `fireEvent()`、`collapse()`。 | `component.beforeQuery(...)` |
| `doLocalQuery` | `queryPlan` | 执行 `localQuery` 操作。 执行时会更新 `queryFilter` 状态。源码涉及 `getPicker()`、`expand()`、`collapse()`、`afterQuery()`。 | `component.doLocalQuery(...)` |
| `doRemoteQuery` | `queryPlan` | 执行 `remoteQuery` 操作。源码涉及 `afterQuery()`、`loadPage()`、`getParams()`。 | `component.doRemoteQuery(...)` |
| `afterQuery` | `queryPlan` | 在 `query` 后执行后处理。 执行时会同步关联状态。源码涉及 `expand()`、`doTypeAhead()`、`getRawValue()`、`getDisplayValue()`。 | `component.afterQuery(...)` |
| `loadPage` | `pageNum, options` | 加载 `page`。源码涉及 `getParams()`。 | `component.loadPage(...)` |
| `onPageChange` | `toolbar, newPage` | 处理 `pageChange` 回调。源码涉及 `loadPage()`。 | `component.onPageChange(...)` |
| `getParams` | `queryString` | 读取并返回 `params`。 | `component.getParams(...)` |
| `doAutoSelect` | `` | 执行 `autoSelect` 操作。 | `component.doAutoSelect()` |
| `doTypeAhead` | `` | 执行 `typeAhead` 操作。 执行时会更新 `typeAheadTask` 状态。 | `component.doTypeAhead()` |
| `onTriggerClick` | `` | 处理 `triggerClick` 回调。 执行时会更新 `duringTriggerClick` 状态。源码涉及 `collapse()`、`onFocus()`、`doQuery()`、`getRawValue()`。 | `component.onTriggerClick()` |
| `onPaste` | `` | 处理 `paste` 回调。 | `component.onPaste()` |
| `onKeyUp` | `e, t` | 处理 `keyUp` 回调。 执行时会保留父类默认行为、更新 `lastKey` 状态。源码涉及 `callParent()`。 | `component.onKeyUp(...)` |
| `initEvents` | `` | 初始化 `events`。 执行时会保留父类默认行为。源码涉及 `callParent()`、`mon()`。 | `component.initEvents()` |
| `onDestroy` | `` | 处理 `destroy` 回调。 执行时会保留父类默认行为、更新 `typeAheadTask` 状态。源码涉及 `bindStore()`、`callParent()`。 | `component.onDestroy()` |
| `onAdded` | `` | 处理 `added` 回调。 执行时会保留父类默认行为、更新 `bindValueField` 状态。源码涉及 `callParent()`、`up()`。 | `component.onAdded()` |
| `createPicker` | `` | 创建 `picker`。 执行时会更新 `picker` 状态。源码涉及 `mon()`。 | `component.createPicker()` |
| `alignPicker` | `` | 对齐 `picker`。 执行时会保留父类默认行为。源码涉及 `getPicker()`、`getPosition()`、`getHeight()`、`callParent()`。 | `component.alignPicker()` |
| `onListRefresh` | `` | 处理 `listRefresh` 回调。 执行时会同步关联状态。源码涉及 `alignPicker()`、`syncSelection()`。 | `component.onListRefresh()` |
| `onItemClick` | `picker, record` | 处理 `itemClick` 回调。 执行时会更新组件值、更新 `displayTplData` 状态。源码涉及 `setRawValue()`、`getDisplayValue()`、`collapse()`。 | `component.onItemClick(...)` |
| `onBeforeSelect` | `list, record` | 处理 `beforeSelect` 回调。 执行时会派发 `beforeselect` 事件。源码涉及 `fireEvent()`。 | `component.onBeforeSelect(...)` |
| `onBeforeDeselect` | `list, record` | 处理 `beforeDeselect` 回调。 执行时会派发 `beforedeselect` 事件。源码涉及 `fireEvent()`。 | `component.onBeforeDeselect(...)` |
| `onListSelectionChange` | `list, selectedRecords` | 处理 `listSelectionChange` 回调。 执行时会派发 `select` 事件、更新组件值。源码涉及 `setValue()`、`fireEvent()`。 | `component.onListSelectionChange(...)` |
| `onExpand` | `` | 处理 `expand` 回调。 执行时会更新 `listKeyNav`、`ignoreMonitorTab` 状态。源码涉及 `getPicker()`、`selectHighlighted()`、`triggerBlur()`、`collapse()`。 | `component.onExpand()` |
| `onCollapse` | `` | 处理 `collapse` 回调。 执行时会更新 `ignoreMonitorTab` 状态。 | `component.onCollapse()` |
| `select` | `r,  assert` | 选中当前目标。 执行时会派发 `select` 事件、更新组件值。源码涉及 `setValue()`、`fireEvent()`。 | `component.select(...)` |
| `findRecord` | `field, value` | 查找 `record`。 | `component.findRecord(...)` |
| `findRecordByValue` | `value` | 查找 `recordByValue`。源码涉及 `findRecord()`。 | `component.findRecordByValue(...)` |
| `findRecordByDisplay` | `value` | 查找 `recordByDisplay`。源码涉及 `findRecord()`。 | `component.findRecordByDisplay(...)` |
| `setValue` | `value, doSelect` | 设置 `value`。 执行时会同步关联状态、更新 `value`、`displayTplData` 状态。源码涉及 `setHiddenValue()`、`findRecordByValue()`、`setRawValue()`、`getDisplayValue()`。 | `component.setValue(...)` |
| `setHiddenValue` | `values` | 设置 `hiddenValue`。 | `component.setHiddenValue(...)` |
| `getDisplayValue` | `` | 读取并返回 `displayValue`。 | `component.getDisplayValue()` |
| `getValue` | `` | 读取并返回 `value`。 执行时会更新 `value`、`displayTplData` 状态。源码涉及 `getRawValue()`、`getDisplayValue()`。 | `component.getValue()` |
| `getSubmitValue` | `` | 读取并返回 `submitValue`。源码涉及 `getValue()`。 | `component.getSubmitValue()` |
| `isEqual` | `v1, v2` | 判断 `equal` 状态。 | `component.isEqual(...)` |
| `clearValue` | `` | 清空 `value`。 执行时会更新组件值。源码涉及 `setValue()`。 | `component.clearValue()` |
| `syncSelection` | `` | 同步 `selection`。 | `component.syncSelection()` |
| `onEditorTab` | `e` | 处理 `editorTab` 回调。 | `component.onEditorTab(...)` |

## 事件

| 事件 | 说明 | 监听示例 |
| --- | --- | --- |
| `beforedeselect` | 执行 `deselect` 对应的默认操作之前触发；监听器返回 `false` 可取消默认处理。 源码在 `onBeforeDeselect()` 中通过 `fireEvent()` 触发。 | `listeners: { beforedeselect: function () {} }` |
| `beforequery` | 下拉组件执行查询前触发；监听器可修改或取消查询。 源码在 `beforeQuery()` 中通过 `fireEvent()` 触发。 | `listeners: { beforequery: function () {} }` |
| `beforeselect` | 选中值或记录之前触发，可用于取消选择。 源码在 `onBeforeSelect()` 中通过 `fireEvent()` 触发。 | `listeners: { beforeselect: function () {} }` |
| `select` | 用户选中值或记录时触发。 源码在 `onListSelectionChange()`、`select()` 中通过 `fireEvent()` 触发。 | `listeners: { select: function () {} }` |

Source: https://ag.879818327.xyz/ext/form/form-field-combobox/index.mdx