QML 맵

개요

Map 유형은 지도를 표시하고 지도 내에 개체를 배치할 수 있습니다. 다양한 관심 지점을 정의하고 지도에 추가하여 표시할 수 있습니다. 또한 Map 유형에는 지도 표시 방식을 제어할 수 있는 기능이 있습니다. 지도 항목을 사용하여 지도를 가운데에 배치하고, 확대/축소하고, 핀치하고, 항목을 플릭 가능하게 만들 수 있습니다.

지도에 추가할 장소는 MapItems입니다. 항목의 위치는 위도, 경도 및 고도를 포함하는 coordinate 으로 정의됩니다. 그런 다음 항목이 Map 에 추가되면 자동으로 표시됩니다.

지도상의 위치

모든 위치 API는 QtPositioning 모듈의 일부입니다. 위치 정보의 기본은 coordinate 좌표입니다. 좌표는 위치의 위도, 경도 및 고도에 대한 데이터를 캡슐화합니다. 고도는 미터 단위입니다. 또한 다른 coordinate 까지의 거리를 결정하는 방법도 있습니다. coordinate 유형은 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
        }
    }
}

지오코딩

지오코딩은 위치에 대한 다른 지리적 참조로부터 지리적 좌표(위도 및 경도)를 도출하는 것입니다. 예를 들어 거리 주소가 여기에 해당합니다. 지리적 좌표를 결정하기 위해 도로 주소를 사용하는 역 지오코딩도 가능합니다. 지오코딩은 GeocodeModel 유형을 사용하여 수행됩니다.

다음 코드 예제는 맵 뷰어(QML ) 예제의 map 컴포넌트의 일부입니다. 코드 조각은 GeocodeModel 구성 요소의 선언을 보여줍니다.

코드 조각에서 [QML]{GeocodeModel}에는 플러그인과 두 개의 시그널 핸들러가 포함되어 있음을 알 수 있습니다. 하나는 상태 변경을 위한 것이고 onStatusChanged 를 변경하고 다른 하나는 맵 객체의 중심을 업데이트하기 위한 것입니다. 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 유형의 매우 중요한 기능은 경로를 따라 가능한 경유지가 있는 한 장소에서 목적지까지의 내비게이션입니다. 경로는 일련의 세그먼트로 나뉩니다. 각 세그먼트의 끝에는 기동이라는 정점이 있습니다. 세그먼트에는 세그먼트의 끝까지의 시간과 거리에 대한 정보가 포함되어 있습니다. 기동에는 다음에 해야 할 일, 다음 세그먼트가 있는 경우 그 세그먼트로 이동하는 방법에 대한 정보가 포함되어 있습니다. 따라서 기동에는 내비게이션 정보(예: "지금 우회전")가 포함됩니다.

적합한 경로를 찾으려면 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
    }
}

ListModel routeInfoModel 은 세그먼트 길이, 명령어 텍스트 및 다음 명령어까지의 거리를 추출하는 세그먼트를 반복하는 코드를 사용하여 값으로 채울 수 있습니다. 추출된 데이터는 검색되는 대로 표시할 수 있도록 형식이 지정됩니다.

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

이 예제에 대한 자세한 내용은 지도 뷰어(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);
    }
}
}

확대/축소는 슬라이더와 같은 다른 객체로도 제어할 수 있으며, 지도 zoomLevel 에 바인딩할 수도 있습니다.

QML 유형

지도

GeoJsonData

GeoJSON 문서를 표현, 로드 및 저장하는 모델입니다.

Map

유형은 지도를 표시합니다.

MapCircle

유형은 맵에 지리적 원을 표시합니다.

MapCopyrightNotice

항목은 맵 요소에 대한 현재 유효한 저작권 고지를 표시합니다.

MapItemGroup

유형은 맵 항목의 컨테이너입니다.

MapItemView

모델에서 맵을 채우는 데 사용됩니다.

MapPolygon

유형은 맵에 다각형을 표시합니다.

MapPolyline

유형은 맵에 폴리라인을 표시합니다.

MapQuickItem

유형은 맵에 임의의 Qt Quick 개체를 표시합니다.

MapRectangle

유형은 맵에 직사각형을 표시합니다.

MapRoute

유형은 지도에 경로를 표시합니다.

cameraCapabilities

유형은 특정 맵 유형에 대한 카메라 기능에 대한 정보를 보유합니다.

mapType

유형은 지도 유형에 대한 정보를 보유합니다.

지오코딩

GeocodeModel

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

라우팅

RouteModel

유형은 경로에 대한 액세스를 제공합니다.

RouteQuery

유형은 RouteModel에 쿼리 매개변수를 제공하는 데 사용됩니다.

route

유형은 하나의 지리적 경로를 나타냅니다.

routeManeuver

Type은 두 개의 RouteSegment가 만나는 지점과 관련된 정보를 나타냅니다.

routeSegment

유형은 경로의 세그먼트를 나타냅니다.

예제

위의 스니펫은 지도 뷰어(QML ) 예제에서 가져온 것입니다.

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