Back to Qt.io
Contact Us Blog Download Qt
本页内容

地图查看器（QML）

“地图查看器”示例演示了如何显示地图并与之交互、搜索地址以及查找驾车路线。

奥斯陆地图，上面标有“The Qt Company”的标记

这是一个大型示例，涵盖了Qt Location 中地图、定位和导航服务的许多基本用法。本页面分为多个部分，通过代码片段分别介绍了这些功能领域。

运行示例

您可以通过以下方式运行该示例：

该示例可与任何可用的地理服务插件配合使用。但某些插件可能需要额外的plugin parameters 才能正常运行。可通过在命令行中使用--plugin 参数传递Plugin parameters ，其格式如下：

--plugin.<parameter name> <parameter value>

有关各地理服务插件支持哪些参数的详细信息，请参阅各插件的文档。本示例使用的默认插件是Qt Location Open Street Map 插件，该插件无需任何参数。

概述

本示例中展示的 QML 类型：

显示地图

通过MapView 类型可在屏幕上绘制地图，如下所示。

MapView {
    id: view
    map.zoomLevel: (maximumZoomLevel - minimumZoomLevel)/2
    map.center {
        // The Qt Company in Oslo
        latitude: 59.9485
        longitude: 10.7686
    }
}

MapView 由map 组成，并在其基础上扩展了基本导航功能。在此示例中，我们为地图指定了一个初始中心点geoCoordinate ，并设置了其经纬度。此外，我们将初始缩放级别设为 50%（即最大值与最小值的中间值）。

查找地址（地理编码）

要在地图上定位某个地址或地点，需要使用一种称为地理编码（geocoding）的过程。要执行地理编码操作，我们首先需要调整 Map 对象，使其能够接收结果。

通过GeocodeModel 接收地理编码结果：

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

要显示GeocodeModel 的内容，我们使用MapItemView ：

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

MapItemView 使用名为delegate 的对象作为其创建项的模板。该模板可以包含任何所需的地图对象，但在本例中，我们展示了一个包含标记图像的MapQuickItem ：

Component {
    id: pointDelegate

    MapQuickItem {
        id: point
        parent: view.map
        coordinate: locationData.coordinate

        sourceItem: Image {
            id: pointMarker
            source: "../resources/marker_blue.png"
        }
    }
}

有了这三个对象，我们就具备了接收地理编码响应并在地图上显示它们的能力。最后一步是发送实际的地理编码请求。

要发送地理编码请求，首先需要创建一个 `Address ` 对象，并向其中填充所需的参数。

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

然后，我们将geocodeModel.query 设置为已填充的Address ，并调用GeocodeModel 上的update()方法。

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

路线与出行路线

与GeocodeModel 类似，Qt Location 也支持RouteModel 类型，这使得我们可以获取两个或多个点之间的路线信息（例如驾车路线），并将其与Map 结合使用。

同样，我们将RouteModel 作为地图的属性进行实例化：

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

要向用户显示模型的内容，我们需要一个视图。我们再次使用MapItemView ，将路线作为对象显示在地图上：

MapItemView {
    parent: view.map
    model: routeModel
    delegate: routeDelegate

为了作为视图需要创建的对象的模板，我们创建了一个委托组件：

Component {
    id: routeDelegate

    MapRoute {
        id: route
        route: routeData
        line.color: "#46a2da"
        line.width: 5
        smooth: true
        opacity: 0.8

现在模型、视图和委托组件都已完成，唯一缺失的组件就是某种用于控制模型以启动路线请求流程的控件。在最简单的情况下，我们可以利用两个现成的coordinates 来填写路线请求：

property variant fromCoordinate: QtPositioning.coordinate(59.9483, 10.7695)
property variant toCoordinate: QtPositioning.coordinate(59.9645, 10.671)

在下面的代码片段中，我们将演示如何设置请求对象并指示模型进行更新。同时，我们还会指示地图将视图中心定位在路线请求的起点坐标上。

// 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();
// center the map on the start coord
view.map.center = startCoordinate;

这便是将路线显示在地图上所需的所有步骤。不过，能够检索到书面路线指引及行程说明也会非常有用。 在示例中，这些内容显示在ListView 元素中。为了生成这些内容，我们使用标准的ListModel和ListView 组合。ListModel中的数据由routeModel的输出构建而成：

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

在RouteModel 中，如上所示，我们添加了一个onStatusChanged 处理程序，该处理程序会调用showRouteList() 方法来更新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)
        });
    }
}

示例项目 @ code.qt.io

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