En esta página

Visor de mapas (QML)

El ejemplo del visor de mapas muestra cómo visualizar un mapa e interactuar con él, buscar una dirección y obtener indicaciones para llegar en coche.

Mapa de Oslo con un marcador que dice «The Qt Company»

Se trata de un ejemplo extenso que abarca muchos usos básicos de los mapas, el posicionamiento y los servicios de navegación en Qt Location. Esta página se divide en secciones que abarcan cada una de estas áreas de funcionalidad con fragmentos del código.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

El ejemplo funciona con cualquiera de los complementos de servicios geográficos disponibles. No obstante, es posible que algunos complementos requieran un « plugin parameters » adicional para funcionar correctamente. Se puede pasar Plugin parameters en la línea de comandos utilizando el argumento --plugin, que tiene el siguiente formato:

--plugin.<parameter name> <parameter value>

Consulta la documentación de cada uno de los complementos de servicios geográficos para obtener más detalles sobre los parámetros que admiten. El complemento predeterminado utilizado en este ejemplo es el complemento OpenStreetMap deQt Location , que no requiere ningún parámetro.

Resumen

Tipos QML que aparecen en este ejemplo:

Visualización de un mapa

Para dibujar un mapa en pantalla se utiliza el tipo « MapView », tal y como se muestra a continuación.

MapView {
    id: view
    map.zoomLevel: (maximumZoomLevel - minimumZoomLevel)/2
    map.center {
        // The Qt Company in Oslo
        latitude: 59.9485
        longitude: 10.7686
    }
}

El tipo ` MapView ` se compone de un ` map ` y lo amplía para ofrecer funciones básicas de navegación. En este ejemplo, asignamos al mapa un centro inicial geoCoordinate con una latitud y una longitud determinadas. También establecemos el nivel de zoom inicial en el 50 % (a medio camino entre el máximo y el mínimo).

Búsqueda de una dirección (geocodificación)

Para localizar una dirección o un lugar concreto en el mapa se utiliza un proceso denominado geocodificación. Para realizar una operación de geocodificación, primero debemos configurar nuestro objeto Map para que pueda recibir el resultado.

La recepción de los resultados de la geocodificación se realiza a través de un ` GeocodeModel`:

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
        }
    }
}

Para mostrar el contenido del ` GeocodeModel `, utilizamos un ` MapItemView`:

MapItemView {
    parent: view.map
    model: geocodeModel
    delegate: pointDelegate
}

MapItemView utiliza un objeto denominado « delegate » que actúa como plantilla para los elementos que crea. Este puede contener cualquier objeto de mapa que se desee, pero en este caso mostramos un « MapQuickItem » que contiene una imagen de un marcador:

Component {
    id: pointDelegate

    MapQuickItem {
        id: point
        parent: view.map
        coordinate: locationData.coordinate

        sourceItem: Image {
            id: pointMarker
            source: "../resources/marker_blue.png"
        }
    }
}

Con estos tres objetos, tenemos lo necesario para recibir respuestas de geocodificación y mostrarlas en nuestro mapa. El último paso es enviar la solicitud de geocodificación propiamente dicha.

Para enviar una solicitud de geocodificación, primero creamos un objeto ` Address ` y lo rellenamos con los parámetros deseados.

Address {
    id :fromAddress
    street: "Sandakerveien 116"
    city: "Oslo"
    country: "Norway"
    state : ""
    postalCode: "0484"
}

A continuación, asignamos geocodeModel.query a Address una vez rellenado, y llamamos a update() en GeocodeModel.

// send the geocode request
geocodeModel.query = fromAddress
geocodeModel.update()

Indicaciones y rutas de viaje

Al igual que el ` GeocodeModel`, el ` Qt Location ` también cuenta con el tipo ` RouteModel `, que permite recibir información sobre rutas (por ejemplo, indicaciones para llegar en coche) entre dos o más puntos, y utilizarla con un ` Map`.

De nuevo, instanciamos el ` RouteModel ` como una propiedad de nuestro `Map`:

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

Para mostrar el contenido de un modelo al usuario, necesitamos una vista. Una vez más, utilizaremos un MapItemView para mostrar las rutas como objetos en el mapa:

MapItemView {
    parent: view.map
    model: routeModel
    delegate: routeDelegate

Para que sirva de plantilla a los objetos que queremos que cree la vista, creamos un componente delegado:

Component {
    id: routeDelegate

    MapRoute {
        id: route
        route: routeData
        line.color: "#46a2da"
        line.width: 5
        smooth: true
        opacity: 0.8

Ahora que el modelo, la vista y el delegado están completos, el único componente que falta es algún tipo de control sobre el modelo para iniciar el proceso de solicitud de ruta. En el caso más sencillo, podemos rellenar una solicitud de ruta utilizando dos coordinates ya disponibles:

property variant fromCoordinate: QtPositioning.coordinate(59.9483, 10.7695)
property variant toCoordinate: QtPositioning.coordinate(59.9645, 10.671)

En el siguiente fragmento de código, mostramos cómo configurar el objeto de solicitud e indicar al modelo que se actualice. También indicamos al mapa que se centre en la coordenada de inicio de nuestra solicitud de ruta.

// 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();
// center the map on the start coord
view.map.center = startCoordinate;

Esto es todo lo que se necesita para mostrar una ruta en el mapa. Sin embargo, también resulta útil poder recuperar las indicaciones escritas y la explicación de la ruta de viaje. En el ejemplo, estas se muestran en un elemento ` ListView `. Para crear este contenido, utilizamos un par estándar de `ListModel` y ` ListView `. Los datos del ` ListModel` se construyen a partir de la salida del `routeModel`:

ListView {
    interactive: true
    model: ListModel { id: routeInfoModel }
    header: RouteListHeader {}
    delegate:  RouteListDelegate{
        routeIndex.text: index + 1
        routeInstruction.text: instruction
        routeDistance.text: distance
    }
}

Dentro del elemento ` RouteModel`, como se puede ver más arriba, añadimos un controlador ` onStatusChanged `, que llama a la función ` showRouteList() `, la cual actualiza el ` routeInfoModel`:

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)
        });
    }
}

Proyecto de ejemplo en code.qt.io

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