En esta página

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()

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

numberAlternativeRoutesEl número de rutas alternativas
travelModesModos de transporte
routeOptimizationsOptimizaciones de ruta requeridas
segmentDetailNivel de detalle en los segmentos
maneuverDetailEl nivel de detalle en las maniobras entre segmentos
waypointsUna lista de puntos de paso
excludedAreasUna lista de zonas excluidas que la ruta no debe atravesar
featureTypesElementos 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

GeoJsonData

Un modelo para representar, cargar y guardar documentos GeoJSON

Map

El tipo muestra un mapa

MapCircle

Este tipo muestra un círculo geográfico en un mapa

MapCopyrightNotice

El elemento muestra el aviso de derechos de autor válido actualmente para un elemento de mapa

MapItemGroup

El tipo es un contenedor de elementos del mapa

MapItemView

Se utiliza para rellenar el mapa a partir de un modelo

MapPolygon

El tipo muestra un polígono en un mapa

MapPolyline

El tipo muestra una polilínea en un mapa

MapQuickItem

El tipo muestra un objeto « Qt Quick » arbitrario en un mapa

MapRectangle

El tipo muestra un rectángulo en un mapa

MapRoute

El tipo muestra una ruta en un mapa

cameraCapabilities

El tipo contiene información sobre las capacidades de la cámara para un tipo de mapa específico

mapType

El tipo contiene información sobre un tipo de mapa

Geocodificación

GeocodeModel

El tipo ofrece soporte para operaciones de búsqueda relacionadas con la información geográfica

Rutas

RouteModel

El tipo permite acceder a rutas

RouteQuery

El tipo se utiliza para proporcionar parámetros de consulta a un RouteModel

route

El tipo representa una ruta geográfica

routeManeuver

El tipo representa la información relevante para el punto en el que se unen dos «routeSegments»

routeSegment

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.