Map QML Type

地图类型显示地图。更多

• 所有成员（包括继承成员）的列表
• Map 是QML 地图插件的一部分。

属性

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

详细说明

地图类型用于显示地球的地图或图像，还可以显示与地图表面相关的交互式对象。

以二维方式显示地球表面有多种不同的方法，但都涉及某种投影：屏幕上的三维坐标（纬度、经度和高度）与二维坐标（X 和 Y，以像素为单位）之间的数学关系。

不同的地图数据源可以使用不同的投影，从地图类型的角度来看，我们将这些数据源视为一个可替换的单元：地图插件。地图插件由数据源以及在屏幕上显示数据所需的所有其他细节组成。

当前使用的地图插件包含在地图项的plugin 属性中。要在地图项中显示任何图像，都需要设置该属性。请参阅Plugin 类型，了解如何检索合适的插件。

地图项中显示的地理区域称为视口，由属性center 和zoomLevel 定义。center 属性包含一个指定视口中心的坐标，而zoomLevel 则控制地图的比例。有关这些属性值的更多详情，请参阅每个属性。

显示地图时，可见的每个可能地理坐标都将映射到屏幕上的某个像素 X 和 Y 坐标。为了在这两者之间进行转换，地图提供了toCoordinate 和fromCoordinate 函数，这两个函数具有通用性。

地图对象

与地图相关的对象可以在Qt Quick 地图对象的主体中声明，并自动出现在地图上。要以编程方式添加对象，首先要确保该对象是以 Map 作为父对象创建的（例如，在Component::createObject 的参数中）。然后，如果该对象的类型是MapCircle,MapRectangle,MapPolyline,MapPolygon,MapRoute 或MapQuickItem 之一，则调用地图上的addMapItem 方法。相应的removeMapItem 方法也可以做相反的操作，从地图上删除任何上述类型的地图对象。

移动地图对象、调整它们的大小或改变它们的形状通常不涉及与地图本身的任何特殊交互--在地图对象中改变这些属性将自动更新显示。

性能

地图是使用 OpenGL (ES) 和 Qt 场景图栈渲染的，因此在有 GL 加速硬件的情况下性能相当不错。

对于 "在线 "地图，网络带宽和延迟可能是影响用户性能感知的主要因素。为了缓解这一问题，我们进行了广泛的缓存，但这种缓存并不总是完美的。

一般来说，大型复杂的地图项目（如具有大量顶点的多边形和折线）会对用户界面性能产生不利影响。

使用示例

下面的代码段显示了一个简单的地图和使用该地图所需的插件类型。地图以挪威奥斯陆为中心，缩放级别为 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]

此只读属性保存上次发生的映射服务提供商错误。

• 地图。NoError - 未发生错误。
• Map.NotSupportedError -未设置地图插件属性，或没有与插件关联的映射管理器。
• Map.UnknownParameterError -插件无法识别给定的参数。
• Map.MissingRequiredParameterError - 插件未找到预期参数之一。
• Map.ConnectionError - 插件无法连接其后台服务或数据库。

另请参见 QGeoServiceProvider::Error 。

errorString : string [read-only]

此只读属性用于保存最新映射提供程序错误的文字表述。如果没有发生错误，则返回空字符串。

如果发生的错误没有相关的文本表述，也会返回空字符串。

另请参阅 QGeoServiceProvider::errorString()。

fieldOfView : real [since QtLocation 5.9]

该属性表示用于观察地图的摄像机的视场角，单位为度。如果未设置地图的插件属性，或者插件不支持映射，则该值为 45 度。

请注意，改变该值也会隐式地改变摄像机与地图之间的距离，因此在倾斜角度为 0 度时，该属性的任何值所产生的图像都是相同的。

有关此参数的更多信息，请查阅维基百科上有关视场角和视角的文章。

此属性在 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 元素。它的大小将与 Map 元素的大小保持一致。visibleArea 为空意味着整个地图都是可见的。

visibleRegion : geoShape

该属性用于保存占据地图视口的区域。摄像机被放置在形状的中心，并尽可能以最大的整体缩放级别在屏幕上看到整个形状。这意味着，在设置该属性后不久读取返回的区域等于或大于设置的区域。

设置该属性会隐式更改地图的center 和zoomLevel 。之前为这些属性设置的任何值都将被覆盖。

zoomLevel : real

该属性表示地图的缩放级别。

缩放级别值越大，提供的细节越多。缩放级别总是非负的。默认值为 8.0。根据所使用插件的不同，[minimumZoomLevel,maximumZoomLevel]范围以外的值可能会被接受或被箝制，该范围代表了可使用磁贴的范围。

信号文档

copyrightLinkActivated(string link)

当用户点击版权声明中的link 时会发出该信号。应用程序应在浏览器中打开该链接或向用户显示其内容。

方法文档

void addMapItem(MapItem item)

将给定的item 添加到地图上（例如MapQuickItem,MapCircle ）。如果该对象已在地图上，则不会再次添加。

举例来说，如果您有一个代表您当前位置的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 中包含的地图项添加到地图中（例如MapQuickItem,MapCircle ）。

另请参阅 MapItemGroup 和removeMapItemGroup 。

void addMapItemView(MapItemView itemView)

在地图上添加itemView 。

另请参阅 MapItemView 和removeMapItemView 。

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

将coordinate 对齐到point 。该方法有效扩展了center qml 属性提供的功能，允许将坐标对齐到地图元素中心以外的点。这在场景中心（如光标）并不完全位于地图中心的应用中非常有用。

如果地图是倾斜的，而coordinate 恰好位于摄像机后面，或者地图尚未准备就绪（参见mapReady ），调用此方法将没有任何效果。

随 Qt 5.10 发布的此 API 为技术预览版。

另请参阅 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 及其实例化的项目。

另请参阅 MapItemView 和addMapItemView 。

void setBearing(real bearing, coordinate coordinate)

将地图的方位设置为bearing ，并围绕coordinate 旋转。如果地图使用的插件支持方位，bearing 的有效范围为 0 至 360。如果地图使用的插件不支持方位，或者地图是倾斜的，而coordinate 恰好位于摄像头后面，或者地图尚未准备就绪（请参阅mapReady ），调用此方法将没有任何效果。

随 Qt 5.10 发布的此 API 为技术预览版。

coordinate toCoordinate(QPointF position, bool clipToViewPort)

返回position 相对于地图项的坐标。

如果clipToViewPort 是true ，或者没有提供，那么如果position 不在当前视口内，则返回无效坐标。