SearchField QML Type

Un campo de entrada especializado diseñado para su uso en la función de búsqueda. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• 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

Señales

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

Descripción detallada

SearchField es un campo de entrada especializado diseñado para la funcionalidad de búsqueda. El control incluye un campo de texto, iconos de búsqueda y de borrado, y una ventana emergente que muestra sugerencias o resultados de búsqueda.

Indicadores de SearchField

SearchField proporciona dos botones indicadores integrados opcionales: searchIndicator y clearIndicator.

No se trata de indicadores en el sentido de BusyIndicator o ProgressBar, sino de controles interactivos integrados en el campo (similares a los botones arriba/abajo de SpinBox). Al pulsar searchIndicator se activa searchButtonPressed(), y al pulsar clearIndicator se activa clearButtonPressed().

Además de exponer las acciones, los botones indicadores proporcionan un estado de interacción (pulsado/movido/enfocado, etc.) que puede ser utilizado por los estilos.

Personalización del contenido de los indicadores

Las propiedades searchIndicator y clearIndicator son de sólo lectura. La personalización se realiza a través de sus propiedades internas.

En particular, el contenido visual del botón es proporcionado por su elemento indicator, que es escribible. Esto permite sustituir o eliminar por completo el contenido predeterminado.

Por ejemplo, para eliminar los dos iconos indicadores:

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

Este es un escenario de personalización soportado. Las distintas variantes de SearchField pueden omitir uno de los botones (por ejemplo, proporcionar sólo un botón de búsqueda) o sustituir el contenido del indicador por un elemento alternativo (por ejemplo, un icono de micrófono para activar la entrada de voz).

Funciones del modelo SearchField

SearchField es capaz de visualizar modelos de datos estándar que proporcionan el rol modelData:

• modelos que sólo tienen un rol
• modelos que no tienen roles con nombre (matriz JavaScript, entero)

Cuando se utilizan modelos que tienen varios roles con nombre, SearchField debe configurarse para utilizar un text role específico para sus instancias text y 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
}

Véase también searchIndicator, clearIndicator, searchButtonPressed(), y clearButtonPressed().

Documentación de propiedades

clearIndicator group

Esta propiedad agrupada contiene el elemento indicador clearIndicator y sus propiedades asociadas.

Esta propiedad contiene el indicador clear. Al pulsarlo se activa clearButtonPressed().

Está expuesta para que los estilos y las aplicaciones puedan personalizarla a través de sus propiedades internas (por ejemplo, sustituyendo o eliminando el clearIndicator a través de clearIndicator.indicator, o reaccionando al estado de interacción como pulsado y hovered).

Véase también SearchField's Indicators.

currentIndex : int

Esta propiedad contiene el índice de la sugerencia actualmente seleccionada en la lista desplegable.

Su valor es -1 cuando no hay ninguna sugerencia seleccionada.

currentIndex no se modifica automáticamente cuando cambia el modelo o cuando el usuario escribe o edita texto. Sólo se actualiza cuando el usuario selecciona explícitamente una sugerencia, ya sea haciendo clic en un elemento de la lista emergente o pulsando Intro en un elemento resaltado.

currentIndex puede establecerse; por ejemplo, para mostrar el primer elemento del modelo al inicio. Antes de hacerlo, asegúrese de que el modelo no está vacío:

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

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

Véase también activated(), text, y highlightedIndex.

delegate : Component

Esta propiedad contiene un delegado que presenta un elemento en la ventana emergente del campo de búsqueda.

Se recomienda utilizar ItemDelegate (o cualquier otro derivado de AbstractButton ) como delegado. Esto asegura que la interacción funcione como se espera, y la ventana emergente se cerrará automáticamente cuando sea apropiado. Cuando se utilizan otros tipos como delegado, la ventana emergente debe cerrarse manualmente. Por ejemplo, si se utiliza MouseArea:

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

Desde Qt 6.11, SearchField no se apropia del delegado.

delegateModel : model [read-only]

Esta propiedad contiene el modelo que proporciona instancias delegadas para el campo de búsqueda.

Normalmente se asigna a un ListView en el contentItem del popup.

highlightedIndex : int [read-only]

Esta propiedad contiene el índice del elemento resaltado actualmente en la lista emergente.

Cuando se activa el elemento resaltado, la ventana emergente se cierra, currentIndex se actualiza para coincidir con highlightedIndex, y esta propiedad se restablece a -1, indicando que no hay ningún elemento resaltado actualmente.

Véase también highlighted() y currentIndex.

live : bool

Esta propiedad contiene un valor booleano que determina si la búsqueda se activa en cada edición de texto.

Cuando se establece en true, la señal searchTriggered() se emite en cada cambio de texto, lo que permite responder a cada pulsación de tecla. Si está configurado como false, la señal searchTriggered() sólo se emite cuando el usuario pulsa la tecla Intro o Retorno.

Véase también searchTriggered().

popup : Popup

Esta propiedad contiene la ventana emergente.

La ventana emergente puede abrirse o cerrarse manualmente, si es necesario:

onSpecialEvent: searchField.popup.close()

searchIndicator group

Esta propiedad agrupada contiene el elemento indicador searchIndicator y sus propiedades asociadas.

Esta propiedad contiene el indicador de búsqueda. Al pulsarlo se activa searchButtonPressed().

Está expuesta para que los estilos y las aplicaciones puedan personalizarla a través de sus propiedades internas (por ejemplo, sustituyendo o eliminando el searchIndicator a través de searchIndicator.indicator, o reaccionando al estado de interacción como pulsado y hovered).

Véase también SearchField's Indicators.

suggestionCount : int [read-only]

Esta propiedad contiene el número de sugerencias a mostrar del modelo de sugerencias.

suggestionModel : model

Esta propiedad contiene el modelo de datos utilizado para mostrar sugerencias de búsqueda en el menú emergente.

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

Véase también textRole.

text : string

Esta propiedad contiene el texto introducido en el campo de búsqueda.

El texto se vincula a la entrada del usuario, activando actualizaciones de sugerencias o lógica de búsqueda.

Véase también searchTriggered() y textEdited().

textRole : string

Esta propiedad contiene el rol del modelo utilizado para mostrar los elementos en el modelo de sugerencia mostrado en la lista emergente.

Cuando el modelo tiene varios roles, se puede establecer textRole para determinar qué rol se debe mostrar.

Documentación de la señal

void accepted()

Esta señal se emite cuando el usuario confirma su entrada pulsando la tecla Intro o Retorno.

Esta señal se utiliza normalmente para desencadenar una búsqueda o acción basada en el texto final introducido, e indica la intención del usuario de completar o enviar la consulta.

Véase también searchTriggered().

void activated(int index)

Esta señal se emite cuando el elemento en index es activado por el usuario.

Un elemento se activa cuando se selecciona mientras la ventana emergente está abierta, lo que provoca el cierre de la ventana (y el cambio de currentIndex ). La propiedad currentIndex se establece en index.

Véase también currentIndex.

void clearButtonPressed()

Esta señal se emite cuando se pulsa el botón de borrar.

Véase también searchButtonPressed().

void highlighted(int index)

Esta señal se emite cuando el usuario resalta el elemento que aparece en index en la lista emergente.

La señal de resaltado sólo se emite cuando la ventana emergente está abierta y un elemento está resaltado, pero no necesariamente activated.

Véase también highlightedIndex.

void searchButtonPressed()

Esta señal se emite cuando se pulsa el botón de búsqueda.

Véase también clearButtonPressed().

void searchTriggered()

Esta señal se emite cuando se inicia una acción de búsqueda.

Se produce en dos casos: 1. Cuando se pulsa la tecla Intro o Retorno, se emitirá junto con la señal accepted() 2. Cuando se edita el texto y si la propiedad live está establecida en true, se emitirá esta señal.

Esta señal es ideal para iniciar búsquedas tanto bajo demanda como en tiempo real a medida que el usuario teclea, dependiendo del modelo de interacción deseado.

Véase también accepted() y textEdited().

void textEdited()

Esta señal se emite cada vez que el usuario modifica el texto del campo de búsqueda, normalmente con cada pulsación de tecla.

Véase también searchTriggered().