QML 地图

概述

Map 类型支持显示地图并在地图中放置对象。可以定义各种兴趣点并将其添加到地图中进行显示。此外，Map 还具备控制地图显示方式的功能。通过Map项，您可以将地图居中、缩放、双指缩放，并使该项支持轻扫操作。

要添加到地图上的地点是MapItems。该项的位置由geoCoordinate 定义，其中包含纬度、经度和海拔。该项在添加到Map 后会自动显示。

地图上的位置

所有位置相关 API 均属于QtPositioning 模块。位置信息的基本单元是geoCoordinate 。geoCoordinate 封装了该位置的纬度、经度和海拔数据。海拔单位为米。它还提供了一个方法，用于确定到另一个位置的距离：geoCoordinate 。geoCoordinate 类型也可以包含在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 组件的声明方式。

在代码片段中，我们可以看到 `GeocodeModel ` 包含插件和两个信号处理程序。其中一个用于处理状态变化 onStatusChanged ，另一个用于更新 Map 对象的居中位置 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 应返回一个routeSegment列表，该列表定义了通往目的地的路线，并包含路线各路段连接处（称为routeManeuver）的导航建议。

您可以向查询中添加多种选项以缩小筛选条件。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
    }
}

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

缩放功能还可以通过其他对象（如滑块）进行控制，只需将其与 MapzoomLevel 进行绑定即可。

QML 类型

地图

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

地理编码

GeocodeModel

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

路线规划

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

示例

上述代码片段摘自“地图查看器（QML）”示例。

地点后端地图 QML API

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