ComboBox QML 类型

组合按钮和弹出列表以选择选项。更多信息...

导入声明	import QtQuick.Controls
继承	控件

包括继承成员的所有成员列表

属性

acceptableInput : bool (自 QtQuick.Controls 2.2 (Qt 5.9)以来)
count : int
currentIndex : int
currentText : string
currentValue : var (自 QtQuick.Controls 2.14 (Qt 5.14)以来)
delegate : Component
displayText : string
down : bool (自 QtQuick.Controls 2.2 (Qt 5.9)以来)
editText : string (自 QtQuick.Controls 2.2 (Qt 5.9)以来)
editable : bool (自 QtQuick.Controllers 2.2 (Qt 5.9)以来)
flat : bool (自 QtQuick.Controls 2.1 (Qt 5.8)以来)
highlightedIndex : int
implicitContentWidthPolicy : enumeration (自 QtQuick.Controls 6.0 (Qt 6.0)以来)
implicitIndicatorHeight : real (自 QtQuick.Controls 2.5 (Qt 5.12)以来)
implicitIndicatorWidth : real (自 QtQuick.Controls 2.5 (Qt 5.12)以来)
indicator : Item
inputMethodComposing : bool (自 QtQuick.Controls 2.2 (Qt 5.9)以来)
inputMethodHints : flags (自 QtQuick.Controls 2.2 (Qt 5.9)以来)
model : model
popup : Popup
pressed : bool
selectTextByMouse : bool (自 QtQuick.Controls 2.15 (Qt 5.15)以来)
textRole : 字符串
validator : 验证器 (自 QtQuick.Controls 2.2 (Qt 5.9))
valueRole : 字符串 (自 QtQuick.Controls 2.14 (Qt 5.14))

信号

void accepted() (自 QtQuick.Controls 2.2 (Qt 5.9))
void activated(int index)
void highlighted(int index)

方法

void decrementCurrentIndex()
int find(string text, enumeration flags)
void incrementCurrentIndex()
int indexOfValue(object value) (自 QtQuick.Controls 2.14 (Qt 5.14))
void selectAll() (自 QtQuick.Controls 2.2 (Qt 5.9))
string textAt(int index)
var valueAt(int index) (自 QtQuick.Controls 2.14 (Qt 5.14))

详细描述

ComboBox 是组合按钮和弹出列表。它以占用最小屏幕空间的方式提供向用户显示选项列表的方法。

ComboBox 由数据模型填充。数据模型通常是一个 JavaScript 数组、ListModel 或整数，但也支持其他类型的数据模型。

ComboBox {
    model: ["First", "Second", "Third"]
}

可编辑 ComboBox

ComboBox 可以设置为可编辑。可编辑的 combo box 根据模型中可用的内容自动完成其文本。

以下示例演示了通过响应 accepted 信号向可编辑 combo box 添加内容。

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

默认情况下，点击 ComboBox 弹出菜单之外将关闭它，并且事件会传播到堆叠顺序较低的项。为了防止弹出菜单关闭，设置其 closePolicy

    popup.closePolicy: Popup.CloseOnEscape

为了防止事件传播，设置其 modal 属性为 true

    popup.modal: true

ComboBox 模型角色

ComboBox 可以可视化只提供 modelData 角色的标准数据模型

仅有一个角色的模型
没有命名角色的模型（JavaScript 数组、整数）

当使用具有多个命名角色的模型时，ComboBox必须配置使用特定的文本角色来表示其显示文本和代理实例。如果您想使用与文本角色对应的数据项的角色，则设置valueRole。之后可以使用currentValue属性和indexOfValue()方法来获取这些值的相关信息。

例如

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    // Used as an example of a backend - this would usually be
    // e.g. a C++ type exposed to QML.
    QtObject {
        id: backend
        property int modifier
    }

    ComboBox {
        textRole: "text"
        valueRole: "value"
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
        // Set the initial currentIndex to the value stored in the backend.
        Component.onCompleted: currentIndex = indexOfValue(backend.modifier)
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
    }
}

注意：如果ComboBox分配了具有多个命名角色的数据模型，但未定义textRole，则ComboBox无法可视化它并抛出ReferenceError: modelData未定义。

另请参阅：自定义ComboBox、输入控件和Qt Quick Controls中的焦点管理。

属性文档

acceptableInput : bool [只读，从QtQuick.Controls 2.2 (Qt 5.9)开始]

此属性保留组合框是否包含可接受的文本在可编辑的文本字段中。

如果设置了验证器，则值为true仅当当前文本作为最终字符串被验证器接受时（而不是作为中间字符串）。

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

另请参阅：验证器和accepted。

count : int [只读]

此属性保留组合框中项目数。

currentIndex : int

此属性保留组合框中当前项目的索引。

默认值为-1，当count为0时，否则为0。

另请参阅：activated()，currentText和highlightedIndex。

currentText : string [只读]

此属性保留组合框中当前项目的文本。

另请参阅：currentIndex，displayText，textRole和editText。

currentValue : var [只读，从QtQuick.Controls 2.14 (Qt 5.14)开始]

此属性保留组合框中当前项目的值。

有关使用此属性的示例，请参阅ComboBox模型角色。

此属性从QtQuick.Controls 2.14 (Qt 5.14)中引入。

另请参阅：currentIndex，currentText和valueRole。

delegate : Component

此属性保留一个代理，用于在组合框弹出窗口中呈现项目。

建议使用ItemDelegate（或任何其他AbstractButton的子类）作为代理。这确保了交互按预期工作，并在适当的时候自动关闭弹出窗口。当其他类型用作代理时，必须手动关闭弹出窗口。例如，如果使用MouseArea

delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: comboBox.popup.close()
    }
}

另请参阅ItemDelegate和自定义ComboBox。

displayText : string

此属性包含在组合框按钮上显示的文本。

默认情况下，显示文本显示当前选择。即，它跟随当前项的文本。但是，可以通过自定义值覆盖默认显示文本。

ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}

另请参阅currentText和textRole。

down : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

此属性包含组合框按钮是否在视觉上处于按下状态。

除非显式设置，否则在pressed或popup.visible为true时，此属性为true。要回到默认值，将此属性设置为undefined。

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

另请参阅pressed和popup。

editText : string [since QtQuick.Controls 2.2 (Qt 5.9)]

此属性包含可编辑组合框文本框中的文本。

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

另请参阅editable、currentText和displayText。

editable : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

此属性包含组合框是否可编辑。

默认值为false。

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

另请参阅validator。

flat : bool [since QtQuick.Controls 2.1 (Qt 5.8)]

此属性包含组合框按钮是否为平面。

平面组合框按钮除非被交互，否则不绘制背景。与普通组合框相比，平面组合框提供了更不突出于整个UI的外观。例如，当将组合框放入工具栏时，可能希望将其设置为平面以更好地匹配工具按钮的平面外观。

默认值为false。

此属性在QtQuick.Controls 2.1 (Qt 5.8)中引入。

highlightedIndex : int [只读]

此属性包含组合框弹出列表中突出显示的项目索引。

当突出显示的项目被激活时，弹出窗口关闭，currentIndex设置为highlightedIndex，并且此属性的值重置为-1，因为没有突出显示的项目。

另请参阅highlighted()和currentIndex。

implicitContentWidthPolicy : 枚举 [自 QtQuick.Controls 6.0 (Qt 6.0) 起支持]

该属性控制 implicitContentWidth 的计算方式。

当 ComboBox 的宽度不足以显示文本时，文本会被截断。根据被截断的文本部分，这可能会让最终用户难以选择项目。确保 ComboBox 宽度足够，避免文本被截断的有效方式是设置一个已知足够大的宽度。

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

然而，通常无法确定硬编码的值是否足够大，因为文本的大小取决于许多因素，例如字体家族、字体大小、翻译等。

implicitContentWidthPolicy 提供了一种轻松控制 implicitContentWidth 计算方式的方法，这反过来会影响 implicitWidth 的 ComboBox，并确保文本不会被截断。

可用的值有

常数	描述
`ContentItemImplicitWidth`	implicitContentWidth 将默认为 contentItem 的值。这是最有效的方式，因为不需要额外的文本布局。
`WidestText`	每次模型更改时，implicitContentWidth 将设置为 textRole 对应的最大文本的隐式宽度。对小模型应使用此选项，因为它可能很昂贵。
`WidestTextWhenCompleted`	在组件完成后，implicitContentWidth 将设置为对应最大文本 textRole 的隐式宽度。对小模型应使用此选项，因为它可能很昂贵。

默认值为 ContentItemImplicitWidth。

由于此属性仅影响 ComboBox 的隐式宽度，所以设置显式 width 仍然可能导致文本被截断。

注意：此功能要求 contentItem 是从 TextInput 派生的类型。

注意：此功能需要文本布局，因此对于大型模型或内容经常更新的模型可能很昂贵。

此属性是在 QtQuick.Controls 6.0 (Qt 6.0) 中引入的。

implicitIndicatorHeight : real [只读，自 QtQuick.Controls 2.5 (Qt 5.12) 起支持]

此属性包含隐式指示器的高度。

值等于 indicator ? indicator.implicitHeight : 0。

通常与 implicitContentHeight 和 implicitBackgroundHeight 一起使用，以计算 implicitHeight。

此属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参阅implicitIndicatorWidth。

implicitIndicatorWidth : real [只读，自 QtQuick.Controls 2.5 (Qt 5.12) 起支持]

此属性包含隐式指示器的宽度。

值等于 indicator ? indicator.implicitWidth : 0。

该属性通常与 implicitContentWidth 和 implicitBackgroundWidth 一起使用，用于计算 implicitWidth。

此属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另见 implicitIndicatorHeight。

indicator : Item

此属性包含下拉指标项。

另见自定义ComboBox。

inputMethodComposing : bool [只读，自QtQuick.Controls 2.2 (Qt 5.9)以来]

此属性表示编辑型ComboBox是否已从输入法接收部分文本输入。

在输入过程中，输入法可能依靠组合框的鼠标或按键事件来编辑或提交部分文本。该属性可用于确定何时禁用可能会干扰输入法正确操作的事件处理器。

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

inputMethodHints : flags [自QtQuick.Controls 2.2 (Qt 5.9)以来]

为输入法提供有关ComboBox预期内容和应如何操作的提示。

默认值是 Qt.ImhNoPredictiveText。

值是标志的位组合，如果没有设置提示则返回 Qt.ImhNone。

改变行为（行为改变）的标志是

Qt.ImhHiddenText - 应隐藏字符，如输入密码时通常使用。
Qt.ImhSensitiveData - 不应将键入的文本存储在活动输入法的任何持久存储中，例如预测性用户词典。
Qt.ImhNoAutoUppercase - 输入法不应在句子结尾时自动切换到大写。
Qt.ImhPreferNumbers - 优先考虑数字（但不是必需的）。
Qt.ImhPreferUppercase - 优先考虑大写字母（但不是必需的）。
Qt.ImhPreferLowercase - 优先考虑小写字母（但不是必需的）。
Qt.ImhNoPredictiveText - 键入时不要使用预测文本（即在字典中进行查找）。
Qt.ImhDate - 文本编辑器承担日期字段的职能。
Qt.ImhTime - 文本编辑器承担时间字段的职能。

限制输入（排他性标志）的标志是

Qt.ImhDigitsOnly - 只允许数字。
Qt.ImhFormattedNumbersOnly - 只允许数字输入。这包括小数点和负号。
Qt.ImhUppercaseOnly - 只允许大写字母输入。
Qt.ImhLowercaseOnly - 只允许小写字母输入。
Qt.ImhDialableCharactersOnly - 仅允许适用于电话拨号的字符。
Qt.ImhEmailCharactersOnly - 仅允许适用于电子邮件地址的字符。
Qt.ImhUrlCharactersOnly - 仅允许适用于URL的字符。

掩码

Qt.ImhExclusiveInputMask - 如果使用了任何排他性标志，则此掩码产生非零值。

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

model : model

此属性包含为ComboBox提供数据的模型。

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

另见 textRole 和数据模型。

此属性包含弹出层。

如有必要，可以手动打开或关闭弹出层。

onSpecialEvent: comboBox.popup.close()

另见自定义ComboBox。

pressed : bool [只读]

此属性表示组合框按钮是否被实际按下。按钮可以通过触摸或按键事件来按下。

另见 down。

selectTextByMouse : bool [自QtQuick.Controls 2.15 (Qt 5.15)以来]

该属性表示是否可以选中可编辑的ComboBox文本字段。

默认值为false。

此属性自QtQuick.Controls 2.15（Qt 5.15）引入。

textRole : string

该属性持有用于填充组合框的模型角色。

当模型有多个角色时，可以将textRole设置以确定应显示哪个角色。

另请参阅 model、currentText、displayText和ComboBox 模型角色。

validator : Validator [since QtQuick.Controls 2.2 (Qt 5.9)]

该属性持有可编辑组合框的输入文本验证器。

设置验证器后，文本字段将仅接受使文本属性处于中间状态的输入。只有在文本处于可接受状态时（即在按下Return或Enter键时），才会发出accepted信号。

目前支持的验证器包括IntValidator、DoubleValidator和RegularExpressionValidator。下面是一个使用验证器的示例，允许将整数0到10输入到文本字段中

ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}

此属性从QtQuick.Controls 2.2 (Qt 5.9)中引入。

另请参阅 acceptableInput、accepted和editable。

valueRole : string [since QtQuick.Controls 2.14 (Qt 5.14)]

该属性持有用于存储与模型中每个项目关联的值的模型角色。

有关使用此属性的示例，请参阅ComboBox模型角色。

此属性从QtQuick.Controls 2.14 (Qt 5.14)中引入。

另请参阅 model和currentValue。

信号文档

[since QtQuick.Controls 2.2 (Qt 5.9)] void accepted()

当在可编辑组合框上按下Return或Enter键时，将发出此信号。

可以通过处理此信号将新输入的项目添加到模型中，例如

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

在发出信号之前，将检查字符串是否在模型中存在。如果存在，则将currentIndex设置为其实际索引，将currentText设置为该字符串本身。

在发出信号之后，如果第一个检查失败（即项目不存在），将再次检查信号处理程序是否已添加项目。如果是，将相应地更新currentIndex和currentText。否则，将它们分别设置为-1和""。

注意：如果组合框上设置了validator，则只有在输入处于可接受状态时才会发出信号。

注意：对应处理程序为onAccepted。

该信号自QtQuick.Controls 2.2（Qt 5.9）引入。

void activated(int index)

当用户激活索引为index的项目时，将发出此信号。

当弹出窗口打开时选择一项，则会激活该项，导致窗口关闭（同时 currentIndex 改变），或者当弹出窗口关闭且通过键盘导航组合框时，也将导致 currentIndex 改变。《currentIndex》属性被设置为index。

注意：相应的处理程序是onActivated。

另请参阅：currentIndex。

void highlighted(int index)

当用户通过高度突出显示弹出列表中的项时，会发出此信号。

只有当弹出窗口打开且项被突出显示时，才会发出突出显示信号，但不一定触发 activated。

注意：相应的处理程序是onHighlighted。

另请参阅：highlightedIndex。

方法说明

void decrementCurrentIndex()

减少组合框的当前索引，如果弹出列表可见，则减少加亮索引。

另请参阅：currentIndex 和 highlightedIndex。

int find(string text, enumeration flags)

返回指定 text 的索引，如果没有找到匹配项则返回 -1。

搜索的方式由指定的匹配 flags 决定。默认情况下，组合框将执行大小写敏感的精确匹配（Qt.MatchExactly）。除非也指定了 Qt.MatchCaseSensitive 标志，否则所有其他匹配类型均不区分大小写。

常数	描述
`Qt.MatchExactly`	搜索条件与项完全匹配（默认）。
`Qt.MatchRegularExpression`	搜索条件与正则表达式匹配。
`Qt.MatchWildcard`	使用通配符进行搜索匹配。
`Qt.MatchFixedString`	搜索条件与固定字符串匹配。
`Qt.MatchStartsWith`	搜索条件与条目的开始匹配。
`Qt.MatchEndsWith`	搜索条件与条目的结尾匹配。
`Qt.MatchContains`	搜索条件包含在条目中。
`Qt.MatchCaseSensitive`	搜索区分大小写。

注意：只能在Component.completed() 为ComboBox发出后使用此功能。

例如

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

另请参阅：textRole。

void incrementCurrentIndex()

增加组合框的当前索引，如果弹出列表可见，则增加加亮索引。

另请参阅：currentIndex 和 highlightedIndex。

[since QtQuick.Controls 2.14 (Qt 5.14)] int indexOfValue(object value)

返回指定 value 的索引，如果没有找到匹配项则返回 -1。

有关如何使用此方法的示例，请参阅ComboBox Model Roles。

注意：只能在Component.completed() 为ComboBox发出后使用此功能。

此方法是在 QtQuick.Controls 2.14（Qt 5.14）中引入的。

另请参阅：find()，currentValue，currentIndex，valueRole 和 valueAt。

[since QtQuick.Controls 2.2 (Qt 5.9)] void selectAll()

选择组合框中可编辑文本框内的所有文本。

此方法在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅editText。

string textAt(int index)

返回指定index的文本，如果索引超出范围，则返回空字符串。

注意：只能在Component.completed() 为ComboBox发出后使用此功能。

例如

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

另请参阅：textRole。

[since QtQuick.Controls 2.14 (Qt 5.14)] var valueAt(int index)

返回组合框中位置index的值。

此方法是在 QtQuick.Controls 2.14（Qt 5.14）中引入的。

另请参阅indexOfValue。

ComboBox QML 类型

属性

信号

方法

详细描述

可编辑 ComboBox

ComboBox 的弹出菜单

ComboBox 模型角色

属性文档

信号文档

方法说明