SearchField QML Type

Ein spezielles Eingabefeld, das für die Suchfunktion vorgesehen ist. Mehr...

• Liste aller Elemente, einschließlich vererbter Elemente

Eigenschaften

• 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

Signale

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

Methoden

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

Ausführliche Beschreibung

SearchField ist ein spezielles Eingabefeld, das für Suchfunktionen konzipiert ist. Das Steuerelement umfasst ein Textfeld, Symbole zum Suchen und Löschen sowie ein Popup-Fenster, in dem Vorschläge oder Suchergebnisse angezeigt werden.

Anzeigen von SearchField

SearchField bietet zwei optionale, integrierte Anzeigeschaltflächen: „ searchIndicator “ und „ clearIndicator “.

Dabei handelt es sich nicht um Indikatoren im Sinne von „ BusyIndicator “ oder „ ProgressBar “. Stattdessen sind es interaktive Steuerelemente, die in das Feld eingebettet sind (ähnlich den Auf-/Ab-Schaltflächen in „ SpinBox “). Das Drücken von „ searchIndicator “ löst „ searchButtonPressed “ aus, und das Drücken von „ clearIndicator “ löst „ clearButtonPressed “ aus.

Zusätzlich zur Bereitstellung der Aktionen liefern die Indikator-Schaltflächen Interaktionszustände (gedrückt/mit der Maus darüber, im Fokus usw.), die von Stilen genutzt werden können.

Anpassen des Inhalts der Indikatoren

Die Eigenschaften „ searchIndicator “ und „ clearIndicator “ sind schreibgeschützt. Die Anpassung erfolgt über ihre internen Eigenschaften.

Insbesondere wird der visuelle Inhalt der Schaltfläche durch das Element „ indicator “ bereitgestellt, das beschreibbar ist. Dadurch kann der Standardinhalt ersetzt oder vollständig entfernt werden.

Beispiel: So entfernen Sie beide Symbol-Icons:

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

Dies ist ein unterstütztes Anpassungsszenario. Verschiedene „SearchField“-Varianten können eine der Schaltflächen weglassen (z. B. nur eine Suchschaltfläche bereitstellen) oder den Inhalt der Anzeigen durch ein alternatives Element ersetzen (z. B. ein Mikrofonsymbol zum Auslösen der Spracheingabe).

SearchField-Modellrollen

„SearchField“ kann Standarddatenmodelle visualisieren, die die Rolle „ modelData “ bereitstellen:

• Modelle, die nur eine Rolle haben
• Modelle, die keine benannten Rollen haben (JavaScript-Array, Ganzzahl)

Bei der Verwendung von Modellen mit mehreren benannten Rollen muss „SearchField“ so konfiguriert werden, dass es für seine Instanzen „ text “ und „ delegate “ ein bestimmtes „ text role “ verwendet.

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
}

Siehe auch „ searchIndicator“ , „ clearIndicator “, „ searchButtonPressed “ und „ clearButtonPressed “.

Dokumentation zu den Eigenschaften

clearIndicator group

Diese gruppierte Eigenschaft enthält das Indikatorelement „clearIndicator“ und die dazugehörigen Eigenschaften.

Diese Eigenschaft enthält den „Clear“-Indikator. Durch Drücken dieses Indikators wird „ clearButtonPressed “ ausgelöst.

Sie wird bereitgestellt, damit Stile und Anwendungen sie über ihre internen Eigenschaften anpassen können (beispielsweise durch Ersetzen oder Entfernen des „ clearIndicator “ über „ clearIndicator.indicator “ oder durch Reagieren auf Interaktionszustände wie „gedrückt“ und „Mauszeiger darüber“).

Siehe auch „ SearchField's Indicators “.

currentIndex : int

Diese Eigenschaft enthält den Index des aktuell ausgewählten Vorschlags in der Popup-Liste.

Ihr Wert ist „ -1 “, wenn kein Vorschlag ausgewählt ist.

„currentIndex“ wird nicht automatisch geändert, wenn sich das Modell ändert oder wenn der Benutzer Text eingibt oder bearbeitet. Er wird nur aktualisiert, wenn der Benutzer explizit einen Vorschlag auswählt, entweder durch Klicken auf ein Element im Popup oder durch Drücken der Eingabetaste bei einem markierten Element.

„currentIndex“ kann gesetzt werden, beispielsweise um beim Start das erste Element im Modell anzuzeigen. Stellen Sie zuvor sicher, dass das Modell nicht leer ist:

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

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

Siehe auch ` activated()`, ` text` und ` highlightedIndex`.

cursorPosition : int [since 6.12]

Die Position des Cursors im Textfeld. Der Cursor befindet sich zwischen Zeichen.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

delegate : Component

Diese Eigenschaft enthält einen Delegaten, der ein Element im Popup-Fenster des Suchfelds anzeigt.

Es wird empfohlen, ` ItemDelegate ` (oder ein anderes Derivat von ` AbstractButton `) als Delegat zu verwenden. Dadurch wird sichergestellt, dass die Interaktion wie erwartet funktioniert und sich das Popup bei Bedarf automatisch schließt. Werden andere Typen als Delegat verwendet, muss das Popup manuell geschlossen werden. Wenn beispielsweise ` MouseArea ` verwendet wird:

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

Seit Qt 6.11 übernimmt „ SearchField “ nicht mehr die Eigentümerschaft des Delegaten.

delegateModel : model [read-only]

Diese Eigenschaft enthält das Modell, das Delegat-Instanzen für das Suchfeld bereitstellt.

Sie wird in der Regel im „ contentItem “ des „ popup “ einem „ ListView “ zugewiesen.

highlightedIndex : int [read-only]

Diese Eigenschaft enthält den Index des aktuell markierten Elements in der Popup-Liste.

Wenn der markierte Eintrag aktiviert wird, wird das Popup geschlossen, „ currentIndex “ wird entsprechend „ highlightedIndex “ aktualisiert und diese Eigenschaft wird auf „ -1 “ zurückgesetzt, was anzeigt, dass derzeit kein Eintrag markiert ist.

Siehe auch highlighted() und currentIndex.

live : bool

Diese Eigenschaft enthält einen booleschen Wert, der festlegt, ob die Suche bei jeder Textänderung ausgelöst wird.

Bei der Einstellung „ true “ wird das Signal „ searchTriggered()“ bei jeder Textänderung ausgegeben, sodass Sie auf jeden Tastenanschlag reagieren können. Bei der Einstellung „ false “ wird das Signal „ searchTriggered()“ nur ausgegeben, wenn der Benutzer die Eingabetaste oder die Return-Taste drückt.

Siehe auch searchTriggered().

placeholderText : string [since 6.12]

Diese Eigenschaft enthält den Hinweis, der im Feld „ SearchField “ angezeigt wird, bevor der Benutzer Text eingibt.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

popup : Popup

Diese Eigenschaft enthält das Popup-Fenster.

Das Popup-Fenster kann bei Bedarf manuell geöffnet oder geschlossen werden:

onSpecialEvent: searchField.popup.close()

searchIndicator group

Diese gruppierte Eigenschaft enthält das Indikatorelement „searchIndicator“ und die dazugehörigen Eigenschaften.

Diese Eigenschaft enthält den Suchindikator. Durch Anklicken wird „ searchButtonPressed “ ausgelöst.

Sie ist öffentlich zugänglich, sodass Stile und Anwendungen sie über ihre internen Eigenschaften anpassen können (z. B. durch Ersetzen oder Entfernen des „ searchIndicator “ über „ searchIndicator.indicator “ oder durch Reagieren auf Interaktionszustände wie „gedrückt“ und „Mauszeiger darüber“).

Siehe auch „ SearchField's Indicators “.

selectTextByMouse : bool [since 6.12]

Diese Eigenschaft legt fest, ob der Text mit der Maus ausgewählt werden kann.

Der Standardwert ist „ true “.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

selectedText : string [read-only, since 6.12]

Diese schreibgeschützte Eigenschaft enthält den aktuell ausgewählten Text.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

selectionEnd : int [read-only, since 6.12]

Die Cursorposition nach dem letzten Zeichen der aktuellen Auswahl.

Diese Eigenschaft ist schreibgeschützt. Um die Auswahl zu ändern, verwenden Sie „select(start, end)“, „ selectAll()“ oder „ selectWord()“.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

Siehe auch ` selectionStart`, ` cursorPosition` und ` selectedText`.

selectionStart : int [read-only, since 6.12]

Die Cursorposition vor dem ersten Zeichen der aktuellen Auswahl.

Diese Eigenschaft ist schreibgeschützt. Um die Auswahl zu ändern, verwenden Sie `select(start, end)`, ` selectAll()` oder ` selectWord()`.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

Siehe auch ` selectionEnd`, ` cursorPosition` und ` selectedText`.

suggestionCount : int [read-only]

Diese Eigenschaft gibt die Anzahl der Vorschläge an, die aus dem Vorschlagsmodell angezeigt werden sollen.

suggestionModel : model

Diese Eigenschaft enthält das Datenmodell, das zur Anzeige von Suchvorschlägen im Popup-Menü verwendet wird.

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

Siehe auch „ textRole “.

text : string

Diese Eigenschaft enthält den aktuellen Eingabetext im Suchfeld.

Der Text ist an die Benutzereingabe gebunden und löst Aktualisierungen der Vorschläge oder die Suchlogik aus.

Siehe auch searchTriggered() und textEdited().

textRole : string

Diese Eigenschaft enthält die Modellrolle, die zur Anzeige von Elementen im Vorschlagsmodell verwendet wird, das in der Popup-Liste angezeigt wird.

Wenn das Modell mehrere Rollen hat, kann „ textRole “ festgelegt werden, um zu bestimmen, welche Rolle angezeigt werden soll.

Signal-Dokumentation

void accepted()

Dieses Signal wird ausgelöst, wenn der Benutzer seine Eingabe durch Drücken der Enter- oder Return-Taste bestätigt.

Dieses Signal wird in der Regel verwendet, um eine Suche oder Aktion auf der Grundlage der endgültigen Texteingabe auszulösen, und es zeigt die Absicht des Benutzers an, die Abfrage abzuschließen oder zu übermitteln.

Siehe auch searchTriggered().

void activated(int index)

Dieses Signal wird ausgelöst, wenn das Element unter index vom Benutzer aktiviert wird.

Ein Element wird aktiviert, wenn es bei geöffnetem Popup ausgewählt wird, wodurch sich das Popup schließt (und sich currentIndex ändert). Die Eigenschaft „ currentIndex “ wird auf „ index “ gesetzt.

Siehe auch „ currentIndex “.

void clearButtonPressed()

Dieses Signal wird beim Drücken der Löschtaste ausgegeben.

Siehe auch searchButtonPressed().

void highlighted(int index)

Dieses Signal wird ausgelöst, wenn der Eintrag unter index in der Popup-Liste vom Benutzer markiert wird.

Das Signal „highlighted“ wird nur ausgelöst, wenn das Popup geöffnet ist und ein Eintrag markiert wird, jedoch nicht unbedingt „ activated “.

Siehe auch „ highlightedIndex “.

void searchButtonPressed()

Dieses Signal wird ausgelöst, wenn die Suchschaltfläche gedrückt wird.

Siehe auch clearButtonPressed().

void searchTriggered()

Dieses Signal wird ausgegeben, wenn eine Suchaktion gestartet wird.

Es tritt in zwei Fällen auf: 1. Wenn die Eingabetaste (Enter oder Return) gedrückt wird, wird es zusammen mit dem Signal „ accepted “ () ausgelöst. 2. Wenn der Text bearbeitet wird und die Eigenschaft „ live “ auf „ true “ gesetzt ist, wird dieses Signal ausgelöst.

Dieses Signal eignet sich ideal zum Auslösen von Suchvorgängen sowohl auf Abruf als auch in Echtzeit während der Eingabe durch den Benutzer, je nach gewünschtem Interaktionsmodell.

Siehe auch „ accepted()“ und „ textEdited()“.

void textEdited()

Dieses Signal wird jedes Mal ausgelöst, wenn der Benutzer den Text im Suchfeld ändert, in der Regel bei jedem Tastendruck.

Siehe auch searchTriggered().

Methodendokumentation

[since 6.12] void deselect()

Hebt die aktive Textauswahl auf.

Diese Methode wurde in Qt 6.12 eingeführt.

Siehe auch selectedText, selectionStart und selectionEnd.

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

Bewirkt, dass der Text von start bis end ausgewählt wird.

Liegt entweder start oder end außerhalb des Bereichs, wird die Auswahl nicht geändert.

Nach dem Aufruf dieser Methode wird selectionStart zum kleineren und selectionEnd zum größeren Wert (unabhängig von der Reihenfolge, in der die Parameter an diese Methode übergeben wurden).

Diese Methode wurde in Qt 6.12 eingeführt.

Siehe auch „ selectionStart “ und „ selectionEnd “.

[since 6.12] void selectAll()

Wählt den gesamten Text im Textfeld des Steuerelements aus.

Diese Methode wurde in Qt 6.12 eingeführt.

[since 6.12] void selectWord()

Wählt das Wort aus, das der aktuellen Cursorposition am nächsten liegt.

Diese Methode wurde in Qt 6.12 eingeführt.

Siehe auch cursorPosition und selectedText.