Back to Qt.io
Contact Us Blog Download Qt
本页内容

简约地图（QML）

使用Qt Quick 显示地图所需的最小代码量。

应用程序窗口中显示了一张奥斯陆市中心的地图

“简易地图”演示了如何使用Map 控件来渲染地图。它展示了显示地图所需的最小代码量，可作为进一步实验的基础。

运行示例

您可以通过以下方式运行示例：

C++ 代码

在main.cpp 中，我们仅使用QGuiApplication 和QQmlApplicationEngine 这两个类。

#include <QGuiApplication>
#include <QQmlApplicationEngine>

在 main 函数中，我们首先实例化一个QGuiApplication 对象。然后创建一个QQmlApplicationEngine 并指示其从Qt 资源系统中加载main.qml 。

最后，QGuiApplication::exec() 启动主事件循环。

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

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

    return app.exec();
}

QML 代码

在 `main.qml` 中，我们导入了 `QtLocation ` QML 模块及其依赖的 `QtPositioning ` QML 模块。接下来，我们创建顶级窗口，设置一个合理的默认尺寸，并使其可见。该窗口将由一个显示地图的 `Map ` 项填充。

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

Plugin 项用于定义我们将要使用的地图提供程序。该示例可与任何可用的地理服务插件配合使用。不过，某些插件可能需要额外的插件参数才能正常工作，我们可以使用PluginParameter 来指定这些参数。在本示例中，我们使用osm 插件，这是一个Qt Location 的OpenStreetMap插件，无需任何参数。

在“Map ”项中，我们引用所使用的plugin ，并设置地图的center 和zoomLevel 。

要求

该示例需要有效的互联网连接以下载OpenStreetMap 地图图块。系统代理（可选）应被自动检测。

示例项目 @ 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.