SearchField QML Type
Un campo de entrada especializado diseñado para la función de búsqueda. Más...
| Import Statement: | import QtQuick.Controls |
| Since: | Qt 6.10 |
| Inherits: |
Propiedades
- 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
Señales
- void accepted()
- void activated(int index)
- void clearButtonPressed()
- void highlighted(int index)
- void searchButtonPressed()
- void searchTriggered()
- void textEdited()
Métodos
- void deselect()
(since 6.12) - void select(int start, int end)
(since 6.12) - void selectAll()
(since 6.12) - void selectWord()
(since 6.12)
Descripción detallada
SearchField es un campo de entrada especializado diseñado para la función de búsqueda. El control incluye un campo de texto, iconos de búsqueda y borrado, y una ventana emergente que muestra sugerencias o resultados de búsqueda.
Nota: El estilo iOS no proporciona una ventana emergente integrada para SearchField con el fin de conservar el aspecto y el comportamiento nativos. Si aún así se desea una ventana emergente, el usuario deberá definirla.
Indicadores de SearchField
SearchField ofrece dos botones indicadores integrados opcionales: searchIndicator y clearIndicator.
No se trata de indicadores en el sentido de BusyIndicator o ProgressBar. Más bien, son controles interactivos integrados en el campo (similares a los botones de arriba/abajo de SpinBox). Al pulsar searchIndicator se activa searchButtonPressed, y al pulsar clearIndicator se activa clearButtonPressed.
Además de mostrar las acciones, los botones indicadores proporcionan un estado de interacción (pulsado/al pasar el cursor/enfocado, etc.) que puede utilizarse en los estilos.
Personalización del contenido de los indicadores
Las propiedades searchIndicator y clearIndicator son de solo lectura. La personalización se realiza a través de sus propiedades internas.
En concreto, el contenido visual del botón lo proporciona su elemento indicator, que es modificable. Esto permite sustituir el contenido predeterminado o eliminarlo por completo.
Por ejemplo, para eliminar ambos iconos indicadores:
SearchField {
searchIndicator.indicator: null
clearIndicator.indicator: null
}Este es un caso de personalización admitido. Las diferentes variantes de SearchField pueden omitir uno de los botones (por ejemplo, mostrando solo 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).
Roles del modelo SearchField
SearchField es capaz de visualizar modelos de datos estándar que proporcionan la función « modelData »:
- modelos que solo tienen una función
- modelos que no tienen roles con nombre (matriz de 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
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
}Véase también searchIndicator, clearIndicator, searchButtonPressed y clearButtonPressed.
Documentación de propiedades
clearIndicator group
clearIndicator.hovered : bool
clearIndicator.implicitIndicatorHeight : real
clearIndicator.implicitIndicatorWidth : real
clearIndicator.indicator : Item
clearIndicator.pressed : bool
Esta propiedad agrupada contiene el elemento indicador «clearIndicator» y sus propiedades asociadas.
Esta propiedad contiene el indicador de borrado. Al pulsarlo, se activa « clearButtonPressed ».
Se expone para que los estilos y las aplicaciones puedan personalizarla a través de sus propiedades internas (por ejemplo, sustituyendo o eliminando el ` clearIndicator ` mediante ` clearIndicator.indicator`, o reaccionando a estados de interacción como «pulsado» y «al pasar el cursor»).
Véase también SearchField's Indicators.
currentIndex : int
Esta propiedad contiene el índice de la sugerencia seleccionada actualmente en la lista emergente.
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. Solo se actualiza cuando el usuario selecciona explícitamente una sugerencia, ya sea haciendo clic en un elemento de la ventana emergente o pulsando Intro sobre un elemento resaltado.
Se puede establecer el valor de `currentIndex`; por ejemplo, para mostrar el primer elemento del modelo al iniciar la aplicación. Antes de hacerlo, asegúrate 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.
cursorPosition : int [since 6.12]
La posición del cursor en el campo de texto. El cursor se sitúa entre caracteres.
Nota: En este caso,los caracteres se refieren a la cadena de objetos « QChar », es decir, caracteres Unicode de 16 bits, y la posición se considera un índice dentro de esta cadena. Esto no se corresponde necesariamente con grafemas individuales del sistema de escritura, ya que un solo grafema puede estar representado por varios caracteres Unicode, como en el caso de los pares sustitutos, las ligaduras lingüísticas o los signos diacríticos.
Esta propiedad se introdujo en Qt 6.12.
delegate : Component
Esta propiedad contiene un delegado que muestra un elemento en la ventana emergente del campo de búsqueda.
Se recomienda utilizar ` ItemDelegate ` (o cualquier otro derivado de ` AbstractButton `) como delegado. Esto garantiza que la interacción funcione según lo esperado y que la ventana emergente se cierre automáticamente cuando sea necesario. Si se utilizan otros tipos como delegado, la ventana emergente deberá cerrarse manualmente. Por ejemplo, si se utiliza ` MouseArea `:
delegate: Rectangle {
// ...
MouseArea {
// ...
onClicked: searchField.popup.close()
}
}Desde Qt 6.11, SearchField no asume la propiedad del delegado.
delegateModel : model [read-only]
Esta propiedad contiene el modelo que proporciona instancias de delegado 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 actualmente resaltado en la lista emergente.
Cuando se activa el elemento resaltado, el menú emergente se cierra, currentIndex se actualiza para que coincida con highlightedIndex y esta propiedad se restablece a -1, lo que indica que actualmente no hay ningún elemento resaltado.
Véase también highlighted() y currentIndex.
live : bool
Esta propiedad contiene un valor booleano que determina si la búsqueda se activa cada vez que se modifica el texto.
Cuando se establece en « true », la señal « searchTriggered()» se emite con cada cambio de texto, lo que permite responder a cada pulsación de tecla. Cuando se establece en « false », la señal « searchTriggered()» solo se emite cuando el usuario pulsa la tecla Intro o Retorno.
Véase también searchTriggered().
placeholderText : string [since 6.12]
Esta propiedad contiene la sugerencia que se muestra en el campo « SearchField » antes de que el usuario introduzca texto.
Esta propiedad se introdujo en Qt 6.12.
popup : Popup
Esta propiedad contiene la ventana emergente.
La ventana emergente se puede abrir o cerrar manualmente, si es necesario:
onSpecialEvent: searchField.popup.close()searchIndicator group
searchIndicator.hovered : bool
searchIndicator.implicitIndicatorHeight : real
searchIndicator.implicitIndicatorWidth : real
searchIndicator.indicator : Item
searchIndicator.pressed : bool
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.
Se expone para que los estilos y las aplicaciones puedan personalizarla a través de sus propiedades internas (por ejemplo, sustituyendo o eliminando el « searchIndicator » mediante « searchIndicator.indicator », o reaccionando a estados de interacción como «pulsado» y «al pasar el cursor»).
Véase también SearchField's Indicators.
selectTextByMouse : bool [since 6.12]
Esta propiedad indica si el texto se puede seleccionar con el ratón.
El valor por defecto es « true ».
Esta propiedad se introdujo en Qt 6.12.
selectedText : string [read-only, since 6.12]
Esta propiedad de solo lectura contiene el texto seleccionado actualmente.
Esta propiedad se introdujo en Qt 6.12.
selectionEnd : int [read-only, since 6.12]
La posición del cursor después del último carácter de la selección actual.
Esta propiedad es de solo lectura. Para modificar la selección, utiliza select(start, end), selectAll() o selectWord().
Esta propiedad se introdujo en Qt 6.12.
Véase también selectionStart, cursorPosition y selectedText.
selectionStart : int [read-only, since 6.12]
La posición del cursor antes del primer carácter de la selección actual.
Esta propiedad es de solo lectura. Para cambiar la selección, utiliza select(start, end), selectAll() o selectWord().
Esta propiedad se introdujo en Qt 6.12.
Véase también selectionEnd, cursorPosition y selectedText.
suggestionCount : int [read-only]
Esta propiedad contiene el número de sugerencias que se deben mostrar a partir del modelo de sugerencias.
suggestionModel : model
Esta propiedad contiene el modelo de datos que se utiliza para mostrar las 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 actualmente en el campo de búsqueda.
El texto está vinculado a la entrada del usuario, lo que activa las actualizaciones de las sugerencias o la lógica de búsqueda.
Véase también searchTriggered() y textEdited().
textRole : string
Esta propiedad contiene el rol del modelo que se utiliza para mostrar los elementos del modelo de sugerencias que aparecen en la lista emergente.
Cuando el modelo tiene varios roles, se puede configurar « textRole » para determinar qué rol se debe mostrar.
Documentación de Signal
void accepted()
Esta señal se emite cuando el usuario confirma lo que ha introducido pulsando la tecla «Intro» o «Retorno».
Esta señal se utiliza normalmente para activar una búsqueda o una acción basada en el texto introducido finalmente, e indica la intención del usuario de completar o enviar la consulta.
Nota: El controlador correspondiente es onAccepted.
Véase también searchTriggered().
void activated(int index)
Esta señal se emite cuando el usuario activa el elemento situado en index.
Un elemento se activa cuando se selecciona mientras la ventana emergente está abierta, lo que provoca que esta se cierre (y que cambie currentIndex ). La propiedad currentIndex se establece en index.
Nota: El controlador correspondiente es onActivated.
Véase también currentIndex.
void clearButtonPressed()
Esta señal se emite al pulsar el botón «Borrar».
Nota: El controlador correspondiente es onClearButtonPressed.
Véase también searchButtonPressed().
void highlighted(int index)
Esta señal se emite cuando el usuario resalta el elemento situado en index de la lista emergente.
La señal «highlighted» solo se emite cuando el menú emergente está abierto y se ha resaltado un elemento, pero no necesariamente « activated ».
Nota: El controlador correspondiente es « onHighlighted ».
Véase también « highlightedIndex ».
void searchButtonPressed()
Esta señal se emite al pulsar el botón de búsqueda.
Nota: El controlador correspondiente es onSearchButtonPressed.
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. Al pulsar la tecla Intro o Retorno, se emitirá junto con la señal accepted() 2. Al editar el texto, 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 escribe, dependiendo del modelo de interacción deseado.
Nota: El controlador correspondiente es onSearchTriggered.
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.
Nota: El controlador correspondiente es onTextEdited.
Véase también searchTriggered().
Documentación del método
[since 6.12] void deselect()
Elimina la selección de texto activa.
Este método se introdujo en Qt 6.12.
Véase también selectedText, selectionStart y selectionEnd.
[since 6.12] void select(int start, int end)
Hace que se seleccione el texto desde start hasta end.
Si start o end están fuera del rango, la selección no se modifica.
Tras llamar a este método, selectionStart pasará a ser el menor y selectionEnd el mayor (independientemente del orden en que se hayan pasado a este método).
Este método se introdujo en Qt 6.12.
Véase también « selectionStart » y « selectionEnd ».
[since 6.12] void selectAll()
Selecciona todo el texto del campo de texto del control.
Este método se introdujo en Qt 6.12.
[since 6.12] void selectWord()
Hace que se seleccione la palabra más cercana a la posición actual del cursor.
Este método se introdujo en Qt 6.12.
Véase también cursorPosition y selectedText.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.