QML 지도

개요

Map 유형을 사용하면 지도를 표시하고 지도 내에 객체를 배치할 수 있습니다. 다양한 관심 지점을 정의하여 지도에 추가하고 표시할 수 있습니다. 또한 Map 에는 지도 표시 방식을 제어하는 기능이 포함되어 있습니다. Map 항목을 사용하면 지도를 중앙에 배치하고, 확대/축소하며, 핀치 제스처를 적용하고, 항목을 플릭할 수 있게 설정할 수 있습니다.

지도에 추가될 장소는 MapItems입니다. 항목의 위치는 위도, 경도 및 고도를 포함하는 geoCoordinate 로 정의됩니다. 항목은 Map 에 추가된 후 자동으로 표시됩니다.

지도상의 위치

모든 위치 관련 API는 QtPositioning 모듈에 포함되어 있습니다. 위치 정보의 기본 단위는 geoCoordinate 입니다. geoCoordinate 는 위치의 위도, 경도 및 고도 데이터를 캡슐화합니다. 고도는 미터 단위로 표시됩니다. 또한 다른 위치 geoCoordinate 까지의 거리를 계산하는 메서드도 제공합니다. geoCoordinate 유형은 Location 요소 내에 포함될 수도 있으며, 이 경우 위치와의 충분한 근접성을 판단하기 위한 경계 상자 크기와 위치 주소에 대한 정보도 포함됩니다.

다음은 position source 를 사용하여 map 를 현재 위치에 중앙 정렬하는 클라이언트의 예시입니다:

import QtPositioning
import QtLocation
...

Rectangle {

    Map {
        id: map
        // initialize map
        ...
    }

    PositionSource {
        onPositionChanged: {
            // center the map on the current position
            map.center = position.coordinate
        }
    }
}

지오코딩

지오코딩(Geocoding)은 위치에 대한 다른 지리적 참조 정보(예: 도로 주소)로부터 지리적 좌표(위도 및 경도)를 도출하는 과정입니다. 또한 도로 주소를 사용하여 지리적 좌표를 결정하는 역지오코딩(Reverse geocoding)도 가능합니다. 지오코딩은 GeocodeModel 타입을 사용하여 수행됩니다.

다음 코드 예제는 ‘Map Viewer (QML) ’ 예제에서 map 컴포넌트의 일부를 보여줍니다. 이 코드 조각은 GeocodeModel 컴포넌트의 선언을 보여줍니다.

이 코드 조각에서 볼 수 있듯이, ` GeocodeModel `에는 플러그인과 두 개의 신호 핸들러가 포함되어 있습니다. 하나는 상태 변경을 처리하고 onStatusChanged , 다른 하나는 Map 객체의 중심 위치를 업데이트하기 위한 신호 핸들러입니다 onLocationsChanged.

GeocodeModel {
    id: geocodeModel
    plugin: view.map.plugin
    onStatusChanged: {
        if ((status == GeocodeModel.Ready) || (status == GeocodeModel.Error))
            view.geocodeFinished()
    }
    onLocationsChanged:
    {
        if (count === 1) {
            view.map.center.latitude = get(0).coordinate.latitude
            view.map.center.longitude = get(0).coordinate.longitude
        }
    }
}

MapItemView {
    parent: view.map
    model: geocodeModel
    delegate: pointDelegate
}

지오코딩 기능은 상위 수준의 코드에서 호출됩니다. 이 코드 조각에서는 원하는 매개변수로 채워진 Address 객체를 볼 수 있습니다.

Address {
    id :fromAddress
    street: "Sandakerveien 116"
    city: "Oslo"
    country: "Norway"
    state : ""
    postalCode: "0484"
}

Address 는 이후 GeocodeModel 에 대한 쿼리에 사용되어 지리적 coordinates 를 처리하고 결정합니다.

// send the geocode request
geocodeModel.query = fromAddress
geocodeModel.update()

Map 유형의 매우 중요한 기능은 경로상의 경유지를 포함하여 한 장소에서 목적지까지 이동하는 내비게이션입니다. 경로는 일련의 세그먼트로 나뉩니다. 각 세그먼트의 끝에는 ‘기동(maneuver)’이라고 하는 정점이 있습니다. 세그먼트에는 세그먼트 끝까지의 소요 시간과 거리에 대한 정보가 포함되어 있습니다. 기동(maneuver )에는 다음에 무엇을 해야 하는지, 다음 세그먼트가 있다면 어떻게 그 세그먼트로 진입해야 하는지에 대한 정보가 포함됩니다. 따라서 기동에는 “지금 우회전하라”와 같은 내비게이션 정보가 포함됩니다.

적합한 경로를 찾으려면 ` RouteQuery `를 사용하여 선택 기준을 정의하고 필요한 경유지를 추가해야 합니다. ` RouteModel `는 ` routeSegment` 목록을 반환해야 하며, 이 목록은 목적지까지의 경로를 정의하고 세그먼트 간 연결 지점(` routeManeuver`라고 함)에 대한 내비게이션 안내를 포함합니다.

쿼리에 다양한 옵션을 추가하여 조건을 더 구체화할 수 있습니다. RouteQuery 속성에는 다음이 포함될 수 있습니다.

numberAlternativeRoutes	대체 경로의 수
travelModes	이동 수단
routeOptimizations	필요한 경로 최적화
segmentDetail	구간의 상세 수준
maneuverDetail	구간 간 기동 세부 수준
waypoints	경유지 목록
excludedAreas	경로가 통과해서는 안 되는 제외 구역 목록
featureTypes	관련 지도 특징(예: 고속도로, 페리)

다음 예제에서는 ` RouteModel` 내에서 기본 경로 객체( RouteQuery )가 선언됩니다.

RouteModel {
    id: routeModel
    plugin : view.map.plugin
    query:  RouteQuery {
        id: routeQuery
    }
    onStatusChanged: {
        if (status == RouteModel.Ready) {
            switch (count) {
            case 0:
                // technically not an error
                view.routeError()
                break
            case 1:
                view.showRouteList()
                break
            }
        } else if (status == RouteModel.Error) {
            view.routeError()
        }
    }
}

사용자는 경로의 출발지, 몇 개의 경유지 및 목적지와 같은 정보를 입력합니다. 이 모든 위치는 경유지이므로, 출발지부터 도착지까지의 경로는 일련의 경유지로 입력됩니다. 그런 다음 이 여정에 특화된 다른 쿼리 속성을 설정할 수 있습니다.

// clear away any old data in the query
routeQuery.clearWaypoints();
// add the start and end coords as waypoints on the route
routeQuery.addWaypoint(startCoordinate)
routeQuery.addWaypoint(endCoordinate)
routeQuery.travelModes = RouteQuery.CarTravel
routeQuery.routeOptimizations = RouteQuery.FastestRoute
routeModel.update();

routeInfoModel ListModel은 쿼리 결과를 가져와 표시하기에 적합한 목록을 구성하는 데 사용됩니다.

ListView {
    interactive: true
    model: ListModel { id: routeInfoModel }
    header: RouteListHeader {}
    delegate:  RouteListDelegate{
        routeIndex.text: index + 1
        routeInstruction.text: instruction
        routeDistance.text: distance
    }
}

routeInfoModel ListModel은 코드를 사용하여 값을 채울 수 있으며, 이 코드는 세그먼트를 순회하며 세그먼트 길이, 안내 문구 및 다음 안내 지점까지의 거리를 추출합니다. 추출된 데이터는 가져오는 즉시 표시용으로 형식이 지정됩니다.

routeInfoModel.clear()
if (routeModel.count > 0) {
    for (var i = 0; i < routeModel.get(0).segments.length; i++) {
        routeInfoModel.append({
            "instruction": routeModel.get(0).segments[i].maneuver.instructionText,
             "distance": Helper.formatDistance(routeModel.get(0).segments[i].maneuver.distanceToNextInstruction)
        });
    }
}

이 예제에 대한 자세한 내용은 ‘Map Viewer (QML) ’ 예제를 참조하십시오.

확대/축소, 핀치, 플릭 지원

Map 항목은 터치 및 마우스 제스처를 사용한 지도와의 사용자 인터페이스 상호작용도 지원합니다. 즉, 스와이프하여 이동하거나 핀치 제스처로 확대/축소하는 등의 기능을 말합니다.

MapView 유형 내에서 핀치 및 플릭 기능을 활성화하고 구성하는 것은 쉽습니다.

MapView {
    id: view
TapHandler {
    id: tapHandler
    property variant lastCoordinate
    acceptedButtons: Qt.LeftButton | Qt.RightButton

    onPressedChanged: (eventPoint, button) => {
        if (pressed) {
            lastCoordinate = view.map.toCoordinate(tapHandler.point.position)
        }
    }

    onSingleTapped: (eventPoint, button) => {
            if (button === Qt.RightButton) {
                showMainMenu(lastCoordinate)
            }
    }

    onDoubleTapped: (eventPoint, button) => {
        var preZoomPoint = view.map.toCoordinate(eventPoint.position);
        if (button === Qt.LeftButton) {
            view.map.zoomLevel = Math.floor(view.map.zoomLevel + 1)
        } else if (button === Qt.RightButton) {
            view.map.zoomLevel = Math.floor(view.map.zoomLevel - 1)
        }
        var postZoomPoint = view.map.toCoordinate(eventPoint.position);
        var dx = postZoomPoint.latitude - preZoomPoint.latitude;
        var dy = postZoomPoint.longitude - preZoomPoint.longitude;

        view.map.center = QtPositioning.coordinate(view.map.center.latitude - dx,
                                                   view.map.center.longitude - dy);
    }
}
}

확대/축소는 Map zoomLevel 에 바인딩하여 슬라이더와 같은 다른 객체를 통해서도 제어할 수 있습니다.

QML 유형

지도

GeoJsonData	GeoJSON 문서를 표현, 로드 및 저장하기 위한 모델
Map	지도(Map)를 표시하는 타입
MapCircle	지도에 지리적 원을 표시하는 타입
MapCopyrightNotice	항목은 지도 요소에 대한 현재 유효한 저작권 고지를 표시합니다
MapItemGroup	Type은 지도 항목을 담는 컨테이너입니다
MapItemView	모델에서 지도를 채우는 데 사용됩니다
MapPolygon	타입은 지도에 다각형을 표시합니다
MapPolyline	Type은 지도에 폴리라인을 표시합니다
MapQuickItem	이 타입은 지도에 임의의 Qt Quick 객체를 표시합니다
MapRectangle	Type은 지도에 사각형을 표시합니다
MapRoute	이 유형은 지도에 경로를 표시합니다
cameraCapabilities	Type은 특정 지도 유형에 대한 카메라 기능 정보를 포함합니다
mapType	이 타입은 지도 유형에 대한 정보를 보유합니다

지오코딩

GeocodeModel

Type은 지리 정보와 관련된 검색 작업을 지원합니다

경로 안내

RouteModel	Type은 경로에 대한 액세스를 제공합니다
RouteQuery	이 타입은 RouteModel에 쿼리 매개변수를 제공하는 데 사용됩니다
route	이 타입은 하나의 지리적 경로를 나타냅니다
routeManeuver	Type은 두 routeSegment가 만나는 지점과 관련된 정보를 나타냅니다
routeSegment	Type은 경로의 한 세그먼트를 나타냅니다

예시

위의 코드 조각은 Map Viewer(QML) 예제에서 발췌한 것입니다.

장소 백엔드 지도 QML API

© 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.