En esta página

API de QML para 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 te permite gestionar lugares y categorías, lo que te permite guardarlos y eliminarlos. Los lugares también pueden incluir rutas, carreteras o medios de transporte, lo que permite optimizar la navegación y ofrecer asistencia. Para obtener más información sobre la navegación, consulta routes.

Conceptos introductorios

Complemento

Un « Plugin » es una abstracción de un backend. Un « Plugin » puede acceder a los lugares desde un servidor REST, mientras que otro puede hacerlo desde una base de datos local. El siguiente código crea una instancia de un objeto « Plugin » proporcionando el nombre «osm». El nombre « Plugin » identifica qué backend se debe elegir. Los complementos también pueden incluir un conjunto de parameters, que básicamente adopta la forma de un conjunto de pares clave-valor. Los parameters que se pueden especificar varían según los distintos backends Plugin. Para consultar la documentación sobre los posibles parameters y los matices de cada Plugin, véase la sección «Referencias de complementos».

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

Modelos, vistas y delegados

La API de QML Places se basa en el concepto de modelos, vistas y delegados.

ModeloUn modelo contiene elementos de datos y mantiene su estructura. El modelo también se encarga de recuperar los elementos de una fuente de datos.
VistaUna vista es un contenedor visual que muestra los datos y gestiona cómo se presentan los elementos visuales, por ejemplo, en una lista o una cuadrícula. La vista también puede encargarse de la navegación por los datos; por ejemplo, desplazarse por los elementos visuales con un movimiento rápido.
DelegadoUn 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 que se debe invocar al hacer clic en un elemento visual.

La sección «Casos de uso comunes» que figura a continuación muestra ejemplos concretos de cómo encajan estos conceptos entre sí.

Casos de uso comunes

Búsqueda de lugares

La búsqueda se realiza a través de ` PlaceSearchModel`. La propiedad ` plugin ` especifica en qué backend se deben realizar las operaciones de búsqueda. Los parámetros de búsqueda pueden proporcionarse a través de propiedades como ` searchTerm ` y ` searchArea`. A continuación, se puede iniciar una operación de búsqueda invocando el método ` update()`. Para simplificar, el fragmento de código siguiente invoca update() una vez finalizada la construcción del modelo; normalmente, update() se invocaría en respuesta a una acción del usuario, como hacer clic en un botón. Mientras la operación de búsqueda está en curso, la propiedad PlaceSearchModel::status pasa al estado Loading y, cuando se completa 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 los resultados de la búsqueda mediante un ListView

Se puede utilizar un ListView para mostrar los resultados de búsqueda encontrados por el modelo. Define la región visual donde se muestran los resultados y, en el caso que se muestra a continuación, ocupa la totalidad de su elemento padre. El ListView cuenta con un comportamiento integrado que permite que la región responda a eventos de deslizamiento y se desplace adecuadamente.

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

Se ha vinculado un delegado sencillo a la propiedad ` delegate ` de ` ListView`. El ` PlaceSearchModel ` expone un conjunto de ` roles `, de los cuales se han utilizado a continuación los roles «title» y «place»; estos son de tipo «string» y « Place », respectivamente. Básicamente, para cada elemento de datos que deba ser visible en la vista, esta 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 }
            }
        }
    }
}
Lista numerada de pizzerías

Nota: En aras de la simplicidad, hemos supuesto que todos los resultados de búsqueda son de tipo type PlaceSearchResult y, por lo tanto, siempre tienen acceso al rol «place»; es posible que otros tipos de resultados de búsqueda no dispongan de un rol «place ».

Consulta el ejemplo «Lista de lugares » para ver el código fuente completo.

Mostrar resultados de búsqueda utilizando un `MapItemView`

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

Dentro de Map, se declara un MapItemView, en el que la propiedad model se ha establecido en el modelo de búsqueda y se utiliza un delegate, que consiste en un MapQuickItem, para mostrar una imagen de marcador. Se muestra un marcador para cada lugar encontrado por el modelo de búsqueda. El delegado utiliza el rol «place» 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 }
            }
        }
    }
}
Mapa con marcadores de lugares etiquetados

Nota: En aras de la simplicidad, hemos supuesto que todos los resultados de búsqueda son de tipo « type » ( PlaceSearchResult ) y, por lo tanto, siempre tienen acceso al rol «place»; es posible que otros tipos de resultados de búsqueda no dispongan de dicho rol.

Consulta el ejemplo «Mapa de lugares » para ver el código fuente completo.

Obtención de detalles de lugares

Para ahorrar ancho de banda, a veces un backend solo devuelve lugares cuyos detalles están parcialmente rellenados. Esto se puede comprobar con la propiedad Place::detailsFetched, que indica si se han recuperado todos los detalles disponibles o no. Si no es así, se puede invocar el método Place::getDetails() para recuperar los detalles restantes.

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

Guardar y eliminar lugares

Algunos backends pueden admitir el guardado y la eliminación de lugares. Esto se puede hacer 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 se va a guardar. La propiedad « status » pasará al estado « Saving » mientras se lleva a cabo la operación de guardado y, una vez completada con éxito, pasará al estado « Ready ». El siguiente fragmento de código 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 de código anteriores solo muestran una pequeña parte de la funcionalidad de «Places». Consulte los tipos de «Places» que se muestran a continuación para obtener información más detallada, como images, reviews, etc., así como descripciones y explicaciones más exhaustivas.

Consulta también el ejemplo de «Places (QML) » para obtener una demostración más completa sobre cómo utilizar la API.

Tipos de «Places»

Tipos de datos

Category

El tipo representa una categoría a la que se puede asociar un lugar

ContactDetails

«Type» contiene los datos de contacto de un «Place»

ExtendedAttributes

El «Tipo» contiene datos adicionales sobre un «Lugar»

Place

El tipo representa una ubicación que constituye un punto de interés

contactDetail

El tipo contiene un dato de contacto, como un número de teléfono o la dirección de una página web

icon

El tipo representa el icono de un lugar

placeAttribute

El tipo contiene información genérica sobre los atributos del lugar

ratings

El tipo contiene información sobre la valoración del lugar

supplier

Contiene datos relativos al proveedor de un lugar, una imagen del mismo, una reseña o un artículo editorial

user

El tipo identifica a un usuario que ha aportado un elemento de contenido concreto sobre un lugar

Modelos

CategoryModel

El tipo proporciona un modelo de las categorías compatibles con un complemento

EditorialModel

El tipo proporciona un modelo de los artículos editoriales sobre lugares

ImageModel

El tipo proporciona un modelo de las imágenes de un lugar

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

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