SearchField QML Type

一个专为搜索功能设计的专用输入框。更多...

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

属性

• clearIndicator
  • clearIndicator.hovered : bool
  • clearIndicator.implicitIndicatorHeight : real
  • clearIndicator.implicitIndicatorWidth : real
  • clearIndicator.indicator : Item
  • clearIndicator.pressed : bool
• currentIndex : int
• cursorPosition : int (since 6.12)
• delegate : Component
• delegateModel : model
• highlightedIndex : int
• live : bool
• placeholderText : string (since 6.12)
• popup : Popup
• searchIndicator
  • searchIndicator.hovered : bool
  • searchIndicator.implicitIndicatorHeight : real
  • searchIndicator.implicitIndicatorWidth : real
  • searchIndicator.indicator : Item
  • searchIndicator.pressed : bool
• selectTextByMouse : bool (since 6.12)
• selectedText : string (since 6.12)
• selectionEnd : int (since 6.12)
• selectionStart : int (since 6.12)
• 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()

方法

• void deselect() (since 6.12)
• void select(int start, int end) (since 6.12)
• void selectAll() (since 6.12)
• void selectWord() (since 6.12)

详细说明

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
    sourceModel: fruitModel
    sorters: [
        RoleSorter {
            roleName: "name"
        }
    ]
    filters: [
        FunctionFilter {
            property var regExp: new RegExp(fruitSearch.text, "i")
            onRegExpChanged: invalidate()
            function filter(name: string): bool {
                return regExp.test(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 不会自动修改。只有当用户通过点击弹出列表中的项目，或在高亮显示的项目上按 Enter 键，明确选中一个建议项时，它才会更新。

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 。

cursorPosition : int [since 6.12]

文本框中光标的位置。光标位于字符之间。

该属性在 Qt 6.12 中引入。

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 时，searchTriggered()仅在用户按下Enter或Return键时触发。

另请参阅 searchTriggered()。

placeholderText : string [since 6.12]

该属性存储在用户输入文本之前，在SearchField 中显示的提示信息。

该属性于 Qt 6.12 版本中引入。

popup : Popup

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

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

onSpecialEvent: searchField.popup.close()

searchIndicator group

此分组属性包含搜索指示器（searchIndicator）及其相关属性。

该属性包含搜索指示器。点击它将触发searchButtonPressed 。

该属性对外公开，以便样式和应用程序能够通过其内部属性对其进行自定义（例如，通过 `searchIndicator.indicator` 替换或移除 `searchIndicator `，或响应“按下”和“悬停”等交互状态）。

另请参阅 SearchField's Indicators 。

selectTextByMouse : bool [since 6.12]

该属性控制文本是否可以使用鼠标进行选择。

默认值为true 。

该属性在 Qt 6.12 中引入。

selectedText : string [read-only, since 6.12]

此只读属性保存当前选中的文本。

该属性于 Qt 6.12 版本中引入。

selectionEnd : int [read-only, since 6.12]

光标位于当前选区最后一个字符之后的位置。

该属性为只读。若要更改选区，请使用 select(start, end)、selectAll() 或selectWord()。

该属性自 Qt 6.12 起引入。

另请参阅 selectionStart 、cursorPosition 以及selectedText 。

selectionStart : int [read-only, since 6.12]

光标位于当前选区第一个字符之前的的位置。

该属性为只读。若要更改选区，请使用 select(start, end)、selectAll() 或selectWord()。

该属性自 Qt 6.12 起引入。

另请参阅 selectionEnd 、cursorPosition 和selectedText 。

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 ` 来确定应显示哪个角色。

Signal 文档

void accepted()

当用户按下回车键或Return键确认输入时，会触发此信号。

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

另请参阅 searchTriggered()。

void activated(int index)

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

当弹出窗口打开时，若选中某个项目，该项目即被激活，从而导致弹出窗口关闭（且currentIndex 发生变化）。currentIndex 属性被设置为index 。

另请参阅 currentIndex 。

void clearButtonPressed()

按下“清除”按钮时会发出此信号。

另请参阅 searchButtonPressed()。

void highlighted(int index)

当用户选中弹出列表中位于index 的项目时，会触发此信号。

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

另请参阅 highlightedIndex 。

void searchButtonPressed()

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

另请参阅 clearButtonPressed()。

void searchTriggered()

当启动搜索操作时，会发出此信号。

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

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

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

void textEdited()

每当用户修改搜索框中的文本时（通常是每次按键时），都会触发此信号。

另请参阅 searchTriggered()。

方法文档

[since 6.12] void deselect()

取消当前选中的文本。

该方法在 Qt 6.12 中引入。

另请参阅 selectedText 、selectionStart 以及selectionEnd 。

[since 6.12] void select(int start, int end)

将start 至end 之间的文本选中。

如果start 或end 超出范围，则选定内容不会发生变化。

调用此方法后，selectionStart 将成为较小值，selectionEnd 将成为较大值（无论传递给此方法的顺序如何）。

该方法在 Qt 6.12 中引入。

另请参阅 selectionStart 和selectionEnd 。

[since 6.12] void selectAll()

选中控件文本框中的所有文本。

该方法于 Qt 6.12 版本中引入。

[since 6.12] void selectWord()

选中距离当前光标位置最近的单词。

该方法自 Qt 6.12 起引入。

另请参阅 cursorPosition 和selectedText 。