ComboBox QML Type

该属性表示组合框的可编辑文本字段中是否包含可接受的文本。

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

该属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 validator 和accepted 。

该属性用于保存组合框中的项目数。

该属性保存当前项目在组合框中的索引。

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

另请参阅 activated(),currentText, 和highlightedIndex 。

该属性保存组合框中当前项目的文本。

另请参阅 currentIndex,displayText,textRole, 和editText 。

该属性保存组合框中当前项目的值。

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

该属性在 QtQuick.Controls 2.14 (Qt 5.14) 中引入。

另请参阅 currentIndex,currentText, 和valueRole 。

该属性包含一个在组合框弹出窗口中显示项目的委托。

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

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

另请参阅 ItemDelegate 和自定义 ComboBox。

该属性包含为组合框提供委托实例的模型。

它通常分配给popup 的contentItem 中的ListView 。

另请参阅 自定义组合框。

该属性用于保存显示在组合框按钮上的文本。

默认情况下，显示文本显示当前选择。也就是说，它跟随当前项的文本。但是，可以使用自定义值覆盖默认显示文本。

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

另请参阅 currentText 和textRole 。

该属性用于确定组合框按钮是否向下显示。

除非明确设置，否则当pressed 或popup.visible 为true 时，该属性为true 。要返回默认值，请将此属性设置为undefined 。

该属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 pressed 和popup 。

该属性保存可编辑组合框文本字段中的文本。

该属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 editable,currentText, 和displayText 。

该属性表示组合框是否可编辑。

默认值为false 。

该属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 validator 。

该属性表示组合框按钮是否为平面。

除非与之交互，否则扁平组合框按钮不会绘制背景。与普通的组合框相比，扁平组合框的外观使其在用户界面的其他部分中不那么显眼。例如，在工具栏中放置组合框时，可能需要将组合框设计成扁平的，以便与工具按钮的扁平外观更匹配。

默认值是false 。

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

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

当高亮显示项被激活时，弹出窗口关闭，currentIndex 设置为highlightedIndex ，该属性的值重置为-1 ，因为不再有高亮显示项。

另请参阅 highlighted() 和currentIndex 。

该属性控制如何计算ComboBox 的implicitContentWidth 。

当ComboBox 的宽度不足以显示文本时，该文本将被省略。视文本的哪些部分被省略而定，这可能会给最终用户选择项目带来困难。确保ComboBox 的宽度足以避免文本被省略的有效方法是设置一个已知足够大的宽度：

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

但是，通常无法知道硬编码值是否足够大，因为文本的大小取决于很多因素，如字体家族、字体大小、翻译等。

implicitContentWidthPolicy 提供了一种简便的方法来控制 implicitContentWidth 的计算方式，这反过来又会影响implicitWidth 的ComboBox ，并确保文本不会被省略。

可用值有

默认值是ContentItemImplicitWidth 。

由于此属性只影响ComboBox 的implicitWidth ，因此设置显式width 仍会导致误码。

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

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

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

它通常与implicitContentHeight 和implicitBackgroundHeight 一起用于计算implicitHeight 。

该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。

另请参阅 implicitIndicatorWidth 。

该属性保存隐式指示器宽度。

其值等于indicator ? indicator.implicitWidth : 0 。

它通常与implicitContentWidth 和implicitBackgroundWidth 一起用于计算implicitWidth 。

该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。

另请参阅 implicitIndicatorHeight 。

该属性用于保存下拉指示符项。

另请参阅 自定义 ComboBox。

该属性表示一个可编辑的组合框是否有来自输入法的部分文本输入。

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

该属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

为输入法提供有关组合框预期内容及其操作方式的提示。

默认值是Qt.ImhNoPredictiveText 。

该值是标志的位向组合，如果未设置提示，则为Qt.ImhNone 。

可改变行为的标志有

• Qt.ImhHiddenText - 字符应隐藏，通常用于输入密码。
• Qt.ImhSensitiveData - 输入的文本不应由 Active 输入法存储在任何持久性存储中，如预测用户字典。
• 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) 中引入。

该属性保存为组合框提供数据的模型。

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()

另请参阅 自定义组合框。

该属性显示组合框按钮是否被按下。按钮可通过触摸或按键事件按下。

另请参阅 down 。

该属性用于确定是否可以用鼠标选择可编辑ComboBox 的文本字段。

默认值为false 。

该属性在 QtQuick.Controls 2.15 (Qt 5.15) 中引入。

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

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

另请参阅 model,currentText,displayText 和ComboBox Model Roles 。

该属性用于保存可编辑组合框的输入文本验证器。

设置验证器后，文本字段将只接受使文本属性处于中间状态的输入。只有当按下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 。

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

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

该属性在 QtQuick.Controls 2.14 (Qt 5.14) 中引入。

另请参阅 model 和currentValue 。

在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) 中引入。

当位于index 的项目被用户激活时，将发出该信号。

当一个项目在弹出窗口打开时被选中，导致弹出窗口关闭（并且currentIndex 发生变化），或者当弹出窗口关闭并且通过键盘导航组合框，导致currentIndex 发生变化时，该项目被激活。currentIndex 属性设置为index 。

另请参阅 currentIndex 。

当用户高亮显示弹出列表中index 处的项目时，将发出该信号。

高亮信号仅在弹出窗口打开且项目被高亮时发出，但不一定是activated 。

另请参阅 highlightedIndex 。

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

另请参阅 currentIndex 和highlightedIndex 。

返回指定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 。

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

另请参阅 currentIndex 和highlightedIndex 。

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

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

此方法在 QtQuick.Controls 2.14 (Qt 5.14) 中引入。

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

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

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

另请参阅 editText 。

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

例如

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

另请参见 textRole 。

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

该方法在 QtQuick.Controls 2.14 (Qt 5.14) 中引入。

另请参阅 indexOfValue 。