PlaceSearchModel QML Type

Proporciona acceso a los resultados de la búsqueda de lugares. Más...

• Lista de todos los miembros, incluidos los heredados

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

• dataChanged()

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 searchArea. Las propiedades searchTerm y categories pueden establecerse para restringir los resultados de búsqueda a los lugares que coincidan con esos criterios.

El PlaceSearchModel devuelve resultados de búsqueda patrocinados y orgánicos. Los resultados de búsqueda patrocinados tendrán la función sponsored establecida en true.

El modelo devuelve datos para los siguientes roles:

Tipos de resultados de búsqueda

El rol type puede tomar los siguientes valores:

A menudo puede resultar útil utilizar Loader para crear un delegado que elija diferentes Components 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 suprimidos

El PlaceSearchModel escucha los lugares que han sido actualizados o eliminados del backend de su plugin. Si detecta que un lugar ha sido actualizado y ese lugar está actualmente presente en el modelo, entonces llamará a Place::getDetails para actualizar los detalles. Si detecta que un lugar ha sido eliminado, entonces el lugar será eliminado del modelo si está actualmente presente.

Ejemplo

El siguiente ejemplo muestra cómo utilizar el modelo PlaceSearchModel para buscar pizzerías cercanas a una posición determinada. Se proporcionan al modelo searchTerm y searchArea y se utiliza update() para realizar una consulta de búsqueda. Tenga en cuenta que el modelo no obtiene los resultados de la búsqueda de forma incremental, sino que realiza una única obtención cuando se ejecuta update(). count se establece en el número de resultados de búsqueda devueltos durante la búsqueda.

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 PlaceSearchModel ofrece un soporte limitado para 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 la propiedad limit está activada, la página de resultados de búsqueda contiene como máximo limit entradas (de tipo resultado de lugar). Por ejemplo, si el backend tiene 5 resultados de búsqueda en total [a,b,c,d,e], y suponiendo que se muestra la primera página y se ha establecido el límite de 3, entonces se devuelve a,b,c. nextPage () devolvería d,e. Las propiedades nextPagesAvailable y previousPagesAvailable pueden utilizarse para buscar más páginas. Por el momento, la API no permite recuperar el número total de elementos disponibles en la base de datos. Tenga en cuenta que la compatibilidad con nextPage(), previousPage() y limit puede variar en función de la propiedad 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 los lugares que coincidan con al menos una de las categorías.

count : int [read-only]

Esta propiedad contiene el número de resultados que tiene el modelo.

Tenga en cuenta que no se refiere al número total de resultados de búsqueda disponibles en el backend. El número total de resultados de búsqueda no está soportado actualmente por la API.

favoritesMatchParameters : VariantMap

Esta propiedad contiene un conjunto de parámetros que se utilizan para especificar cómo se emparejan los lugares de los resultados de búsqueda con los favoritos en favoritesPlugin.

Por defecto, el mapa de parámetros está vacío e implica que el plugin de favoritos empareja por identificadores alternativos. Generalmente, un desarrollador de aplicaciones no necesitará configurar esta propiedad.

En los casos en los que el complemento de favoritos no admita la comparación por identificadores alternativos, deberá consultarse la documentación del complemento para saber con precisión qué parámetros clave-valor deben establecerse.

favoritesPlugin : Plugin

Esta propiedad contiene el Plugin que se utilizará para buscar favoritos. Cualquier lugar de la búsqueda que pueda ser referenciado o encontrado en el favoritesPlugin tendrá su propiedad favorite establecida en el correspondiente Place del favoritesPlugin.

Si no se establece el favoritesPlugin, la propiedad favorite de los lugares de los resultados será siempre nula.

Véase también Favorites.

incremental : bool [since QtLocation 5.12]

Esta propiedad controla cómo afectará la paginación a PlaceSearchModel. Si es verdadera, al llamar a previousPage o nextPage no se reiniciará el modelo, sino que los nuevos resultados se añadirán al modelo. Por defecto es false.

Esta propiedad se introdujo en QtLocation 5.12.

limit : int

Esta propiedad contiene el límite del número de elementos que se devolverán.

nextPagesAvailable : bool [read-only]

Esta propiedad mantiene si hay una o más páginas adicionales de resultados de búsqueda disponibles.

Véase también nextPage().

plugin : Plugin

Esta propiedad contiene el Plugin que se utilizará para realizar la búsqueda.

previousPagesAvailable : bool [read-only]

Esta propiedad mantiene si hay una o más páginas anteriores de resultados de búsqueda disponibles.

Véase también previousPage().

recommendationId : string

Esta propiedad contiene el placeId que se utilizará para encontrar recomendaciones de lugares similares.

relevanceHint : enumeration

Esta propiedad contiene una pista de relevancia utilizada en la consulta de búsqueda. La pista se da al proveedor para ayudar, pero no para dictar la clasificación de los resultados. Por ejemplo, la pista de distancia puede dar a los lugares más cercanos una clasificación más alta, pero no significa necesariamente que los resultados se ordenen estrictamente según la distancia. Un proveedor puede ignorar la sugerencia por completo.

searchArea : variant

Esta propiedad contiene el área de búsqueda. El resultado de la búsqueda devuelto por el modelo estará dentro del área de búsqueda.

Si esta propiedad se establece en geoCircle, su propiedad radius puede dejarse sin establecer, en cuyo caso Plugin elegirá un radio apropiado para la búsqueda.

El soporte para especificar un área de búsqueda puede variar según la implementación del backend plugin. Por ejemplo, algunas sólo admiten un centro de búsqueda, mientras que otras sólo 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 libre.

status : enum [read-only]

Esta propiedad contiene el estado del modelo. Puede ser

visibilityScope : enum

Esta propiedad contiene el ámbito de visibilidad de los lugares a buscar. Sólo los lugares con la visibilidad especificada aparecerán en los resultados de la búsqueda.

El ámbito de visibilidad puede ser uno de los siguientes

Documentación sobre señales

dataChanged()

Esta señal se emite cuando se han realizado cambios significativos en el almacén de datos subyacente.

Las aplicaciones deben actuar sobre esta señal a su propia discreción. Los datos proporcionados por el modelo podrían no estar actualizados, por lo que el modelo debería volver a actualizarse en algún momento; sin embargo, una nueva actualización inmediata podría desconcertar a los usuarios si los resultados cambian sin que ellos hayan realizado ninguna acción.

El gestor 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 cualquier resultado de búsqueda que tuviera antes de que se iniciara la operación.

Si una operación no está en curso, la invocación de cancel() no tiene ningún efecto.

Véase también update() y status.

Variant data(int index, string role)

Devuelve los datos de un determinado role en la fila especificada index.

string errorString()

Esta propiedad de sólo lectura contiene la presentación textual del último error del modelo de búsqueda de lugar. 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 representación textual asociada.

void nextPage()

Actualiza el modelo para mostrar la siguiente página de resultados de búsqueda. Si no hay página siguiente, este método no hace nada.

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 hace nada.

void reset()

Reinicia el modelo. Se borran todos los resultados de búsqueda, se cancelan las solicitudes pendientes y se borran los posibles errores. El estado del modelo será PlaceSearchModel.Null.

void update()

Actualiza el modelo basándose en los parámetros de consulta proporcionados. El modelo se rellenará 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 estableciendo 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 que los procese.

Mientras el modelo se actualiza, el status del modelo se establece en PlaceSearchModel.Loading. Si el modelo se actualiza con éxito, el status se establece en PlaceSearchModel.Ready, mientras que si se completa sin é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 en el índice proposedSearchIndex. El modelo se rellenará con una lista de lugares que coincidan con la búsqueda propuesta. El estado del modelo será PlaceSearchModel.Loading. Si el modelo se actualiza correctamente, el estado será PlaceSearchModel.Ready. Si se produce un error, el estado será PlaceSearchModel.Error y se borrará el modelo.

Si proposedSearchIndex no hace referencia a un ProposedSearchResult este método no hace nada.