API de QML Places

Descripción general

La API de Lugares permite a los usuarios descubrir lugares de interés y ver detalles sobre ellos, como la dirección y la información de contacto. Algunos lugares pueden tener contenido adicional asociado, como imágenes y reseñas. La API de Lugares también permite gestionar lugares y categorías, así como guardarlos y eliminarlos. Los lugares también pueden incluir caminos, carreteras o formas de transporte, lo que permite optimizar y ayudar a la navegación. Para obtener más información sobre la navegación, consulte routes.

Conceptos introductorios

Plugin

Un Plugin es una abstracción para un backend. Un Plugin puede acceder a lugares desde un servidor REST mientras que otro puede acceder a lugares desde una base de datos local. A continuación se instancia un objeto Plugin proporcionándole un nombre "osm". El nombre Plugin identifica el backend a elegir. A los plugins también se les puede proporcionar un conjunto de parameters, que esencialmente toma la forma de un conjunto de pares clave-valor. Los parameters que pueden especificarse varían entre los distintos backends Plugin. Para obtener documentación sobre los posibles parameters y los matices de cada Plugin, consulte las Referencias de plugins.

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

Modelos, vistas y delegados

La API de QML Places se basa en la noción de modelos, vistas y delegados.

Modelo	Un modelo contiene elementos de datos y mantiene su estructura. El modelo también es responsable de recuperar los elementos de una fuente de datos.
Vista	Una vista es un contenedor visual que muestra los datos y gestiona cómo se muestran los elementos visuales, por ejemplo, en una lista o una cuadrícula. La vista también puede ser responsable de navegar por los datos, por ejemplo, desplazarse por los elementos visuales durante un movimiento de desplazamiento.
Delegado	Un delegado define cómo deben aparecer los elementos de datos individuales como elementos visuales en la vista. Los modelos exponen un conjunto de roles de datos y el delegado los utiliza para construir un elemento visual. El delegado también puede definir comportamientos, como una operación a invocar cuando se hace clic en un elemento visual.

La sección Casos de uso común muestra ejemplos concretos de cómo encajan estos conceptos.

Casos de uso común

Búsqueda de lugares

La búsqueda se realiza a través de PlaceSearchModel. La propiedad plugin especifica en qué backend se realizarán las operaciones de búsqueda. Los parámetros de búsqueda pueden proporcionarse a través de propiedades como searchTerm y searchArea. Una operación de búsqueda puede iniciarse invocando el método update(). Para simplificar, el siguiente fragmento invoca update() una vez que se ha completado la construcción del modelo, normalmente update() se invocaría en respuesta a una acción del usuario como un clic en un botón. Durante la operación de búsqueda, la propiedad PlaceSearchModel::status pasa al estado Loading y, una vez completada con éxito, pasa al estado Ready.

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "food"
    searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);

    Component.onCompleted: update()

}

Mostrar resultados de búsqueda con un ListView

Un ListView puede ser utilizado para mostrar los resultados de búsqueda encontrados por el modelo. Define la región visual en la que se muestran los resultados y, en el caso que se muestra a continuación, rellena la totalidad de su padre. ListView ha incorporado un comportamiento que permite a la región responder a eventos de desplazamiento y desplazarse adecuadamente.

En el siguiente fragmento, el modelo de búsqueda se ha asignado a la propiedad model de ListView. Cuando el modelo se actualiza con nuevos resultados, ListView se actualiza automáticamente para reflejar los nuevos elementos de datos del modelo.

Se ha vinculado un simple delegado a la propiedad delegate de ListView. El PlaceSearchModel expone un conjunto de roles de los cuales los roles title y place se han utilizado a continuación, estos son de tipo string y Place respectivamente. Esencialmente, para cada elemento de datos que debe ser visible en la vista, ésta invoca al delegado para crear una representación visual del elemento.

ListView {
    anchors.fill: parent
    model: searchModel
    delegate: Component {
        Row {
            spacing: 5
            Marker { height: parent.height }
            Column {
                Text { text: title; font.bold: true }
                Text { text: place.location.address.text }
            }
        }
    }
}

Nota: Por razones de simplicidad, hemos supuesto que todos los resultados de búsqueda son de tipo type PlaceSearchResult y, por lo tanto, siempre tienen acceso a la función de lugar; otros tipos de resultados de búsqueda pueden no tener función de lugar.

Para ver el código fuente completo, consulte el ejemplo de la lista de lugares.

Mostrar resultados de búsqueda utilizando un MapItemView

En lugar de ListView, puede utilizarse PlaceSearchModel junto con MapItemView para mostrar marcadores en un mapa. En primer lugar se utiliza un Map para definir la región visual ocupada por el mapa, en este caso llena la totalidad de su padre. Se especifican otras propiedades como el plugin que proporciona los mapas, y los center y zoomLevel del mapa.

Dentro del Map, se declara un MapItemView, donde la propiedad model se ha establecido en el modelo de búsqueda y un delegate que consiste en un MapQuickItem se utiliza para mostrar una imagen de marcador. Se muestra un marcador por cada lugar encontrado por el modelo de búsqueda. El delegado utiliza el rol de lugar para posicionar el marcador.

MapView {
    id: view
    anchors.fill: parent
    map.plugin: myPlugin;
    map.center: positionSource.lastSearchPosition
    map.zoomLevel: 13

    MapItemView {
        model: searchModel
        parent: view.map
        delegate: MapQuickItem {
            coordinate: place.location.coordinate

            anchorPoint.x: image.width * 0.5
            anchorPoint.y: image.height

            sourceItem: Column {
                Image { id: image; source: "marker.png" }
                Text { text: title; font.bold: true }
            }
        }
    }
}

Nota: Por razones de simplicidad hemos asumido que cada resultado de búsqueda es de type PlaceSearchResult y por lo tanto siempre tienen acceso al rol de lugar, otros tipos de resultados de búsqueda pueden no tener un rol de lugar.

Consulte el ejemplo del mapa de lugares para ver el código fuente completo.

Obtención de detalles de lugares

Con el fin de ahorrar ancho de banda, a veces un backend sólo devolverá lugares que estén parcialmente poblados con detalles. Esto puede comprobarse con la propiedad Place::detailsFetched, que indica si se han obtenido o no todos los detalles disponibles. Si no es así, se puede invocar el método Place::getDetails() para obtener los detalles restantes.

if (!place.detailsFetched)
    place.getDetails();

Guardar y eliminar lugares

Algunos backends permiten guardar y eliminar lugares. Esto puede hacerse llamando a los métodos Place::save() y Place::remove() respectivamente. Ten en cuenta que para guardar un Place, se debe asignar un Plugin para especificar en qué backend estamos guardando. La propiedad status pasará al estado Saving mientras se realiza la operación de guardado y, una vez completada con éxito, pasará al estado Ready. El siguiente fragmento muestra cómo guardar y eliminar un lugar utilizando javascript.

//creating and saving a place
var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = myPlugin;
place.name = "New York";
place.location.coordinate.latitude = 40.7
place.location.coordinate.longitude = -74.0
place.save();

//removing a place
place.remove();

Más información

Los fragmentos anteriores sólo muestran un pequeño subconjunto de la funcionalidad de Lugares. Consulta los tipos de lugares que se muestran a continuación para obtener más información, como images, reviews, etc., así como descripciones y explicaciones más detalladas.

Consulte también el ejemplo Lugares (QML ) para obtener una demostración más completa de cómo utilizar la API.

Tipos de lugares

Tipos de datos

Category	Type representa una categoría a la que puede asociarse un lugar
ContactDetails	El tipo contiene los datos de contacto de un lugar
ExtendedAttributes	El tipo contiene datos adicionales sobre un lugar
Place	El tipo representa una ubicación que es un lugar de interés
contactDetail	El tipo contiene información de contacto, como un número de teléfono o la dirección de un sitio web
icon	El tipo representa el icono de un lugar
placeAttribute	El tipo contiene información genérica sobre los atributos de un lugar
ratings	El tipo contiene información sobre la clasificación de un lugar
supplier	Contiene datos sobre el proveedor de un lugar, su imagen, reseña o editorial
user	El tipo identifica al usuario que ha contribuido a un determinado contenido de un lugar.

Modelos

CategoryModel	Type proporciona un modelo de las categorías soportadas por un Plugin
EditorialModel	El tipo proporciona un modelo de editoriales de lugares
ImageModel	El tipo proporciona un modelo de imágenes de lugares
PlaceSearchModel	Proporciona acceso a los resultados de búsqueda de lugares
PlaceSearchSuggestionModel	Proporciona acceso a sugerencias de términos de búsqueda
ReviewModel	El tipo proporciona un modelo de reseñas de lugares

Lugares (C++)Backend de lugares

© 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.