QML 地图

地图概述

Map 类型允许显示地图并在地图中放置对象。可定义各种兴趣点并添加到地图中显示。此外，Map 还具有控制地图显示方式的功能。通过 "地图 "项目，您可以将地图居中、缩放、捏合并使该项目可闪烁。

要添加到地图上的位置是MapItems。项目的位置由coordinate 定义，其中包括纬度、经度和高度。项目添加到Map 后会自动显示。

地图上的位置

所有位置 API 都是QtPositioning 模块的一部分。位置信息的基本部分是coordinate 。坐标包含位置的纬度、经度和高度数据。高度以米为单位。它还有一个确定与另一个coordinate 之间距离的方法。coordinate 类型也可保存在Location 元素中，该元素还将包含有关边界框大小的信息，以确定与位置和位置地址是否足够接近。

下面是一个使用position source 将map 置于当前位置中心的客户端示例：

import QtPositioning
import QtLocation
...

Rectangle {

    Map {
        id: map
        // initialize map
        ...
    }

    PositionSource {
        onPositionChanged: {
            // center the map on the current position
            map.center = position.coordinate
        }
    }
}

地理编码

地理编码是指从位置的其他地理参照中推导出地理坐标（经度和纬度）。例如，可以是街道地址。反向地理编码也可以使用街道地址来确定地理坐标。地理编码通过使用GeocodeModel 类型来执行。

以下代码示例是地图查看器（QML）示例中map 组件的一小部分。这些代码段演示了GeocodeModel 组件的声明。

在代码段中，我们看到 [QML]{GeocodeModel} 包含插件和两个信号处理器。一个用于状态变化 onStatusChanged另一个用于更新地图对象的居中位置 onLocationsChanged.

GeocodeModel {
    id: geocodeModel
    plugin: view.map.plugin
    onStatusChanged: {
        if ((status == GeocodeModel.Ready) || (status == GeocodeModel.Error))
            view.geocodeFinished()
    }
    onLocationsChanged:
    {
        if (count === 1) {
            view.map.center.latitude = get(0).coordinate.latitude
            view.map.center.longitude = get(0).coordinate.longitude
        }
    }
}

MapItemView {
    parent: view.map
    model: geocodeModel
    delegate: pointDelegate
}

地理编码功能由更高级别的代码调用。在该代码段中，我们看到一个填入所需参数的Address 对象。

Address {
    id :fromAddress
    street: "Sandakerveien 116"
    city: "Oslo"
    country: "Norway"
    state : ""
    postalCode: "0484"
}

Address 随后将用于查询GeocodeModel ，以处理和确定地理coordinates 。

// send the geocode request
geocodeModel.query = fromAddress
geocodeModel.update()

Map 类型的一个非常重要的功能是从一个地方到目的地的导航，沿途可能会有航点。路线将被划分为一系列段落。每个航段的末端都有一个顶点，称为机动点。航段包含到航段终点的时间和距离信息。机动点包含下一步该做什么、如何进入下一个航段（如果有的话）的信息。因此，一个操作包含导航信息，例如 "马上右转"。

为了找到合适的路线，我们需要使用RouteQuery 来定义选择标准，并添加所需的航点。RouteModel 应返回一个routeSegments 列表，该列表定义了通往目的地的路线，并在各段之间的连接处提供导航建议，称为routeManeuvers。

您可以在查询中添加许多选项，以缩小选择范围。RouteQuery 属性可包括

numberAlternativeRoutes	备选路线的数量
travelModes	旅行模式
routeOptimizations	所需的路线优化
segmentDetail	路段的详细程度
maneuverDetail	航段间机动的详细程度
waypoints	航点列表
excludedAreas	路线不得穿越的排除区域列表
featureTypes	相关地图特征，例如高速公路、渡口

在下面的示例中，在RouteModel 中声明了默认的RouteQuery 。

RouteModel {
    id: routeModel
    plugin : view.map.plugin
    query:  RouteQuery {
        id: routeQuery
    }
    onStatusChanged: {
        if (status == RouteModel.Ready) {
            switch (count) {
            case 0:
                // technically not an error
                view.routeError()
                break
            case 1:
                view.showRouteList()
                break
            }
        } else if (status == RouteModel.Error) {
            view.routeError()
        }
    }
}

用户输入一些信息，如路线起点、一些航点和目的地。所有这些位置都是航点，因此从起点到终点的位置将以航点序列的形式输入。然后还可以设置其他查询属性，这些属性可能与本次行程有关。

// clear away any old data in the query
routeQuery.clearWaypoints();
// add the start and end coords as waypoints on the route
routeQuery.addWaypoint(startCoordinate)
routeQuery.addWaypoint(endCoordinate)
routeQuery.travelModes = RouteQuery.CarTravel
routeQuery.routeOptimizations = RouteQuery.FastestRoute
routeModel.update();

routeInfoModel ListModel用于获取查询结果并构建一个合适的列表以供显示。

ListView {
    interactive: true
    model: ListModel { id: routeInfoModel }
    header: RouteListHeader {}
    delegate:  RouteListDelegate{
        routeIndex.text: index + 1
        routeInstruction.text: instruction
        routeDistance.text: distance
    }
}

ListModel routeInfoModel 可以使用代码来填充值，该代码会在各航段中循环，提取航段长度、指令文本和到下一指令的距离。提取的数据在检索时会被格式化以便显示。

routeInfoModel.clear()
if (routeModel.count > 0) {
    for (var i = 0; i < routeModel.get(0).segments.length; i++) {
        routeInfoModel.append({
            "instruction": routeModel.get(0).segments[i].maneuver.instructionText,
             "distance": Helper.formatDistance(routeModel.get(0).segments[i].maneuver.distanceToNextInstruction)
        });
    }
}

有关示例的更多信息，请参阅地图查看器 (QML)示例。

缩放、捏合和可滑动

Map 项目还支持使用触觉和鼠标手势与地图进行用户界面交互。这就是轻扫平移、捏合缩放等功能。

在MapView 类型中，启用和配置 "捏合 "和 "轻移 "非常简单。

MapView {
    id: view
TapHandler {
    id: tapHandler
    property variant lastCoordinate
    acceptedButtons: Qt.LeftButton | Qt.RightButton

    onPressedChanged: (eventPoint, button) => {
        if (pressed) {
            lastCoordinate = view.map.toCoordinate(tapHandler.point.position)
        }
    }

    onSingleTapped: (eventPoint, button) => {
            if (button === Qt.RightButton) {
                showMainMenu(lastCoordinate)
            }
    }

    onDoubleTapped: (eventPoint, button) => {
        var preZoomPoint = view.map.toCoordinate(eventPoint.position);
        if (button === Qt.LeftButton) {
            view.map.zoomLevel = Math.floor(view.map.zoomLevel + 1)
        } else if (button === Qt.RightButton) {
            view.map.zoomLevel = Math.floor(view.map.zoomLevel - 1)
        }
        var postZoomPoint = view.map.toCoordinate(eventPoint.position);
        var dx = postZoomPoint.latitude - preZoomPoint.latitude;
        var dy = postZoomPoint.longitude - preZoomPoint.longitude;

        view.map.center = QtPositioning.coordinate(view.map.center.latitude - dx,
                                                   view.map.center.longitude - dy);
    }
}
}

缩放也可由其他对象（如滑块）控制，并与地图zoomLevel 绑定。

QML 类型

地图

GeoJsonData	表示、加载和保存 GeoJSON 文档的模型
Map	显示地图的类型
MapCircle	类型显示地图上的地理圆圈
MapCopyrightNotice	项目显示地图元素当前有效的版权声明
MapItemGroup	类型是地图项的容器
MapItemView	用于从模型中填充地图
MapPolygon	类型在地图上显示多边形
MapPolyline	在地图上显示折线的类型
MapQuickItem	在地图上显示任意Qt Quick 对象的类型
MapRectangle	在地图上显示矩形的类型
MapRoute	类型在地图上显示路线
cameraCapabilities	类型保存特定地图类型的相机功能信息
mapType	类型保存有关地图类型的信息

地理编码

GeocodeModel

该类型支持与地理信息相关的搜索操作

路线

RouteModel	该类型提供对路由的访问
RouteQuery	该类型用于向 RouteModel 提供查询参数
route	类型代表一条地理路线
routeManeuver	类型表示两条路线段交汇点的相关信息
routeSegment	类型代表一条路由的一个区段

示例

以上片段摘自地图查看器 (QML)示例。

地点后台地图 QML API

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