地图QML类型

Map 类型显示地图。 更多信息...

导入声明导入 QtLocation 6.7
自QtLocation 5.0

属性

信号

方法

详细说明

Map 类型用于显示地图或地球图像，同时也可显示与地图表面相关联的交互对象。

有各种不同的方式以二维形式可视化地球表面，但所有这些方式都涉及某种类型的投影：3D 坐标（纬度、经度和高度）与屏幕上的 2D 坐标（像素中的 X 和 Y）之间的数学关系。

不同的地图数据来源可能使用不同的投影方式，从 Map 类型角度看，我们将其视为一个可替换的单元：地图插件。一个地图插件包含数据源，以及所有在其屏幕上显示数据的详细信息。

当前使用的地图插件包含在 Map 项的 plugin 属性中。为了在 Map 项中显示任何图像，您需要设置此属性。有关如何获取适当插件的描述，请参阅 Plugin 类型。

在 Map 项中显示的地理区域称为视图，它由属性 center 和 zoomLevel 定义。属性 center 包含一个指定视图中心的 coordinate，而 zoomLevel 控制地图的缩放。请参阅这些属性的详细信息。

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

地图对象

在Qt Quick中，可以在Map对象的主体内部声明与地图相关的对象，这些对象将自动出现在地图上。要程序化添加对象，首先确保它以地图作为父对象创建（例如在Component::createObject方法中的参数）。然后调用Map对象的addMapItem方法，如果此对象的类型是MapCircle、MapRectangle、MapPolyline、MapPolygon、MapRoute或MapQuickItem中的一种。同时，也存在一个对应的removeMapItem方法来删除以上类型的地图对象。

通常情况下，移动地图对象、调整其大小或改变其形状不需要与Map进行特殊交互——只需在地图对象中更改这些属性，就可以自动更新显示。

性能

地图使用OpenGL（ES）和Qt场景图堆栈进行渲染，因此，在有硬件加速的GL环境中，性能相当不错。

对于“在线”地图，网络的带宽和延迟可能会成为衡量性能的重要因素。为此进行了大量缓存以缓解此问题，但这种缓解并不总是完美的。

一般来说，大型的复杂地图对象，如具有大量顶点的多边形和多段线，可能会对UI性能产生不利影响。

示例用法

以下代码片段展示了简单的Map和必要的Plugin类型。地图以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

访问当前活动的地图类型。

可以将此属性设置为更改活动的地图类型。有关可能的值，请参阅supportedMapTypes属性。

另见 mapType。


bearing : real [自从QtLocation 5.9起]

此属性包含地图的方位角。默认值为0。如果用于地图的Plugin支持方位角，则此值的有效范围是0到360。如果用于地图的Plugin不支持方位角，则更改此属性将不会产生任何影响。

该属性自QtLocation 5.9版本引入。


center : coordinate

此属性包含占映射视口中心的坐标。无效的中心坐标将被忽略。

默认值为一个任意有效的坐标。


color : color

此属性包含地图元素的背景颜色。


copyrightsVisible : bool

此属性包含版权公告的可见性。该公告通常显示在左下角。默认情况下，此属性设置为true。

注意: 许多地图服务提供商要求公告可见作为服务条款的一部分。在关闭该公告之前，请咨询相关提供者的文档。


error : enumeration [只读]

此只读属性包含最后发生的地图服务提供商错误。

  • Map.NoError - 没有发生错误。
  • Map.NotSupportedError - 地图插件属性未设置或没有与插件关联的地图管理器。
  • Map.UnknownParameterError - 插件未能识别它所接收的一个参数。
  • Map.MissingRequiredParameterError - 插件未能找到它所期望的一个参数。
  • Map.ConnectionError - 插件无法连接到其后端服务或数据库。

另请参阅 QGeoServiceProvider::Error.


errorString : string [只读]

此只读属性保存了最新测绘提供者错误的文本表示。如果没有发生错误，则返回空字符串。

如果发生错误但没有关联的文本表示，也可能返回空字符串。

另请参阅 QGeoServiceProvider::errorString().


fieldOfView : real [自 QtLocation 5.9 开始]

此属性保存用于查看地图的摄像头的视场，以度为单位。如果未设置地图的插件属性，或者插件不支持地图，则值是45度。

请注意，更改此值会隐式更改摄像机与地图之间的距离，因此，在仰角为0度时，使用此属性任何值的结果图像都是相同的。

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

该属性自QtLocation 5.9版本引入。

另请参阅 minimumFieldOfView 和 maximumFieldOfView.


mapItems : list<MapItem> [只读]

返回所有地图项的列表，无特定顺序。这些项包括作为类型声明的一部分静态声明的项，以及动态项（addMapItem，MapItemView）。

另请参阅 addMapItem，removeMapItem 和 clearMapItems.


mapReady : bool [只读]

此属性表示地图是否已成功初始化并可使用。在地图准备就绪之前，某些方法，如 fromCoordinate 和 toCoordinate，将无法正常工作。由于 Map 的架构，建议使用为此属性发出的信号代替 Component.onCompleted，以确保一切按预期运行。


maximumFieldOfView : real [自 QtLocation 5.9 开始]

此属性保存地图的最大有效视场，以度为单位。

plugin 使用的最小倾斜视场是此属性的.upper 界限。如果未设置 plugin 属性，或者插件不支持地图，则此属性为 179。

该属性自QtLocation 5.9版本引入。

另请参阅 fieldOfView 和 minimumFieldOfView.


最大倾斜角度 : 实数 [自 QtLocation 5.9 开始]

此属性保存地图的最大有效倾斜角度（以度为单位）。

由所使用的 插件 定义的倾斜角度是此属性的界限。如果未设置 插件 属性或插件不支持地图，则该属性为 89.5。

自 QtLocation 5.12 开始，插件可以进一步根据当前的缩放级别限制此值。

该属性自QtLocation 5.9版本引入。

另请参阅 倾斜 和 最小倾斜角度。


最大缩放级别 : 实数

此属性保存地图的最大有效缩放级别。

最大缩放级别由所使用的 插件 定义。如果未设置 插件 属性或插件不支持地图，则该属性为 30。


最小视场角度 : 实数 [自 QtLocation 5.9 开始]

此属性保存地图的有效最小视场角度（以度为单位）。

由所使用的 插件 定义的视场角度是此属性的界限。如果未设置 插件 属性或插件不支持地图，则该属性为 1。

该属性自QtLocation 5.9版本引入。

另请参阅 视场 和 最大视场角度。


最小倾斜角度 : 实数 [自 QtLocation 5.9 开始]

此属性保存地图的最小倾斜角度（以度为单位）。

由所使用的 插件 定义的倾斜角度是此属性的界限。如果未设置 插件 属性或插件不支持地图，则该属性为 0。

自 QtLocation 5.12 开始，插件可以进一步根据当前的缩放级别限制此值。

该属性自QtLocation 5.9版本引入。

另请参阅 倾斜 和 最大倾斜角度。


最小缩放级别 : 实数

此属性保存地图的有效最小缩放级别。

由所使用的 插件 定义的缩放级别是此属性的界限。但是，返回的值也取决于画布大小，并且可能高于用户指定的值或所使用的插件的定义的最小缩放级别，以防止地图尺寸小于视口。

如果未设置 插件 属性或插件不支持地图，则该属性为 0。


plugin : 插件

此属性保存提供了地图功能的插件。

这是一个一次性属性。一旦与地图关联了插件，任何尝试修改插件的操作都将被忽略。


支持的地图类型 : 列表<地图类型> [只读]

此只读属性保存了此地图支持的地图类型集。

另请参阅 activeMapType.


tilt : real [自 QtLocation 5.9 开始]

此属性用于存储地图的倾斜角度，单位为度。默认值为0。该值的有效范围为[ minimumTilt, maximumTilt ]。如果用于地图的插件不支持倾斜，更改此属性将无效果。

该属性自QtLocation 5.9版本引入。

另请参阅 minimumTilt 和 maximumTilt.


visibleArea : rect

此属性用于存储地图 QML 元素内部的可见区域。它是一个相对地图元素的坐标矩形。其大小将被限制在地图元素的大小内。null visibleArea 表示地图整体可见。


visibleRegion : geoshape

此属性用于存储占用地图视口的区域。相机位于形状的中心，以及允许整个形状在屏幕上可见的最大的整数值缩放级别。这意味着读取此属性后不久，返回的区域等于或大于设置的面积。

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

注意： 自 Qt 5.14 开始，此属性提供更改通知。


zoomLevel : real

此属性用于存储地图的缩放级别。

缩放级别的更高值提供更多细节。缩放级别总是非负数。默认值为 8.0。根据使用的插件，可能接受或限制在 [minimumZoomLevel, maximumZoomLevel] 范围之外，该范围代表可用瓦片的范围。


信号文档

copyrightLinkActivated(string link)

当用户点击版权通知中的链接时，发出此信号。应用应在浏览器中打开链接或向用户显示其内容。

注意： 相应的事件处理函数是 onCopyrightLinkActivated。


方法文档

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

注意： 不能使用此方法添加 MapItemViews。

另请参阅 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），则调用此方法不会有任何效果。

此 API 随 Qt 5.10 一起发布是一个技术预览。

另请参阅 center。


void clearData()

清除当前选中插件收集的地图数据。

注意: 此方法将删除缓存文件。

另请参阅 plugin。


void clearMapItems()

从地图中移除所有项目和项目组。

另请参阅 mapItems、addMapItem、removeMapItem、addMapItemGroup 和 removeMapItemGroup。


void fitViewportToGeoShape(geoShape, margins)

将视口调整到特定的地理形状 geoShape。边距以屏幕像素为单位。

注意: 如果插件使用的投影不是 WebMercator，并且插件没有适配形状的能力，则此方法不会做任何事情。

另请参阅 visibleRegion。


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

如果没有提供参数，则将当前视图调整到所有地图项的边界。相机置于地图项的中心，并在允许所有地图项在屏幕上可见的最大整数缩放级别。

注意: 自 Qt 5.15 以来，此方法获得了可选的 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。


coordinate toCoordinate(QPointF position, bool clipToViewPort)

将地图的航向设置为bearing，围绕coordinate旋转。如果地图所使用的插件支持航向，bearing的有效范围是0到360。如果地图所使用的插件不支持航向，或者地图是倾斜的，且coordinate位于相机后面，或者地图未准备好（参见mapReady），则调用此方法将不会有任何效果。

此 API 随 Qt 5.10 一起发布是一个技术预览。


coordinate toCoordinate(QPointF position, bool clipToViewPort)

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

如果clipToViewPort为true，或者未提供，则如果position不在当前视图中，则返回一个无效的坐标。


© 2024 Qt公司有限公司。此处包含的文档贡献是各自所有者的版权。本提供的文档是在自由软件基金会根据其发布的条款下许可的GNU自由文档许可证版本1.3。Qt及其标志是芬兰以及/或其他国家/地区的Qt公司有限公司的商标。所有其他商标均为其所有者所有。