Map QML Type

'지도' 유형은 지도를 표시합니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록
• Map은 QML Maps 플러그인의 일부입니다.

속성

• activeMapType : mapType
• bearing : real (since QtLocation 5.9)
• center : coordinate
• color : color
• copyrightsVisible : bool
• error : enumeration
• errorString : string
• fieldOfView : real (since QtLocation 5.9)
• mapItems : list<MapItem>
• mapReady : bool
• maximumFieldOfView : real (since QtLocation 5.9)
• maximumTilt : real (since QtLocation 5.9)
• maximumZoomLevel : real
• minimumFieldOfView : real (since QtLocation 5.9)
• minimumTilt : real (since QtLocation 5.9)
• minimumZoomLevel : real
• plugin : Plugin
• supportedMapTypes : list<mapType>
• tilt : real (since QtLocation 5.9)
• visibleArea : rect
• visibleRegion : geoShape
• zoomLevel : real

신호

• copyrightLinkActivated(string link)

방법

• void addMapItem(MapItem item)
• void addMapItemGroup(MapItemGroup itemGroup)
• void addMapItemView(MapItemView itemView)
• void alignCoordinateToPoint(coordinate coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void fitViewportToGeoShape(geoShape, margins)
• void fitViewportToMapItems(list<MapItems> items)
• void fitViewportToVisibleMapItems()
• point fromCoordinate(coordinate coordinate, bool clipToViewPort)
• void pan(int dx, int dy)
• void prefetchData()
• void removeMapItem(MapItem item)
• void removeMapItemGroup(MapItemGroup itemGroup)
• void removeMapItemView(MapItemView itemView)
• void setBearing(real bearing, coordinate coordinate)
• coordinate toCoordinate(QPointF position, bool clipToViewPort)

상세 설명

'지도' 유형은 지도의 표면이나 지구 이미지를 표시하는 데 사용되며, 지도 표면에 연결된 상호작용 가능한 객체를 표시할 수도 있습니다.

지구 표면을 2차원 방식으로 시각화하는 방법은 다양하지만, 모두 일종의 투영법, 즉 3차원 좌표(위도, 경도, 고도)와 화면상의 2차원 좌표(픽셀 단위의 X, Y) 간의 수학적 관계를 포함합니다.

지도 데이터의 출처에 따라 서로 다른 투영법이 사용될 수 있으며, Map 유형의 관점에서 우리는 이를 하나의 교체 가능한 단위, 즉 Map 플러그인으로 취급합니다. Map 플러그인은 데이터 소스와 화면에 데이터를 표시하는 데 필요한 기타 모든 세부 정보로 구성됩니다.

현재 사용 중인 지도 플러그인은 지도 항목의 ` plugin ` 속성에 포함되어 있습니다. 지도 항목에 이미지를 표시하려면 이 속성을 설정해야 합니다. 사용에 적합한 플러그인을 가져오는 방법에 대한 설명은 ` Plugin ` 타입을 참조하십시오.

Map 항목에 표시되는 지리적 영역을 뷰포트라고 하며, 이는 center 및 zoomLevel 속성으로 정의됩니다. center 속성에는 뷰포트의 중심을 지정하는 geoCoordinate 가 포함되어 있으며, zoomLevel 는 지도의 축척을 제어합니다. 각 속성의 값에 대한 자세한 내용은 해당 속성 설명을 참조하십시오.

지도가 표시되면, 화면에 보이는 모든 지리적 좌표는 화면상의 특정 픽셀 X 및 Y 좌표에 매핑됩니다. 이 두 좌표 간 변환을 수행하기 위해 Map은 범용적으로 사용할 수 있는 ` toCoordinate ` 및 ` fromCoordinate ` 함수를 제공합니다.

Map 객체

Map 관련 객체는 ` Qt Quick ` 내의 Map 객체 본문에서 선언할 수 있으며, 자동으로 Map에 표시됩니다. 프로그래밍 방식으로 객체를 추가하려면, 먼저 해당 객체가 Map을 부모로 하여 생성되었는지 확인해야 합니다(예: ` Component::createObject`의 인자에서). 그런 다음, 해당 객체의 유형이 MapCircle, MapRectangle, MapPolyline, MapPolygon, MapRoute 또는 MapQuickItem 중 하나라면, Map에서 addMapItem 메서드를 호출하십시오. 반대로, Map에서 위의 유형에 해당하는 맵 객체를 제거하기 위한 removeMapItem 메서드도 존재합니다.

맵 객체를 이동하거나 크기를 조정하거나 모양을 변경하는 작업은 일반적으로 맵 자체와의 특별한 상호작용을 필요로 하지 않습니다. 맵 객체에서 이러한 속성을 변경하면 표시 내용이 자동으로 업데이트됩니다.

성능

지도는 OpenGL (ES) 및 Qt Scene Graph 스택을 사용하여 렌더링되므로, GL 가속 하드웨어가 사용 가능한 환경에서는 상당히 우수한 성능을 발휘합니다.

"온라인" 지도의 경우, 네트워크 대역폭과 지연 시간이 사용자가 느끼는 성능에 큰 영향을 미칠 수 있습니다. 이를 완화하기 위해 광범위한 캐싱이 수행되지만, 이러한 완화 조치가 항상 완벽한 것은 아닙니다.

일반적으로, 정점 수가 많은 폴리곤이나 폴리라인과 같이 크고 복잡한 지도 항목은 UI 성능에 부정적인 영향을 미칠 수 있습니다.

사용 예

다음 코드 조각은 간단한 지도와 이를 사용하는 데 필요한 플러그인 유형을 보여줍니다. 지도는 노르웨이 오슬로를 중심으로 확대/축소 수준 14로 설정되어 있습니다.

import QtQuick
import QtLocation
import QtPositioning

Window {
    ...
    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)
        }
    }
}

속성 문서

activeMapType : mapType

현재 활성화된 ‘ map type ’에 대한 액세스.

이 속성을 설정하여 활성 상태인 map type 을 변경할 수 있습니다. 가능한 값에 대해서는 supportedMapTypes 속성을 참조하십시오.

mapType도 참조하십시오 .

bearing : real [since QtLocation 5.9]

이 속성은 지도의 방위각을 저장합니다. 기본값은 0입니다. 지도에 사용된 플러그인이 방위각을 지원하는 경우, 이 값의 유효 범위는 0에서 360 사이입니다. 지도에 사용된 플러그인이 방위각을 지원하지 않는 경우, 이 속성을 변경해도 아무런 효과가 없습니다.

이 속성은 QtLocation 5.9에서 도입되었습니다.

center : coordinate

이 속성은 매핑 뷰포트의 중심을 차지하는 좌표를 저장합니다. 유효하지 않은 중심 좌표는 무시됩니다.

기본값은 임의의 유효한 좌표입니다.

color : color

이 속성은 지도 요소의 배경색을 지정합니다.

copyrightsVisible : bool

이 속성은 저작권 고지의 표시 여부를 결정합니다. 이 고지는 일반적으로 화면 왼쪽 하단에 표시됩니다. 기본적으로 이 속성은 ‘ true ’로 설정되어 있습니다.

error : enumeration [read-only]

이 읽기 전용 속성은 가장 최근에 발생한 매핑 서비스 공급자 오류를 저장합니다.

• Map.NoError —오류가 발생하지 않았습니다.
• Map.xml-ph-0000@deepl.internal: 오류가 발생하지 않았습니다. Map.NotSupportedError: 맵 플러그인 속성이 설정되지 않았거나 플러그인과 연결된 매핑 관리자가 없습니다.
• Map.xml-ph-0000@deepl.internal: 오류가 발생하지 않았습니다.Map.NotSupportedError: 플러그인이 제공된 매개 변수 중 하나를 인식하지 못했습니다.
• Map.MissingRequiredParameterError - 플러그인이 예상한 매개 변수 중 하나를 찾지 못했습니다.
• Map.ConnectionError - 플러그인이 백엔드 서비스나 데이터베이스에 연결할 수 없습니다.

QGeoServiceProvider::Error도 참조하십시오 .

errorString : string [read-only]

이 읽기 전용 속성은 가장 최근의 매핑 공급자 오류에 대한 텍스트 표현을 포함합니다. 오류가 발생하지 않은 경우, 빈 문자열이 반환됩니다.

텍스트로 표현할 수 없는 오류가 발생한 경우에도 빈 문자열이 반환될 수 있습니다.

QGeoServiceProvider::errorString()도 참조하십시오 .

fieldOfView : real [since QtLocation 5.9]

이 속성은 지도를 보는 데 사용되는 카메라의 시야각을 도(°) 단위로 저장합니다. 지도의 플러그인 속성이 설정되어 있지 않거나, 플러그인이 지도 기능을 지원하지 않는 경우, 이 값은 45도로 설정됩니다.

이 값을 변경하면 카메라와 지도 사이의 거리도 암묵적으로 변경되므로, 기울기 각도가 0도일 경우 이 속성에 어떤 값을 사용하더라도 결과 이미지는 동일하다는 점에 유의하십시오.

이 매개변수에 대한 자세한 내용은 위키백과의 ‘시야각( Field of view )’ 및 ‘시야각(Angle of view)’ 문서를 참조하십시오.

이 속성은 QtLocation 5.9에서 도입되었습니다.

minimumFieldOfView 및 maximumFieldOfView도 참조하십시오 .

mapItems : list<MapItem> [read-only]

특정 순서 없이 맵의 모든 항목 목록을 반환합니다. 이 항목들에는 유형 선언의 일부로 정적으로 선언된 항목은 물론, 동적 항목(addMapItem, MapItemView)도 포함됩니다.

addMapItem, removeMapItem, clearMapItems도 참조하십시오 .

mapReady : bool [read-only]

이 속성은 맵이 성공적으로 초기화되어 사용 준비가 되었는지 여부를 나타냅니다. ` fromCoordinate ` 및 ` toCoordinate`과 같은 일부 메서드는 맵이 준비되기 전에는 작동하지 않습니다. ` Map`의 아키텍처 특성상, 모든 기능이 예상대로 작동하도록 하려면 ` Component.onCompleted` 대신 이 속성에 대해 발신되는 신호를 사용하는 것이 좋습니다.

maximumFieldOfView : real [since QtLocation 5.9]

이 속성은 지도에 대한 유효한 최대 시야각을 도(°) 단위로 저장합니다.

사용되는 plugin 의 최소 틸트 시야각은 이 속성의 상한값입니다. plugin 속성이 설정되지 않았거나 플러그인이 매핑을 지원하지 않는 경우, 이 속성의 값은 179 입니다.

이 속성은 QtLocation 5.9에서 도입되었습니다.

fieldOfView 및 minimumFieldOfView도 참조하십시오 .

maximumTilt : real [since QtLocation 5.9]

이 속성은 지도의 최대 유효 경사각을 도(°) 단위로 저장합니다.

사용 중인 plugin 에서 정의한 최대 틸트 값은 이 속성의 상한값입니다. plugin 속성이 설정되지 않았거나 플러그인이 매핑을 지원하지 않는 경우, 이 속성의 값은 89.5 입니다.

QtLocation 5.12부터 플러그인은 현재 줌 레벨에 따라 이 값을 추가로 제한할 수 있습니다.

이 속성은 QtLocation 5.9에서 도입되었습니다.

tilt 및 minimumTilt도 참조하십시오 .

maximumZoomLevel : real

이 속성은 지도의 유효한 최대 확대/축소 수준을 지정합니다.

최대 확대/축소 수준은 사용 중인 지도 객체( plugin )에 의해 정의됩니다. plugin 속성이 설정되지 않았거나 플러그인이 지도 기능을 지원하지 않는 경우, 이 속성의 값은 ' 30'입니다.

minimumFieldOfView : real [since QtLocation 5.9]

이 속성은 지도의 최소 유효 시야각을 도(°) 단위로 나타냅니다.

사용되는 plugin 의 최소 틸트 시야각은 이 속성의 하한값입니다. plugin 속성이 설정되지 않았거나 플러그인이 매핑을 지원하지 않는 경우, 이 속성의 값은 1 입니다.

이 속성은 QtLocation 5.9에서 도입되었습니다.

fieldOfView 및 maximumFieldOfView도 참조하십시오 .

minimumTilt : real [since QtLocation 5.9]

이 속성은 맵의 유효한 최소 기울기 값을 도(°) 단위로 저장합니다.

사용 중인 plugin 에 의해 정의된 최소 틸트 값은 이 속성의 하한값입니다. plugin 속성이 설정되지 않았거나 플러그인이 매핑을 지원하지 않는 경우, 이 속성의 값은 0 입니다.

QtLocation 5.12부터 플러그인은 현재 줌 레벨에 따라 이 값을 추가로 제한할 수 있습니다.

이 속성은 QtLocation 5.9에서 도입되었습니다.

tilt 및 maximumTilt도 참조하십시오 .

minimumZoomLevel : real

이 속성은 지도의 유효한 최소 확대/축소 수준을 나타냅니다.

사용 중인 plugin 에 의해 정의된 최소 확대/축소 수준은 이 속성의 하한값입니다. 그러나 반환되는 값은 캔버스 크기에 따라 달라지며, 지도가 어느 한 축에서도 뷰포트보다 작아지지 않도록 하기 위해 사용자가 지정한 값이나 사용 중인 플러그인이 정의한 최소 확대/축소 수준보다 더 높을 수 있습니다.

plugin 속성이 설정되지 않았거나 플러그인이 매핑을 지원하지 않는 경우, 이 속성의 값은 ` 0`입니다.

plugin : Plugin

이 속성은 매핑 기능을 제공하는 플러그인을 저장합니다.

이 속성은 한 번만 쓰기 가능한 속성입니다. 맵에 플러그인이 한 번 연결되면, 이후 플러그인을 수정하려는 모든 시도는 무시됩니다.

supportedMapTypes : list<mapType> [read-only]

이 읽기 전용 속성은 이 맵에서 지원하는 map types 세트를 포함합니다.

activeMapType도 참조하십시오 .

tilt : real [since QtLocation 5.9]

이 속성은 지도의 기울기(도 단위)를 나타냅니다. 기본값은 0입니다. 이 값의 유효 범위는 [ minimumTilt, maximumTilt ]입니다. 지도에 사용된 플러그인이 기울기 기능을 지원하지 않는 경우, 이 속성을 변경해도 아무런 효과가 없습니다.

이 속성은 QtLocation 5.9에서 도입되었습니다.

minimumTilt 및 maximumTilt도 참조하십시오 .

visibleArea : rect

이 속성은 Map QML 요소 내부의 표시 영역을 나타냅니다. 이는 Map 요소를 기준으로 한 좌표를 갖는 rect입니다. 이 영역의 크기는 Map 요소의 크기에 맞춰 제한됩니다. visibleArea가 null인 경우, Map 전체가 표시됨을 의미합니다.

visibleRegion : geoShape

이 속성은 지도의 뷰포트를 차지하는 영역을 나타냅니다. 카메라는 해당 도형의 중심에 위치하며, 도형 전체가 화면에 표시될 수 있는 최대 정수 배율로 설정됩니다. 즉, 이 속성을 설정한 직후 다시 읽으면 반환되는 면적이 설정된 면적과 같거나 더 큽니다.

이 속성을 설정하면 지도의 ` center ` 및 ` zoomLevel ` 속성이 암시적으로 변경됩니다. 해당 속성에 이전에 설정된 값은 모두 덮어쓰게 됩니다.

zoomLevel : real

이 속성은 지도의 확대/축소 수준을 지정합니다.

줌 레벨 값이 클수록 더 상세한 지도를 볼 수 있습니다. 줌 레벨은 항상 0 이상입니다. 기본값은 8.0입니다. 사용 중인 플러그인에 따라, 타일이 제공되는 범위인 [minimumZoomLevel, maximumZoomLevel] 범위를 벗어난 값이 허용되거나 제한될 수 있습니다.

Signal 문서

copyrightLinkActivated(string link)

이 신호는 사용자가 저작권 고지문 내의 link 링크를 클릭할 때 발생합니다. 애플리케이션은 해당 링크를 브라우저에서 열거나 사용자에게 그 내용을 표시해야 합니다.

메서드 문서

void addMapItem(MapItem item)

지정된 item 객체를 Map에 추가합니다(예: MapQuickItem, MapCircle). 해당 객체가 이미 Map에 존재하는 경우, 다시 추가되지 않습니다.

예를 들어, 현재 위치를 나타내는 MapCircle 가 있는 경우를 생각해 보겠습니다:

import QtQuick
import QtPositioning
import QtLocation

PositionSource {
    id: positionSource
}

Map {
    id: map
    property MapCircle circle

    Component.onCompleted: {
        circle = Qt.createQmlObject('import QtLocation; MapCircle {}', page)
        circle.center = positionSource.position.coordinate
        circle.radius = 5000.0
        circle.color = 'green'
        circle.border.width = 3
        map.addMapItem(circle)
    }
}

mapItems, removeMapItem 및 clearMapItems도 참조하십시오 .

void addMapItemGroup(MapItemGroup itemGroup)

지정된 itemGroup 에 포함된 맵 항목을 Map에 추가합니다(예: MapQuickItem, MapCircle).

MapItemGroup 및 removeMapItemGroup도 참조하십시오 .

void addMapItemView(MapItemView itemView)

itemView 를 지도에 추가합니다.

MapItemView 및 removeMapItemView도 참조하십시오 .

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

coordinate 를 point 에 정렬합니다. 이 메서드는 center qml 속성이 제공하는 기능을 효과적으로 확장하여, 좌표를 Map 요소의 중심이 아닌 다른 지점에 정렬할 수 있게 해줍니다. 이는 장면의 중심(예: 커서)을 지도의 정중앙에 정확히 배치하지 않아야 하는 애플리케이션에서 유용합니다.

지도가 기울어져 있어 coordinate 이 카메라 뒤쪽에 위치하거나, 지도가 준비되지 않은 경우( mapReady 참조), 이 메서드를 호출해도 아무런 효과가 없습니다.

Qt 5.10에 포함된 이 API는 기술 미리보기(Technology Preview)입니다.

center도 참조하십시오 .

void clearData()

현재 선택된 플러그인이 수집한 지도 데이터를 삭제합니다.

plugin도 참조하십시오 .

void clearMapItems()

맵에서 모든 항목과 항목 그룹을 제거합니다.

mapItems, addMapItem, removeMapItem, addMapItemGroup, removeMapItemGroup도 참조하십시오 .

void fitViewportToGeoShape(geoShape, margins)

뷰포트를 특정 지리적 도형 geoShape 에 맞춥니다. margins 는 화면 픽셀 단위입니다.

visibleRegion도 참조하십시오 .

void fitViewportToMapItems(list<MapItems> items = {})

인수가 지정되지 않으면, 현재 뷰포트를 모든 지도 항목의 경계에 맞추게 됩니다. 카메라는 지도 항목의 중앙에 위치하며, 화면에 모든 지도 항목이 표시될 수 있는 최대 정수 배율로 설정됩니다. ` items `가 지정되면, 현재 뷰포트를 지정된 지도 항목의 경계에 대해서만 맞추게 됩니다.

fitViewportToVisibleMapItems도 참조하십시오 .

void fitViewportToVisibleMapItems()

현재 뷰포트를 화면에 표시되는 모든 지도 항목의 경계에 맞춥니다. 카메라는 지도 항목의 중앙에 위치하며, 화면에 모든 지도 항목이 표시될 수 있는 최대의 정수 배율로 설정됩니다.

fitViewportToMapItems도 참조하십시오 .

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

coordinate 에 해당하는 지도 항목에 대한 상대적 위치를 반환합니다.

clipToViewPort 가 true 이거나, 가 지정되지 않은 경우, coordinate 가 현재 뷰포트 내에 포함되지 않으면 무효한 QPointF 를 반환합니다.

void pan(int dx, int dy)

x축을 따라 dx 픽셀, y축을 따라 dy 픽셀만큼 지도를 이동하기 시작합니다.

dx 의 양수 값은 지도를 오른쪽으로 이동시키고, 음수 값은 왼쪽으로 이동시킵니다. dy 의 양수 값은 지도를 아래로 이동시키고, 음수 값은 위로 이동시킵니다.

패닝 중에는 center 및 zoomLevel 값이 변경될 수 있습니다.

void prefetchData()

이 유휴 기간 동안 맵을 미리 불러올 수 있도록 하는 선택적 힌트

void removeMapItem(MapItem item)

지정된 item 을 맵에서 제거합니다(예: MapQuickItem, MapCircle). MapItem이 존재하지 않거나 이전에 맵에 추가된 적이 없는 경우, 이 메서드는 아무 작업도 수행하지 않습니다.

mapItems, addMapItem 및 clearMapItems도 참조하십시오 .

void removeMapItemGroup(MapItemGroup itemGroup)

itemGroup 와 그 안에 포함된 항목을 맵에서 제거합니다.

MapItemGroup 및 addMapItemGroup도 참조하십시오 .

void removeMapItemView(MapItemView itemView)

itemView 와 이에 의해 인스턴스화된 항목들을 Map에서 제거합니다.

MapItemView 및 addMapItemView도 참조하십시오 .

void setBearing(real bearing, coordinate coordinate)

지도의 방위각을 bearing 로 설정하고, coordinate 를 중심으로 회전시킵니다. 지도에 사용된 플러그인이 방위각을 지원하는 경우, bearing 의 유효 범위는 0에서 360 사이입니다. 맵에 사용된 플러그인이 방위각을 지원하지 않거나, 맵이 기울어져 있어 coordinate 가 카메라 뒤쪽에 위치하거나, 맵이 준비되지 않은 경우( mapReady 참조), 이 메서드를 호출해도 아무런 효과가 없습니다.

Qt 5.10에 포함된 이 API는 기술 미리보기(Technology Preview) 버전입니다.

coordinate toCoordinate(QPointF position, bool clipToViewPort)

지도 항목을 기준으로 position 에 해당하는 좌표를 반환합니다.

clipToViewPort 가 ` true`이거나 지정되지 않은 경우, ` position `가 현재 뷰포트 내에 포함되지 않으면 유효하지 않은 좌표를 반환합니다.