MapQuickItem QML Type

MapQuickItem 类型可在地图上显示任意Qt Quick 对象。更多

Import Statement: import QtLocation 6.9
Since: QtLocation 5.5

属性

详细说明

MapQuickItem 类型用于在指定位置和大小的地图上放置任意Qt Quick 对象。与浮动在地图上方的项目相比,MapQuickItem 将跟随地图的平移(也可选择缩放),就像它在地图表面一样。

sourceItem 属性包含要绘制的Qt Quick 项目,可以是任何可见类型。

定位和大小

MapQuickItem 在地图上的定位由两个属性控制:coordinateanchorPoint 。如果只设置了coordinate ,则指定了项目放置的经度/纬度坐标。当显示在屏幕上时,所设置的坐标将与所包含项目的左上角对齐。

anchorPoint 属性提供了一种方法,通过设置项目偏移的像素数,使坐标与项目的其他部分对齐,而不仅仅是与左上角对齐。一个简单的思考方法是,注意anchorPoint 在项目本身上给出的点,就是显示时与给定的coordinate 对齐的点。

除了锚定到地图上之外,MapQuickItem 还可以选择跟随地图的比例尺,并在放大或缩小地图时改变大小。这种行为由zoomLevel 属性控制。如果未设置zoomLevel ,默认行为是在 "屏幕 "上而不是在 "地图 "上绘制项目,因此无论地图的缩放级别如何,其大小都保持不变。

性能

MapQuickItem 的性能通常与单独包含Qt Quick 项目的性能相同。增加的开销相当于原始项目的平移和(可能)缩放,以及从经度和纬度到屏幕位置的转换。

局限性

注: 由于一个实现细节,放置在 MapQuickItem 内的项目将有一个并非 MapQuickItem 的parent 项目。在引用 MapQuickItem 时,请使用其id ,并避免在sourceItem 中使用anchor

使用示例

以下代码段显示了一个包含图像对象的 MapQuickItem,用于在地图上显示一个标记。该策略用于在 MapViewer 示例中显示地图标记。

MapQuickItem {
    id: marker
    anchorPoint.x: image.width/4
    anchorPoint.y: image.height

    HoverHandler {
        id: hoverHandler
    }
    TapHandler {
        id: tapHandler
        acceptedButtons: Qt.RightButton
        gesturePolicy: TapHandler.WithinBounds
        onTapped: {
            mapview.currentMarker = -1
            for (var i = 0; i< mapview.markers.length; i++){
                if (marker == mapview.markers[i]){
                    mapview.currentMarker = i
                    break
                }
            }
            mapview.showMarkerMenu(marker.coordinate)
        }
    }
    DragHandler {
        id: dragHandler
        grabPermissions: PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType
    }

    sourceItem: Image {
        id: image
    }
}

属性文档

anchorPoint : point

该属性决定sourceItem 上的哪个点将与地图上的坐标对齐。


autoFadeIn : bool

该属性决定了从极低缩放级别开始缩放地图时,项目是否会自动淡入。默认为true 。将此属性设置为false 会使地图项始终具有QtQuick::Item::opacity 属性指定的不透明度,默认为 1.0。


coordinate : coordinate

该属性保存MapQuickItem 的锚点坐标。在地图上绘制时,由anchorPoint 指定的sourceItem 上的点会与该坐标保持对齐。

在下图中,有 3 个 MapQuickItems,除了anchorPoint 属性的值不同外,其他都是相同的。每个项目的anchorPoint 值都写在项目的顶部。


sourceItem : object

该属性包含将在地图上绘制的源项目。


zoomLevel : real

该属性控制MapQuickItem 内容的缩放行为。特别是,通过设置该属性,可以在绘制在屏幕上(以屏幕像素为单位)的对象和绘制在地图表面(随地图缩放级别改变大小)的对象之间进行选择。

该属性的默认值为 0.0,相当于在屏幕表面绘制对象。如果设置为其他值,则对象将绘制在地图表面。该值(如果不为零)指定了缩放比例为 1:1(即对象像素和屏幕像素相同)时对象可见的 zoomLevel(缩放级别)。当缩放级别小于此值时,对象看起来较小,而当缩放级别大于此值时,对象看起来较大。与此形成鲜明对比的是,当此属性设置为零时,对象在所有缩放级别下在屏幕上都保持相同大小。


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