PlaceSearchModel QML Type
Permite acceder a los resultados de búsqueda de lugares. Más...
| Import Statement: | import QtLocation 6.12 |
| Since: | QtLocation 5.5 |
Propiedades
- categories : list<Category>
- count : int
- favoritesMatchParameters : VariantMap
- favoritesPlugin : Plugin
- incremental : bool
(since QtLocation 5.12) - limit : int
- nextPagesAvailable : bool
- plugin : Plugin
- previousPagesAvailable : bool
- recommendationId : string
- relevanceHint : enumeration
- searchArea : variant
- searchTerm : string
- status : enum
- visibilityScope : enum
Señales
Métodos
- void cancel()
- Variant data(int index, string role)
- string errorString()
- void nextPage()
- void previousPage()
- void reset()
- void update()
- void updateWith(int proposedSearchIndex)
Descripción detallada
PlaceSearchModel proporciona un modelo de resultados de búsqueda de lugares dentro de la clase ` searchArea`. Las propiedades ` searchTerm ` y ` categories ` pueden configurarse para restringir los resultados de la búsqueda a los lugares que cumplan dichos criterios.
PlaceSearchModel devuelve tanto resultados de búsqueda patrocinados como orgánicos. Los resultados de búsqueda patrocinados tendrán el rol « sponsored » establecido en «true».
El modelo devuelve datos para los siguientes roles:
| Rol | Tipo | Descripción |
|---|---|---|
| tipo | enumeración | El tipo de resultado de la búsqueda. |
| título | cadena | Una cadena que describe el resultado de la búsqueda. |
| icono | PlaceIcon | Icono que representa el resultado de la búsqueda. |
| distancia | real | Válido únicamente cuando el rol « type » es « PlaceResult », la distancia del lugar al centro de « searchArea ». Si no se ha especificado ningún « searchArea », la distancia es NaN. |
| lugar | Place | Válido únicamente cuando el rol « type » es « PlaceResult », un objeto que representa el lugar. |
| sponsored | bool | Válido únicamente cuando el rol « type » es « PlaceResult »; es «true» si el resultado de la búsqueda es un resultado patrocinado. |
Tipos de resultados de búsqueda
El rol « type » puede adoptar los siguientes valores:
| PlaceSearchModel.UnknownSearchResult | Se desconoce el contenido del resultado de la búsqueda. |
| PlaceSearchModel.PlaceResult | El resultado de la búsqueda contiene un lugar. |
| PlaceSearchModel.ProposedSearchResult | El resultado de la búsqueda contiene una sugerencia de búsqueda que podría ser relevante. |
A menudo puede resultar útil utilizar un ` Loader ` para crear un delegado que elija diferentes ` Component` en función del tipo de resultado de la búsqueda.
Component {
id: resultDelegate
Loader {
Component {
id: placeResult
Column {
Text { text: title }
Text { text: place.location.address.text }
}
}
Component {
id: otherResult
Text { text: title }
}
sourceComponent: type == PlaceSearchModel.PlaceResult ? placeResult :
otherResult
}
}Detección de lugares actualizados y eliminados
El PlaceSearchModel está atento a los lugares que se han actualizado o eliminado del backend de su plugin. Si detecta que un lugar se ha actualizado y ese lugar está presente actualmente en el modelo, llamará a Place::getDetails para actualizar los detalles. Si detecta que se ha eliminado un lugar, este se eliminará del modelo si se encuentra actualmente en él.
Ejemplo
El siguiente ejemplo muestra cómo utilizar el PlaceSearchModel para buscar pizzerías en las inmediaciones de una posición determinada. Se proporcionan al modelo una ` searchTerm ` y una ` searchArea `, y se utiliza ` update()` para realizar una consulta de búsqueda. Ten en cuenta que el modelo no recupera los resultados de la búsqueda de forma incremental, sino que realiza una única recuperación cuando se ejecuta ` update()`. El parámetro « count » se establece en el número de resultados de búsqueda devueltos durante la recuperación.
import QtQuick
import QtPositioning
import QtLocation
PlaceSearchModel {
id: searchModel
plugin: myPlugin
searchTerm: "food"
searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);
Component.onCompleted: update()
}Paginación
La API de PlaceSearchModel ofrece una compatibilidad limitada con la paginación. Las funciones nextPage() y previousPage(), así como la propiedad limit, pueden utilizarse para acceder a los resultados de búsqueda paginados. Cuando se establece la propiedad limit, la página de resultados de búsqueda contiene como máximo limit entradas (de tipo «place result»). Por ejemplo, si el backend tiene un total de 5 resultados de búsqueda [a, b, c, d, e], y suponiendo que se muestra la primera página y se ha establecido un límite de 3, entonces se devuelven a, b y c. La función nextPage() devolvería d,e. Las propiedades nextPagesAvailable y previousPagesAvailable pueden utilizarse para comprobar si hay más páginas. Por el momento, la API no admite la forma de recuperar el número total de elementos disponibles en el backend. Ten en cuenta que la compatibilidad con nextPage(), previousPage() y limit puede variar según el plugin.
Véase también CategoryModel y QPlaceManager.
Documentación de propiedades
categories : list<Category> [read-only]
Esta propiedad contiene una lista de categorías que se utilizarán en la búsqueda. Los resultados de la búsqueda serán aquellos lugares que coincidan con al menos una de las categorías.
count : int [read-only]
Esta propiedad indica el número de resultados que tiene el modelo.
Ten en cuenta que no se refiere al número total de resultados de búsqueda disponibles en el backend. La API no admite actualmente el número total de resultados de búsqueda.
favoritesMatchParameters : VariantMap
Esta propiedad contiene un conjunto de parámetros que se utilizan para especificar cómo se asocian los resultados de búsqueda con los favoritos en favoritesPlugin.
Por defecto, el mapa de parámetros está vacío, lo que implica que el complemento de favoritos realiza la correspondencia mediante identificadores alternativos. Por lo general, un desarrollador de aplicaciones no necesitará configurar esta propiedad.
En los casos en los que el complemento de favoritos no admita la correspondencia mediante identificadores alternativos, se debe consultar la documentación del complemento para ver exactamente qué parámetros de clave-valor hay que configurar.
favoritesPlugin : Plugin
Esta propiedad contiene el « Plugin », que se utilizará para buscar favoritos. A cualquier lugar de la búsqueda que pueda cruzarse o coincidir con el «favoritesPlugin», se le asignará en la propiedad « favorite » el « Place » correspondiente del «favoritesPlugin».
Si no se ha configurado el «favoritesPlugin», la propiedad « favorite » de los lugares que aparecen en los resultados siempre será nula.
Véase también Favorites.
incremental : bool [since QtLocation 5.12]
Esta propiedad controla cómo afectará la paginación a la propiedad ` PlaceSearchModel`. Si se establece en `true`, al llamar a ` previousPage ` o ` nextPage ` no se restablecerá el modelo, sino que los nuevos resultados se añadirán al final del mismo. El valor por defecto es `false`.
Esta propiedad se introdujo en QtLocation 5.12.
limit : int
Esta propiedad establece el límite del número de elementos que se devolverán.
nextPagesAvailable : bool [read-only]
Esta propiedad se cumple tanto si hay una como si hay más de una página adicional de resultados de búsqueda disponible.
Véase también nextPage().
plugin : Plugin
Esta propiedad contiene el objeto ` Plugin `, que se utilizará para realizar la búsqueda.
previousPagesAvailable : bool [read-only]
Esta propiedad se cumple tanto si hay una como si hay más de una página anterior de resultados de búsqueda disponible.
Véase también previousPage().
recommendationId : string
Esta propiedad contiene el «placeId» que se utilizará para buscar recomendaciones de lugares similares.
relevanceHint : enumeration
Esta propiedad contiene una sugerencia de relevancia que se utiliza en la consulta de búsqueda. La sugerencia se proporciona al proveedor para ayudarle a determinar la clasificación de los resultados, pero sin imponerla. Por ejemplo, la sugerencia de distancia puede otorgar una clasificación más alta a los lugares más cercanos, pero eso no significa necesariamente que los resultados se ordenen estrictamente según la distancia. Un proveedor puede ignorar por completo la sugerencia.
| SearchResultModel.UnspecifiedHint | No se proporciona ninguna indicación de relevancia al proveedor. |
| SearchResultModel.DistanceHint | La distancia del lugar respecto a la ubicación actual del usuario es importante para este. Esta indicación solo tiene sentido cuando se utiliza un área de búsqueda circular. |
| SearchResultModel.LexicalPlaceNameHint | El orden léxico de los nombres de los lugares (en orden alfabético ascendente) es relevante para el usuario. Esta indicación resulta útil para los proveedores que se basan en un almacén de datos local. |
searchArea : variant
Esta propiedad define el área de búsqueda. El resultado de la búsqueda devuelto por el modelo se encontrará dentro de dicha área.
Si esta propiedad se establece en un objeto de tipo « geoCircle », su propiedad « radius » puede dejarse sin definir; en ese caso, el « Plugin » elegirá un radio adecuado para la búsqueda.
La compatibilidad con la especificación de un área de búsqueda puede variar según la implementación del backend de plugin. Por ejemplo, algunos pueden admitir únicamente un punto central de búsqueda, mientras que otros solo admiten rectángulos geográficos.
searchTerm : string
Esta propiedad contiene el término de búsqueda utilizado en la consulta. El término de búsqueda es una cadena de texto de formato libre.
status : enum [read-only]
Esta propiedad contiene el estado del modelo. Puede ser uno de los siguientes:
| PlaceSearchModel.Null | No se ha ejecutado ninguna consulta de búsqueda. El modelo está vacío. |
| PlaceSearchModel.Ready | La consulta de búsqueda ha finalizado y los resultados están disponibles. |
| PlaceSearchModel.Cargando | Actualmente se está ejecutando una consulta de búsqueda. |
| PlaceSearchModel.Error | Se ha producido un error al ejecutar la consulta de búsqueda anterior. |
visibilityScope : enum
Esta propiedad define el ámbito de visibilidad de los lugares que se van a buscar. En los resultados de la búsqueda solo aparecerán los lugares con la visibilidad especificada.
El ámbito de visibilidad puede ser uno de los siguientes:
| Place.UnspecifiedVisibility | No se ha especificado ningún ámbito de visibilidad explícito; los lugares con cualquier nivel de visibilidad pueden formar parte de los resultados de la búsqueda. |
| Place.DeviceVisibility | Solo los lugares almacenados en el dispositivo local formarán parte de los resultados de la búsqueda. |
| Place.PrivateVisibility | Solo los lugares que sean privados para el usuario actual formarán parte de los resultados de búsqueda. |
| Place.PublicVisibility | Solo los lugares que sean públicos formarán parte de los resultados de búsqueda. |
Documentación de Signal
dataChanged()
Esta señal se emite cuando se han producido cambios significativos en el almacén de datos subyacente.
Las aplicaciones deben actuar ante esta señal según su propio criterio. Los datos proporcionados por el modelo podrían estar desactualizados, por lo que el modelo debería volver a actualizarse en algún momento; sin embargo, una actualización inmediata podría resultar desconcertante para los usuarios si los resultados cambian sin que ellos hayan realizado ninguna acción.
El controlador correspondiente es onDataChanged.
Nota: El controlador correspondiente es onDataChanged.
Documentación del método
void cancel()
Cancela inmediatamente una operación de búsqueda en curso y establece el estado del modelo en « PlaceSearchModel.Ready». El modelo conserva los resultados de búsqueda que tenía antes de que se iniciara la operación.
Si no hay ninguna operación en curso, llamar a `cancel()` no tiene ningún efecto.
Véase también ` update()` y ` status`.
Variant data(int index, string role)
Devuelve los datos correspondientes a un « role » determinado en la fila especificada index.
string errorString()
Esta propiedad de solo lectura contiene la representación textual del último error del modelo de búsqueda de lugares. Si no se ha producido ningún error o si se ha borrado el modelo, se devuelve una cadena vacía.
También puede devolverse una cadena vacía si se ha producido un error que no tiene una representación textual asociada.
void nextPage()
Actualiza el modelo para mostrar la siguiente página de resultados de búsqueda. Si no hay ninguna página siguiente, este método no realiza ninguna acción.
void previousPage()
Actualiza el modelo para mostrar la página anterior de resultados de búsqueda. Si no hay página anterior, este método no realiza ninguna acción.
void reset()
Restablece el modelo. Se borran todos los resultados de la búsqueda, se cancelan las solicitudes pendientes y se corrigen los posibles errores. El estado del modelo se establecerá en « PlaceSearchModel.Null».
void update()
Actualiza el modelo en función de los parámetros de consulta proporcionados. El modelo se completará con una lista de lugares que coincidan con los parámetros de búsqueda especificados por las propiedades del tipo. Los criterios de búsqueda se especifican configurando propiedades como searchTerm, categories, searchArea y limit. La compatibilidad con estas propiedades puede variar según plugin. A continuación, update() envía el conjunto de criterios a plugin para su procesamiento.
Mientras el modelo se está actualizando, el status del modelo se establece en PlaceSearchModel.Loading. Si la actualización del modelo se realiza correctamente, el status se establece en PlaceSearchModel.Ready, mientras que, si no se completa con éxito, el status se establece en PlaceSearchModel.Error y el modelo se borra.
PlaceSearchModel {
id: model
plugin: backendPlugin
searchArea: QtPositioning.circle(QtPositioning.coordinate(10, 10))
...
}
MouseArea {
...
onClicked: {
model.searchTerm = "pizza";
model.categories = null; //not searching by any category
model.searchArea.center.latitude = -27.5;
model.searchArea.center.longitude = 153;
model.update();
}
}Véase también cancel() y status.
void updateWith(int proposedSearchIndex)
Actualiza el modelo basándose en el `ProposedSearchResult` del índice ` proposedSearchIndex`. El modelo se rellenará con una lista de lugares que coincidan con la búsqueda propuesta. El estado del modelo se establecerá en ` PlaceSearchModel`.Loading. Si el modelo se actualiza correctamente, el estado se establecerá en ` PlaceSearchModel`.Ready. Si se produce un error, el estado se establecerá en ` PlaceSearchModel`.Error y el modelo se vaciará.
Si proposedSearchIndex no hace referencia a un ProposedSearchResult, este método no realiza ninguna acción.
© 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.