SearchField QML Type

Un champ de saisie spécialisé conçu pour être utilisé dans le cadre d'une fonction de recherche. Plus...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• 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

Signaux

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

Description détaillée

SearchField est un champ de saisie spécialisé conçu pour les fonctions de recherche. Le contrôle comprend un champ de texte, des icônes de recherche et d'effacement, ainsi qu'une fenêtre contextuelle qui affiche des suggestions ou des résultats de recherche.

Indicateurs de SearchField

SearchField propose deux boutons indicateurs intégrés facultatifs : searchIndicator et clearIndicator.

Il ne s'agit pas d'indicateurs au sens de BusyIndicator ou ProgressBar, mais de contrôles interactifs intégrés dans le champ (similaires aux boutons haut/bas de SpinBox). Une pression sur searchIndicator déclenche searchButtonPressed() et une pression sur clearIndicator déclenche clearButtonPressed().

En plus d'exposer les actions, les boutons indicateurs fournissent un état d'interaction (appuyé/ouvert/focalisé, etc.) qui peut être utilisé par les styles.

Personnalisation du contenu des indicateurs

Les propriétés searchIndicator et clearIndicator sont en lecture seule. La personnalisation est prise en charge par leurs propriétés internes.

En particulier, le contenu visuel du bouton est fourni par son élément indicator, qui est accessible en écriture. Cela permet de remplacer ou de supprimer entièrement le contenu par défaut.

Par exemple, pour supprimer les deux icônes de l'indicateur :

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

Il s'agit d'un scénario de personnalisation pris en charge. Différentes variantes du champ de recherche peuvent omettre l'un des boutons (par exemple, en ne fournissant qu'un bouton de recherche) ou remplacer le contenu de l'indicateur par un autre élément (par exemple, une icône de microphone pour déclencher la saisie vocale).

Rôles du modèle de SearchField

SearchField est en mesure de visualiser les modèles de données standard qui fournissent le rôle modelData:

• les modèles qui n'ont qu'un seul rôle
• les modèles qui n'ont pas de rôle nommé (tableau JavaScript, entier).

Lors de l'utilisation de modèles ayant plusieurs rôles nommés, SearchField doit être configuré pour utiliser un text role spécifique pour ses instances text et delegate.

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
}

Voir également searchIndicator, clearIndicator, searchButtonPressed() et clearButtonPressed().

Documentation sur les propriétés

clearIndicator group

Cette propriété groupée contient l'élément d'indicateur clearIndicator et ses propriétés associées.

Cette propriété contient l'indicateur clearIndicator. Le fait d'appuyer sur cette propriété déclenche clearButtonPressed().

Elle est exposée afin que les styles et les applications puissent la personnaliser par le biais de ses propriétés internes (par exemple, en remplaçant ou en supprimant le site clearIndicator via clearIndicator.indicator, ou en réagissant à l'état d'interaction tel que pressé et survolé).

Voir également SearchField's Indicators.

currentIndex : int

Cette propriété contient l'index de la suggestion actuellement sélectionnée dans la liste déroulante.

Sa valeur est -1 lorsqu'aucune suggestion n'est sélectionnée.

currentIndex n'est pas modifié automatiquement lorsque le modèle change ou lorsque l'utilisateur tape ou édite du texte. Il n'est mis à jour que lorsque l'utilisateur sélectionne explicitement une suggestion, soit en cliquant sur un élément de la liste déroulante, soit en appuyant sur la touche Entrée d'un élément en surbrillance.

currentIndex peut être défini, par exemple, pour afficher le premier élément du modèle au démarrage. Avant cela, assurez-vous que le modèle n'est pas vide :

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

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

Voir également activated(), text, et highlightedIndex.

delegate : Component

Cette propriété contient un délégué qui présente un élément dans la fenêtre contextuelle du champ de recherche.

Il est recommandé d'utiliser ItemDelegate (ou tout autre dérivé de AbstractButton ) comme délégué. Cela garantit que l'interaction fonctionne comme prévu et que la fenêtre contextuelle se ferme automatiquement le cas échéant. Lorsque d'autres types sont utilisés comme délégués, la fenêtre contextuelle doit être fermée manuellement. Par exemple, si MouseArea est utilisé :

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

Depuis Qt 6.11, SearchField ne prend pas possession du délégué.

delegateModel : model [read-only]

Cette propriété contient le modèle qui fournit des instances de délégués pour le champ de recherche.

Elle est généralement attribuée à un ListView dans le contentItem du popup.

highlightedIndex : int [read-only]

Cette propriété contient l'index de l'élément actuellement mis en évidence dans la liste déroulante.

Lorsque l'élément mis en évidence est activé, la fenêtre contextuelle se ferme, currentIndex est mis à jour pour correspondre à highlightedIndex, et cette propriété est réinitialisée à -1, ce qui indique qu'aucun élément n'est actuellement mis en évidence.

Voir également highlighted() et currentIndex.

live : bool

Cette propriété contient une valeur booléenne qui détermine si la recherche est déclenchée à chaque modification de texte.

Lorsque cette propriété vaut true, le signal searchTriggered() est émis à chaque modification du texte, ce qui vous permet de réagir à chaque frappe. Si la valeur est false, le signal searchTriggered() n'est émis que lorsque l'utilisateur appuie sur la touche Entrée ou Retour.

Voir également searchTriggered().

popup : Popup

Cette propriété contient la fenêtre contextuelle.

La fenêtre contextuelle peut être ouverte ou fermée manuellement, si nécessaire :

onSpecialEvent: searchField.popup.close()

searchIndicator group

Cette propriété groupée contient l'élément d'indicateur searchIndicator et ses propriétés associées.

Cette propriété contient l'indicateur de recherche. Le fait d'appuyer sur cet indicateur déclenche searchButtonPressed().

Elle est exposée pour que les styles et les applications puissent la personnaliser par le biais de ses propriétés internes (par exemple, en remplaçant ou en supprimant le site searchIndicator via searchIndicator.indicator, ou en réagissant à l'état d'interaction tel que pressé et survolé).

Voir également SearchField's Indicators.

suggestionCount : int [read-only]

Cette propriété indique le nombre de suggestions à afficher à partir du modèle de suggestion.

suggestionModel : model

Cette propriété contient le modèle de données utilisé pour afficher les suggestions de recherche dans le menu contextuel.

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

Voir aussi textRole.

text : string

Cette propriété contient le texte actuellement saisi dans le champ de recherche.

Le texte est lié à la saisie de l'utilisateur, ce qui déclenche la mise à jour des suggestions ou la logique de recherche.

Voir également searchTriggered() et textEdited().

textRole : string

Cette propriété contient le rôle du modèle utilisé pour afficher les éléments du modèle de suggestion figurant dans la liste déroulante.

Lorsque le modèle a plusieurs rôles, textRole peut être défini pour déterminer quel rôle doit être affiché.

Documentation sur les signaux

void accepted()

Ce signal est émis lorsque l'utilisateur confirme sa saisie en appuyant sur la touche Entrée ou Retour.

Ce signal est généralement utilisé pour déclencher une recherche ou une action sur la base du texte final saisi, et il indique l'intention de l'utilisateur de terminer ou de soumettre la requête.

Voir également searchTriggered().

void activated(int index)

Ce signal est émis lorsque l'élément situé à l'adresse index est activé par l'utilisateur.

Un élément est activé lorsqu'il est sélectionné alors que la fenêtre contextuelle est ouverte, ce qui entraîne la fermeture de la fenêtre (et la modification de currentIndex ). La propriété currentIndex est remplacée par index.

Voir également currentIndex.

void clearButtonPressed()

Ce signal est émis lorsque l'on appuie sur le bouton d'effacement.

Voir également searchButtonPressed().

void highlighted(int index)

Ce signal est émis lorsque l'élément situé à index dans la liste popup est mis en évidence par l'utilisateur.

Ce signal n'est émis que lorsque la fenêtre contextuelle est ouverte et qu'un élément est mis en évidence, mais pas nécessairement activated.

Voir également highlightedIndex.

void searchButtonPressed()

Ce signal est émis lorsque le bouton de recherche est enfoncé.

Voir aussi clearButtonPressed().

void searchTriggered()

Ce signal est émis lorsqu'une action de recherche est lancée.

Il se produit dans deux cas : 1. Lorsque l'on appuie sur la touche Entrée ou Retour, ce signal est émis en même temps que le signal accepted(). 2. Lorsque le texte est modifié et que la propriété live est définie sur true, ce signal est émis.

Ce signal est idéal pour lancer des recherches à la fois à la demande et en temps réel au fur et à mesure que l'utilisateur tape, en fonction du modèle d'interaction souhaité.

Voir également accepted() et textEdited().

void textEdited()

Ce signal est émis chaque fois que l'utilisateur modifie le texte dans le champ de recherche, typiquement à chaque frappe de touche.

Voir également searchTriggered().