SearchField QML Type

用于搜索功能的专用输入框。更多

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

属性

• clearIndicator
  • clearIndicator.hovered : bool
  • clearIndicator.implicitIndicatorHeight : real
  • clearIndicator.implicitIndicatorWidth : real
  • clearIndicator.indicator : Item
  • clearIndicator.pressed : bool
• currentIndex : int
• delegate : Component
• delegateModel : model
• highlightedIndex : int
• live : bool
• popup : Popup
• searchIndicator
  • searchIndicator.hovered : bool
  • searchIndicator.implicitIndicatorHeight : real
  • searchIndicator.implicitIndicatorWidth : real
  • searchIndicator.indicator : Item
  • searchIndicator.pressed : bool
• suggestionCount : int
• suggestionModel : model
• text : string
• textRole : string

信号

• void accepted()
• void activated(int index)
• void clearButtonPressed()
• void highlighted(int index)
• void searchButtonPressed()
• void searchTriggered()
• void textEdited()

详细说明

SearchField 是一个专门用于搜索功能的输入框。该控件包括一个文本字段、搜索和清除图标，以及一个显示建议或搜索结果的弹出窗口。

SearchField 的指示器

SearchField 提供两个可选的嵌入式指示按钮：searchIndicator 和clearIndicator 。

它们不是BusyIndicator 或ProgressBar 意义上的指示器。相反，它们是嵌入到字段中的交互式控件（类似于SpinBox 中的上/下按钮）。按searchIndicator 会触发searchButtonPressed() ，按clearIndicator 会触发clearButtonPressed() 。

除了暴露操作外，指示器按钮还提供交互状态（按下/悬停/聚焦等），可被样式使用。

自定义指示器内容

searchIndicator 和clearIndicator 属性为只读。可通过其内部属性进行自定义。

其中，按钮的可视化内容由indicator 项提供，该项是可写的。这样就可以完全替换或删除默认内容。

例如，删除两个指示器图标：

SearchField {
    searchIndicator.indicator: null
    clearIndicator.indicator: null
}

这是一种受支持的自定义情况。不同的 SearchField 变体可以省略其中一个按钮（例如，只提供一个搜索按钮），或用替代项（例如，触发语音输入的麦克风图标）替换指示器内容。

SearchField 模型的作用

SearchField 能够可视化提供modelData 角色的标准数据模型：

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

使用具有多个已命名角色的模型时，必须对 SearchField 进行配置，使其text 和delegate 实例使用特定的text role 。

ListModel {
    id : fruitModel
    ListElement { name: "Apple"; color: "green" }
    ListElement { name: "Cherry"; color: "red" }
    ListElement { name: "Banana"; color: "yellow" }
    ListElement { name: "Orange"; color: "orange" }
    ListElement { name: "WaterMelon"; color: "pink" }
}

SortFilterProxyModel {
    id: fruitFilter
    model: fruitModel
    sorters: [
        RoleSorter {
            roleName: "name"
        }
    ]
    filters: [
        FunctionFilter {
            component CustomData: QtObject { property string name }
            property var regExp: new RegExp(fruitSearch.text, "i")
            onRegExpChanged: invalidate()
            function filter(data: CustomData): bool {
                return regExp.test(data.name);
            }
        }
    ]
}

SearchField {
    id: fruitSearch
    suggestionModel: fruitFilter
    textRole: "name"
    anchors.horizontalCenter: parent.horizontalCenter
}

另请参阅 searchIndicator,clearIndicator,searchButtonPressed() 和clearButtonPressed() 。

属性文档

clearIndicator group

该分组属性包含 clearIndicator 指示符项及其相关属性。

该属性包含清除指示符。按下它会触发clearButtonPressed() 。

暴露该属性后，样式和应用程序可通过其内部属性对其进行自定义（例如，通过clearIndicator.indicator 替换或删除clearIndicator ，或对按下和悬停等交互状态做出反应）。

另请参见 SearchField's Indicators 。

currentIndex : int

该属性保存弹出列表中当前所选建议的索引。

当未选择任何建议时，其值为-1 。

当模型发生变化或用户键入或编辑文本时，currentIndex 不会自动修改。只有当用户通过点击弹出列表中的项目或在高亮显示的项目上按回车键明确选择建议时，才会更新 currentIndex。

可以设置 currentIndex，例如，在启动时显示模型中的第一个项目。在这样做之前，请确保模型不是空的：

SearchField {
    id: searchField
    suggestionModel: ListModel {
        ListElement { value: "123,456" }
    }
    textRole: "value"

    Component.onCompleted: {
        if (suggestionModel.count > 0) {
           text = suggestionModel.get(0).value
           currentIndex = 0
       }
    }
}

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

delegate : Component

该属性包含一个在搜索栏弹出窗口中显示项目的委托。

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

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

自 Qt 6.11 起，SearchField 不再拥有委托的所有权。

delegateModel : model [read-only]

该属性包含为搜索字段提供委托实例的模型。

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

highlightedIndex : int [read-only]

该属性保存当前高亮显示项目在弹出列表中的索引。

高亮显示的项目被激活后，弹出窗口关闭，currentIndex 更新为与highlightedIndex 匹配，该属性重置为-1 ，表示当前没有高亮显示的项目。

另请参阅 highlighted() 和currentIndex 。

live : bool

该属性包含一个布尔值，用于决定是否在每次文本编辑时触发搜索。

当设置为true 时，每次文本更改都会发出searchTriggered() 信号，从而可以对每次按键做出响应。当设置为false 时，只有当用户按下 Enter 或 Return 键时，才会发出searchTriggered() 信号。

另请参阅 searchTriggered()。

popup : Popup

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

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

onSpecialEvent: searchField.popup.close()

searchIndicator group

该分组属性包含 searchIndicator 指示符项及其相关属性。

该属性包含搜索指示器。按下它会触发searchButtonPressed() 。

暴露该属性后，样式和应用程序可通过其内部属性对其进行自定义（例如，通过searchIndicator.indicator 替换或删除searchIndicator ，或对按下和悬停等交互状态做出反应）。

另请参见 SearchField's Indicators 。

suggestionCount : int [read-only]

该属性用于保存要从建议模型中显示的建议数量。

suggestionModel : model

该属性保存用于在弹出菜单中显示搜索建议的数据模型。

SearchField {
    textRole: "age"
    suggestionModel: ListModel {
        ListElement { name: "Karen"; age: "66" }
        ListElement { name: "Jim"; age: "32" }
        ListElement { name: "Pamela"; age: "28" }
    }
}

另请参阅 textRole 。

text : string

该属性保存搜索栏中的当前输入文本。

文本与用户输入绑定，触发建议更新或搜索逻辑。

另请参阅 searchTriggered() 和textEdited()。

textRole : string

此属性保存用于在弹出列表中显示建议模型中的项目的模型角色。

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

信号文档

void accepted()

当用户按 Enter 或 Return 键确认输入时，就会发出该信号。

该信号通常用于根据最终输入的文本触发搜索或操作，并表示用户有意完成或提交查询。

另请参阅 searchTriggered() 。

void activated(int index)

当index 中的项目被用户激活时，就会发出该信号。

当一个项目在弹出窗口打开时被选中并导致弹出窗口关闭（以及currentIndex 变更）时，该项目即被激活。currentIndex 属性被设置为index 。

另请参阅 currentIndex 。

void clearButtonPressed()

按下清除按钮时会发出该信号。

另请参阅 searchButtonPressed() 。

void highlighted(int index)

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

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

另请参阅 highlightedIndex 。

void searchButtonPressed()

按下搜索按钮时会发出该信号。

另请参阅 clearButtonPressed() 。

void searchTriggered()

该信号在搜索操作启动时发出。

有两种情况1.按下 Enter 或 Return 键时，它将与accepted() 信号一起发出 2.编辑文本时，如果live 属性设置为true ，则会发出该信号。

根据所需的交互模式，该信号非常适合在用户键入时按需或实时启动搜索。

另请参阅 accepted() 和textEdited()。

void textEdited()

每次用户修改搜索字段中的文本（通常是每次按键）时，都会发出该信号。

另请参阅 searchTriggered() 。