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.
| Modelo | Un modelo contiene elementos de datos y mantiene su estructura. El modelo también se encarga 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 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. |
| 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 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.
![]() |
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.
| ![]() |
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
El tipo representa una categoría a la que se puede asociar un lugar | |
«Type» contiene los datos de contacto de un «Place» | |
El «Tipo» contiene datos adicionales sobre un «Lugar» | |
El tipo representa una ubicación que constituye un punto de interés | |
El tipo contiene un dato de contacto, como un número de teléfono o la dirección de una página web | |
El tipo representa el icono de un lugar | |
El tipo contiene información genérica sobre los atributos del lugar | |
El tipo contiene información sobre la valoración del lugar | |
Contiene datos relativos al proveedor de un lugar, una imagen del mismo, una reseña o un artículo editorial | |
El tipo identifica a un usuario que ha aportado un elemento de contenido concreto sobre un lugar |
Modelos
El tipo proporciona un modelo de las categorías compatibles con un complemento | |
El tipo proporciona un modelo de los artículos editoriales sobre lugares | |
El tipo proporciona un modelo de las imágenes de un lugar | |
Proporciona acceso a los resultados de búsqueda de lugares | |
Proporciona acceso a sugerencias de términos de búsqueda | |
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.

