Mapas QML
Descripción general
El tipo « Map » permite mostrar un mapa y colocar objetos en él. Se pueden definir y añadir al mapa diversos puntos de interés para su visualización. Además, el « Map » cuenta con funciones para controlar cómo se muestra el mapa. Con el elemento «Map» puedes centrar el mapa, ampliarlo, reducirlo con los dedos y hacer que el elemento sea desplazable con un movimiento rápido.
Los lugares que se van a añadir al mapa son MapItems. La posición del elemento viene definida por un geoCoordinate, que incluye la latitud, la longitud y la altitud. A continuación, el elemento se muestra automáticamente tras añadirlo al Map.
Posición en el mapa
Todas las API de posición forman parte del módulo QtPositioning. La unidad básica de información de posición es el geoCoordinate. Un geoCoordinate encapsula los datos de latitud, longitud y altitud de la ubicación. La altitud se expresa en metros. También dispone de un método para determinar la distancia a otra geoCoordinate. El tipo geoCoordinate también puede estar contenido dentro de un elemento Location; este incluirá, además, información sobre el tamaño de un cuadro delimitador para determinar la proximidad suficiente a la ubicación, así como la dirección de la misma.
A continuación se muestra un ejemplo de un cliente que utiliza un position source para centrar un map en la posición actual:
import QtPositioning
import QtLocation
...
Rectangle {
Map {
id: map
// initialize map
...
}
PositionSource {
onPositionChanged: {
// center the map on the current position
map.center = position.coordinate
}
}
}Geocodificación
La geocodificación es la derivación de coordenadas geográficas (latitud y longitud) a partir de otras referencias geográficas de las ubicaciones. Por ejemplo, puede tratarse de una dirección postal. También es posible la geocodificación inversa, en la que se utiliza una dirección postal para determinar unas coordenadas geográficas. La geocodificación se lleva a cabo utilizando el tipo « GeocodeModel ».
Los siguientes ejemplos de código son una pequeña parte del componente « map » del ejemplo «Map Viewer (QML) ». Los fragmentos muestran la declaración del componente « GeocodeModel ».
En el fragmento vemos que ` GeocodeModel ` contiene el complemento y dos controladores de señales. Uno para los cambios de estado onStatusChanged y otro para actualizar el centrado del objeto Map onLocationsChanged.
GeocodeModel {
id: geocodeModel
plugin: view.map.plugin
onStatusChanged: {
if ((status == GeocodeModel.Ready) || (status == GeocodeModel.Error))
view.geocodeFinished()
}
onLocationsChanged:
{
if (count === 1) {
view.map.center.latitude = get(0).coordinate.latitude
view.map.center.longitude = get(0).coordinate.longitude
}
}
}
MapItemView {
parent: view.map
model: geocodeModel
delegate: pointDelegate
}Las funciones de geocodificación se invocan desde un fragmento de código de nivel superior. En este fragmento vemos un objeto ` Address ` rellenado con los parámetros deseados.
Address {
id :fromAddress
street: "Sandakerveien 116"
city: "Oslo"
country: "Norway"
state : ""
postalCode: "0484"
}El ` Address ` se utiliza posteriormente en una consulta para que el ` GeocodeModel ` procese y determine la ubicación geográfica ` coordinates`.
// send the geocode request
geocodeModel.query = fromAddress
geocodeModel.update()Navegación
Una función muy importante del tipo ` Map ` es la navegación desde un lugar hasta un destino con posibles puntos de paso a lo largo de la ruta. La ruta se dividirá en una serie de segmentos. Al final de cada segmento hay un vértice denominado «maniobra». Los segmentos contienen información sobre el tiempo y la distancia hasta el final del segmento. Las maniobras contienen información sobre qué hacer a continuación y cómo pasar al siguiente segmento, si lo hay. Así pues, una maniobra contiene información de navegación, por ejemplo, «gira a la derecha ahora».
Para encontrar una ruta adecuada, tendremos que utilizar un ` RouteQuery ` para definir los criterios de selección y añadir los puntos de paso necesarios. La ` RouteModel ` debería devolver una lista de ` routeSegment` que definan la ruta hasta el destino, completa con indicaciones de navegación en las uniones entre segmentos, denominadas ` routeManeuver`.
Existen numerosas opciones que se pueden añadir a la consulta para acotar los criterios. Las propiedades de RouteQuery pueden incluir
| numberAlternativeRoutes | El número de rutas alternativas |
| travelModes | Modos de transporte |
| routeOptimizations | Optimizaciones de ruta requeridas |
| segmentDetail | Nivel de detalle en los segmentos |
| maneuverDetail | El nivel de detalle en las maniobras entre segmentos |
| waypoints | Una lista de puntos de paso |
| excludedAreas | Una lista de zonas excluidas que la ruta no debe atravesar |
| featureTypes | Elementos relevantes del mapa, por ejemplo, autopistas o transbordadores |
En el siguiente ejemplo se declara un objeto « RouteQuery » predeterminado dentro de « RouteModel ».
RouteModel {
id: routeModel
plugin : view.map.plugin
query: RouteQuery {
id: routeQuery
}
onStatusChanged: {
if (status == RouteModel.Ready) {
switch (count) {
case 0:
// technically not an error
view.routeError()
break
case 1:
view.showRouteList()
break
}
} else if (status == RouteModel.Error) {
view.routeError()
}
}
}El usuario introduce cierta información, como el punto de partida de la ruta, algunos puntos de paso y el destino. Todas estas ubicaciones son puntos de paso, por lo que las ubicaciones desde el inicio hasta el final se introducirán como una secuencia de puntos de paso. A continuación, se pueden establecer otras propiedades de consulta que puedan ser específicas de este viaje.
// clear away any old data in the query
routeQuery.clearWaypoints();
// add the start and end coords as waypoints on the route
routeQuery.addWaypoint(startCoordinate)
routeQuery.addWaypoint(endCoordinate)
routeQuery.travelModes = RouteQuery.CarTravel
routeQuery.routeOptimizations = RouteQuery.FastestRoute
routeModel.update();El ListModel de routeInfoModel se utiliza para obtener los resultados de la consulta y crear una lista adecuada para su visualización.
ListView {
interactive: true
model: ListModel { id: routeInfoModel }
header: RouteListHeader {}
delegate: RouteListDelegate{
routeIndex.text: index + 1
routeInstruction.text: instruction
routeDistance.text: distance
}
}El ListModel routeInfoModel puede rellenarse con valores mediante un código que recorre los segmentos extrayendo la longitud del segmento, el texto de las instrucciones y la distancia hasta la siguiente instrucción. Los datos extraídos se formatean para su visualización a medida que se recuperan.
routeInfoModel.clear()
if (routeModel.count > 0) {
for (var i = 0; i < routeModel.get(0).segments.length; i++) {
routeInfoModel.append({
"instruction": routeModel.get(0).segments[i].maneuver.instructionText,
"distance": Helper.formatDistance(routeModel.get(0).segments[i].maneuver.distanceToNextInstruction)
});
}
}Para obtener más información sobre el ejemplo, consulta el ejemplo «Map Viewer (QML) ».
Zoom, pellizcar y deslizar
El elemento Map también admite interacciones del usuario con el mapa mediante gestos táctiles y del ratón. Es decir, funciones como deslizar para desplazar la vista o pellizcar para hacer zoom.
Habilitar y configurar el pellizco y el deslizamiento es sencillo dentro del tipo « MapView ».
MapView {
id: view
TapHandler {
id: tapHandler
property variant lastCoordinate
acceptedButtons: Qt.LeftButton | Qt.RightButton
onPressedChanged: (eventPoint, button) => {
if (pressed) {
lastCoordinate = view.map.toCoordinate(tapHandler.point.position)
}
}
onSingleTapped: (eventPoint, button) => {
if (button === Qt.RightButton) {
showMainMenu(lastCoordinate)
}
}
onDoubleTapped: (eventPoint, button) => {
var preZoomPoint = view.map.toCoordinate(eventPoint.position);
if (button === Qt.LeftButton) {
view.map.zoomLevel = Math.floor(view.map.zoomLevel + 1)
} else if (button === Qt.RightButton) {
view.map.zoomLevel = Math.floor(view.map.zoomLevel - 1)
}
var postZoomPoint = view.map.toCoordinate(eventPoint.position);
var dx = postZoomPoint.latitude - preZoomPoint.latitude;
var dy = postZoomPoint.longitude - preZoomPoint.longitude;
view.map.center = QtPositioning.coordinate(view.map.center.latitude - dx,
view.map.center.longitude - dy);
}
}
}El zoom también se puede controlar mediante otros objetos, como controles deslizantes, mediante un enlace al objeto « zoomLevel » del mapa.
Tipos QML
Mapas
Un modelo para representar, cargar y guardar documentos GeoJSON | |
El tipo muestra un mapa | |
Este tipo muestra un círculo geográfico en un mapa | |
El elemento muestra el aviso de derechos de autor válido actualmente para un elemento de mapa | |
El tipo es un contenedor de elementos del mapa | |
Se utiliza para rellenar el mapa a partir de un modelo | |
El tipo muestra un polígono en un mapa | |
El tipo muestra una polilínea en un mapa | |
El tipo muestra un objeto « Qt Quick » arbitrario en un mapa | |
El tipo muestra un rectángulo en un mapa | |
El tipo muestra una ruta en un mapa | |
El tipo contiene información sobre las capacidades de la cámara para un tipo de mapa específico | |
El tipo contiene información sobre un tipo de mapa |
Geocodificación
El tipo ofrece soporte para operaciones de búsqueda relacionadas con la información geográfica |
Rutas
El tipo permite acceder a rutas | |
El tipo se utiliza para proporcionar parámetros de consulta a un RouteModel | |
El tipo representa una ruta geográfica | |
El tipo representa la información relevante para el punto en el que se unen dos «routeSegments» | |
El tipo representa un segmento de una ruta |
Ejemplo
Los fragmentos de código anteriores se han extraído del ejemplo «Map Viewer (QML) ».
© 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.