ComboBox QML Type

用于选择选项的按钮与下拉列表组合。更多...

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

属性

• acceptableInput : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• count : int
• currentIndex : int
• currentText : string
• currentValue : var (since QtQuick.Controls 2.14 (Qt 5.14))
• delegate : Component
• delegateModel : model
• displayText : string
• down : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• editText : string (since QtQuick.Controls 2.2 (Qt 5.9))
• editable : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• flat : bool (since QtQuick.Controls 2.1 (Qt 5.8))
• highlightOnHover : bool (since QtQuick.Controls 6.12 (Qt 6.12))
• highlightedIndex : int
• implicitContentWidthPolicy : enumeration (since QtQuick.Controls 6.0 (Qt 6.0))
• implicitIndicatorHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitIndicatorWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• indicator : Item
• inputMethodComposing : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• inputMethodHints : flags (since QtQuick.Controls 2.2 (Qt 5.9))
• model : model
• popup : Popup
• pressed : bool
• selectTextByMouse : bool (since QtQuick.Controls 2.15 (Qt 5.15))
• textRole : string
• validator : Validator (since QtQuick.Controls 2.2 (Qt 5.9))
• valueRole : string (since QtQuick.Controls 2.14 (Qt 5.14))

信号

• void accepted() (since 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) (since QtQuick.Controls 2.14 (Qt 5.14))
• void selectAll() (since QtQuick.Controls 2.2 (Qt 5.9))
• string textAt(int index)
• var valueAt(int index) (since QtQuick.Controls 2.14 (Qt 5.14))

详细说明

ComboBox 是一种结合了按钮和下拉列表的控件。它能够以占用最小屏幕空间的方式向用户展示选项列表。

下拉列表通过数据模型进行填充。数据模型通常为 JavaScript 数组、ListModel 或整数，但也支持其他类型的数据模型。

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

可编辑下拉列表

ComboBox 可以设置为可编辑的（editable ）。可编辑的 ComboBox 会根据模型中可用的内容自动完成文本。

以下示例演示了如何通过响应accepted 信号向可编辑下拉列表追加内容。

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，使其为display text 和delegate 实例使用特定的text role 。若要使用与 text 角色对应的模型项角色，请将valueRole 设置为 true。随后可通过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 {
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
        textRole: "text"
        valueRole: "value"
        // Set currentValue to the value stored in the backend.
        currentValue: backend.modifier
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
    }
}

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

属性文档

acceptableInput : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

该属性用于指示下拉列表中是否包含可接受的文本，该文本需位于可编辑文本框中。

如果已设置验证器，则只有当当前文本作为最终字符串（而非中间字符串）被验证器视为有效时，该值才会为true 。

该属性在 QtQuick.Controls 2.2（Qt 5.9）中引入。

另请参阅 validator 和accepted 。

count : int [read-only]

该属性存储下拉列表框中的项目数量。

currentIndex : int

该属性存储组合框中当前项的索引。

当 `count ` 的值为 `0` 时，其默认值为 `-1 `；否则，其默认值为 `0 `。

另请参阅 activated()、currentText 以及highlightedIndex 。

currentText : string [read-only]

该属性存储下拉列表中当前选项的文本内容。

另请参阅 currentIndex 、displayText 、textRole 以及editText 。

currentValue : var [since QtQuick.Controls 2.14 (Qt 5.14)]

该属性存储下拉列表中当前选中的项的值。设置此属性将使currentIndex 指向具有相应值的项；若未找到该项，则设置为-1 。若同时声明式地设置currentIndex 和currentValue ，将导致未定义的行为。不支持将此属性设置为非唯一值。

有关如何使用此属性的示例，请参见ComboBox Model Roles 。

该属性首次引入于 QtQuick.Controls 2.14（Qt 5.14）。

另请参阅 currentIndex 、currentText 以及valueRole 。

delegate : Component

该属性保存一个委托，用于在组合框的弹出窗口中显示项目。

建议使用 `ItemDelegate `（或任何其他 `AbstractButton ` 的派生类）作为委托。这可确保交互行为符合预期，并且弹出窗口会在适当的时候自动关闭。当使用其他类型作为委托时，必须手动关闭弹出窗口。例如，如果使用 `MouseArea `：

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

自 Qt 6.11 起，ComboBox 不再拥有该委托对象的所有权。

另请参阅 ItemDelegate 和自定义 ComboBox。

delegateModel : model [read-only]

该属性保存为下拉列表框提供委托实例的模型。

通常，该属性会在popup 的contentItem 中被赋值为ListView 。

另请参阅 “自定义 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)]

该属性控制下拉列表框按钮是否采用扁平化样式。

扁平化下拉列表框按钮在未被交互时不会绘制背景。与普通下拉列表框相比，扁平化下拉列表框的外观使其在用户界面中显得不那么显眼。 例如，将下拉列表框放置在工具栏中时，通常需要将其设置为扁平样式，以便更好地与工具按钮的扁平外观相匹配。

默认值为false 。

该属性在 QtQuick.Controls 2.1（Qt 5.8）中引入。

highlightOnHover : bool [since QtQuick.Controls 6.12 (Qt 6.12)]

该属性控制将鼠标悬停在项目上时是否应将其高亮显示。

默认值为true 。

该属性首次引入于 QtQuick.Controls 6.12（Qt 6.12）。

highlightedIndex : int [read-only]

该属性保存组合框弹出列表中被高亮显示项的索引。

当选中项被激活时，弹出窗口将关闭，currentIndex 将被设置为highlightedIndex ，而该属性的值将重置为-1 ，因为此时已不再有选中项。

另请参阅 highlighted() 和currentIndex 。

implicitContentWidthPolicy : enumeration [since QtQuick.Controls 6.0 (Qt 6.0)]

此属性控制如何计算“ComboBox ”的implicitContentWidth 。

当ComboBox 的宽度不足以显示文本时，该文本会被截断。根据被截断的文本部分不同，这可能会导致最终用户难以选中项目。确保ComboBox 宽度足够以避免文本被截断的一种有效方法是，将其宽度设置为已知足够大的值：

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

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

implicitContentWidthPolicy 提供了一种简便的方法来控制 implicitContentWidth 的计算方式，从而影响ComboBox 的implicitWidth ，并确保文本不会被截断。

可用值包括：

默认值为 `ContentItemImplicitWidth`。

由于该属性仅影响“ComboBox ”的“implicitWidth ”，因此即使显式设置了width ，仍可能导致内容被截断。

该属性在 QtQuick.Controls 6.0（Qt 6.0）中引入。

implicitIndicatorHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

该属性存储隐式指示器的高度。

该值等于indicator ? indicator.implicitHeight : 0 。

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

该属性在 QtQuick.Controls 2.5（Qt 5.12）中引入。

另请参阅 implicitIndicatorWidth 。

implicitIndicatorWidth : real [read-only, since 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 [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

该属性用于指示可编辑下拉列表框是否已通过输入法接收了部分文本输入。

在文本组合过程中，输入法可能会依赖组合框发出的鼠标或键盘事件来编辑或提交部分文本。可通过此属性来确定何时禁用可能干扰输入法正常运行的事件处理程序。

该属性首次引入于 QtQuick.Controls 2.2（Qt 5.9）。

inputMethodHints : flags [since QtQuick.Controls 2.2 (Qt 5.9)]

向输入法提供有关下拉列表预期内容及其工作方式的提示。

默认值为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 {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

另请参阅 textRole 和“数据模型”。

popup : Popup

该属性用于存储弹出窗口。

如有必要，可以手动打开或关闭该弹出窗口：

onSpecialEvent: comboBox.popup.close()

另请参阅 “自定义组合框”。

pressed : bool [read-only]

该属性表示下拉列表框按钮是否被实际按下。按钮可以通过触摸事件或键盘事件被按下。

另请参阅 down 。

selectTextByMouse : bool [since QtQuick.Controls 2.15 (Qt 5.15)]

该属性控制可编辑的ComboBox 的文本字段是否可以使用鼠标选中。

默认值为false 。

该属性在 QtQuick.Controls 2.15（Qt 5.15）中引入。

textRole : string

该属性存储用于填充下拉列表的模型角色。

当模型具有多个角色时，可通过设置textRole 来确定应显示哪个角色。

另请参阅 model 、currentText 、displayText 以及ComboBox Model Roles 。

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

该属性用于为可编辑的下拉列表框设置输入文本验证器。

当设置了验证器后，文本字段只会接受使 text 属性处于中间状态的输入。只有当按下Return 或Enter 键时，text 属性处于可接受状态，才会发出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 Model Roles 。

该属性是在 QtQuick.Controls 2.14（Qt 5.14）中引入的。

另请参阅 model 和currentValue 。

信号文档

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

当在editable 组合框上按下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 和"" 。

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

void activated(int index)

当用户激活位于index 处的项目时，会触发此信号。

当弹出窗口打开时选中某个项，导致弹出窗口关闭（且currentIndex 发生变化）；或者当弹出窗口关闭时，通过键盘导航至下拉列表并导致currentIndex 发生变化，此时该项即被视为已激活。currentIndex 属性将设置为index 。

另请参阅 currentIndex 。

void highlighted(int index)

当用户将弹出列表中位于index 的项目高亮显示时，会触发此信号。

“highlighted”信号仅在弹出窗口打开且某项被选中时触发，但不一定是位于activated 的位置。

另请参见 highlightedIndex 。

方法文档

void decrementCurrentIndex()

将组合框的当前索引减1；如果弹出列表可见，则将高亮显示的索引减1。

另请参阅 currentIndex 和highlightedIndex 。

int find(string text, enumeration flags)

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

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

例如：

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 。

该方法在 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 对应的文本，如果索引超出范围，则返回空字符串。

例如：

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 。