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 을 사용하여 이를 지정할 수 있습니다. 이 예제에서는 Qt Location Open Street Map 플러그인인 osm 플러그인을 사용하며, 이 플러그인은 별도의 매개변수가 필요하지 않습니다.

‘ Map ’ 항목에서 사용하는 plugin 을 참조하고, 지도의 center 및 zoomLevel 을 설정합니다.

필수 조건

이 예제를 실행하려면 OpenStreetMap 지도 타일을 다운로드할 수 있도록 인터넷 연결이 정상적으로 작동해야 합니다. 선택 사항인 시스템 프록시는 자동으로 감지됩니다.

코드.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.