En esta página

Mapa mínimo (QML)

El código mínimo para mostrar un mapa utilizando Qt Quick.

Ventana de la aplicación en la que se muestra un mapa del centro de Oslo

El mapa mínimo muestra cómo utilizar el elemento Map para renderizar un mapa. Muestra la cantidad mínima de código necesaria para mostrar el mapa y puede utilizarse como base para seguir experimentando.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Código C++

En main.cpp solo utilizamos las clases QGuiApplication y QQmlApplicationEngine.

#include <QGuiApplication>
#include <QQmlApplicationEngine>

En la función main, primero instanciamos un objeto QGuiApplication. A continuación, creamos un QQmlApplicationEngine y le indicamos que cargue main.qml desde el sistema de recursos de Qt.

Por último, QGuiApplication::exec() inicia el bucle de eventos principal.

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

    return app.exec();
}

Código QML

En ` main.qml`, importamos el módulo QML ` QtLocation ` y su módulo QML dependiente ` QtPositioning `. A continuación, creamos la ventana de nivel superior, le asignamos un tamaño predeterminado adecuado y la hacemos visible. La ventana se rellenará con un elemento ` Map ` que muestra el mapa.

import QtQuick
import QtLocation
import QtPositioning

Window {
    width: Qt.platform.os == "android" ? Screen.width : 512
    height: Qt.platform.os == "android" ? Screen.height : 512
    visible: true
    title: map.center + " zoom " + map.zoomLevel.toFixed(3)
           + " min " + map.minimumZoomLevel + " max " + map.maximumZoomLevel

    Plugin {
        id: mapPlugin
        name: "osm"
    }

    Map {
        id: map
        anchors.fill: parent
        plugin: mapPlugin
        center: QtPositioning.coordinate(59.91, 10.75) // Oslo
        zoomLevel: 14
        property geoCoordinate startCentroid

        PinchHandler {
            id: pinch
            target: null
            onActiveChanged: if (active) {
                map.startCentroid = map.toCoordinate(pinch.centroid.position, false)
            }
            onScaleChanged: (delta) => {
                map.zoomLevel += Math.log2(delta)
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            onRotationChanged: (delta) => {
                map.bearing -= delta
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            grabPermissions: PointerHandler.TakeOverForbidden
        }
        WheelHandler {
            id: wheel
            // workaround for QTBUG-87646 / QTBUG-112394 / QTBUG-112432:
            // Magic Mouse pretends to be a trackpad but doesn't work with PinchHandler
            // and we don't yet distinguish mice and trackpads on Wayland either
            acceptedDevices: Qt.platform.pluginName === "cocoa" || Qt.platform.pluginName === "wayland"
                             ? PointerDevice.Mouse | PointerDevice.TouchPad
                             : PointerDevice.Mouse
            rotationScale: 1/120
            property: "zoomLevel"
        }
        DragHandler {
            id: drag
            target: null
            onTranslationChanged: (delta) => map.pan(-delta.x, -delta.y)
        }
        Shortcut {
            enabled: map.zoomLevel < map.maximumZoomLevel
            sequence: StandardKey.ZoomIn
            onActivated: map.zoomLevel = Math.round(map.zoomLevel + 1)
        }
        Shortcut {
            enabled: map.zoomLevel > map.minimumZoomLevel
            sequence: StandardKey.ZoomOut
            onActivated: map.zoomLevel = Math.round(map.zoomLevel - 1)
        }
    }
}

El elemento Plugin es necesario para definir el proveedor de mapas que vamos a utilizar. El ejemplo puede funcionar con cualquiera de los complementos de servicios geográficos disponibles. Sin embargo, algunos complementos pueden requerir parámetros adicionales para funcionar correctamente, y podemos utilizar PluginParameter para especificarlos. En este ejemplo, utilizamos el complemento osm, que es un complemento de OpenStreetMap deQt Location y no requiere ningún parámetro.

En el elemento « Map », hacemos referencia a la URL plugin que utilizamos y configuramos la longitud ( center ) y la latitud ( zoomLevel ) del mapa.

Requisitos

El ejemplo requiere una conexión a Internet operativa para descargar los mosaicos del mapa de OpenStreetMap. Un proxy del sistema opcional debería detectarse automáticamente.

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.