Mapa mínimo (QML)

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

Minimal Map muestra cómo utilizar el elemento Map para mostrar un mapa. Muestra la cantidad mínima de código necesaria para mostrar el mapa, y puede utilizarse como base para posteriores experimentos.

Ejecución del ejemplo

Para ejecutar el ejemplo desde Qt Creatorabra el modo Welcome y seleccione el ejemplo de Examples. Para más información, consulte Qt Creator: Tutorial: Construir y ejecutar.

Código C

En main.cpp utilizamos únicamente las clases QGuiApplication y QQmlApplicationEngine.

#include <QGuiApplication>
#include <QQmlApplicationEngine>

En la función principal, primero instanciamos un objeto QGuiApplication. Luego creamos un QQmlApplicationEngine y le decimos que cargue main.qml desde el Sistema de Recursos Qt.

Finalmente, QGuiApplication::exec() lanza 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, establecemos un tamaño por defecto razonable y la hacemos visible. La ventana será rellenada por 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 plugins de servicios geográficos disponibles. Sin embargo, algunos plugins pueden requerir parámetros adicionales para funcionar correctamente y podemos utilizar PluginParameter para especificarlos. En este ejemplo, utilizamos el plugin osm, que es un plugin de Open Street Map deQt Location y no requiere ningún parámetro.

En el elemento Map, hacemos referencia al plugin que utilizamos y establecemos el center y el zoomLevel del mapa.

Requisitos

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

Proyecto de ejemplo @ 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.