Mapa mínimo (QML)
El código mínimo para mostrar un mapa utilizando Qt Quick.

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:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo de Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde « Command Palette » y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
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.
© 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.