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)

详细说明

“地图”类型用于显示地图或地球图像，并能够显示与地图表面相关的交互式对象。

虽然存在多种将地球表面以二维形式可视化的方法，但它们都涉及某种投影：即三维坐标（纬度、经度和海拔）与屏幕上的二维坐标（以像素为单位的 X 和 Y）之间的数学关系。

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

当前使用的地图插件包含在“地图”项的plugin 属性中。要在“地图”项中显示任何图像，您需要设置此属性。有关如何检索合适的插件以供使用的说明，请参阅Plugin 类型。

地图项中显示的地理区域称为其视口，该视口由center 和zoomLevel 属性定义。center 属性包含一个geoCoordinate ，用于指定视口的中心，而zoomLevel 则控制地图的比例尺。有关这些属性的值的更多详细信息，请参阅各属性说明。

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

地图对象

与地图相关的对象可在Qt Quick 中的Map对象主体内声明，并将自动显示在地图上。若要通过编程方式添加对象，首先请确保该对象是在Map作为其父对象的情况下创建的（例如作为Component::createObject 的参数）。 然后，如果该对象的类型属于以下之一：MapCircle 、MapRectangle 、MapPolyline 、MapPolygon 、MapRoute 或MapQuickItem ，则调用 Map 的addMapItem 方法。此外，还存在相应的removeMapItem 方法，用于执行相反操作，即从 Map 中移除上述任何类型的地图对象。

移动地图对象、调整其大小或改变其形状通常无需与 Map 本身进行任何特殊交互——在地图对象中更改这些属性后，显示内容会自动更新。

性能

地图使用 OpenGL (ES) 和 Qt 场景图栈进行渲染，因此在具备 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.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 为 null，则表示整个 Map 均可见。

visibleRegion : geoShape

该属性存储占据地图视口范围的区域。相机位于该区域的中心，且缩放级别设置为能够将整个区域完整显示在屏幕上的最大整数级别。这意味着，在设置该属性后不久再次读取时，返回的区域面积将等于或大于设置的面积。

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

zoomLevel : real

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

缩放级别数值越大，显示的细节越丰富。缩放级别始终为非负数。默认值为 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 ），调用此方法将不会产生任何效果。

该 API 随 Qt 5.10 发布时属于技术预览版。

另请参阅 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 属于技术预览版。

coordinate toCoordinate(QPointF position, bool clipToViewPort)

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

如果 `clipToViewPort ` 为 `true`，或者未提供该参数，则当 `position ` 不在当前视口范围内时，将返回一个无效坐标。