QML Maps

QML Maps

Overview

概述

The Map type allows the display of a map and placing objects within the map. Various points of interest can be defined and added to the map for display. Also the Map has features to control how the map is displayed. With the Map item you can center the map, zoom, pinch and make the item flickable.

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

The places to be added to the map are MapItems. The item's position is defined by a coordinate which includes latitude, longitude and altitude. The item is then displayed automatically after it is added to the Map.

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

Position on map

地图上的位置

All position APIs are part of the QtPositioning module. The basic piece of position information is the coordinate. A coordinate encapsulates data for the latitude, longitude and altitude of the location. Altitude is in meters. It also has a method to determine distance to another coordinate. The coordinate type may also be held within a Location element, this will also have information on a bounding box size to determine sufficient proximity to the location and a location address.

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

Here is an example of a client that uses a position source to center a map on the current position:

​以下是一个使用位置源将地图居中放置在当前位置的客户端示例：

import QtPositioning
import QtLocation
...

Rectangle {

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

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

Geocoding

地理编码

Geocoding is the derivation of geographical coordinates (latitude and longitude) from other geographical references to the locations. For example, this can be a street address. Reverse geocoding is also possible with a street address being used to determine a geographical coordinate. Geocoding is performed by using the GeocodeModel type.

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

The following code examples are a small part of the map component in the Map Viewer (QML) example. The snippets demonstrate the declaration of the GeocodeModel component.

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

In the snippet we see that the [QML]{GeocodeModel} contains the plugin and two signal handlers. One for changes in status onStatusChanged and the other to update the centering of the Map object onLocationsChanged.

​在代码片段中，我们看到[QML]{GeocodeModel}包含插件和两个信号处理程序。一个用于更改StatusChanged的状态，另一个用于更新LocationsChanged上Map对象的中心。

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
}

The geocoding features are called from a higher level piece of code. In this snippet we see an Address object filled with the desired parameters.

​地理编码功能是从更高级别的代码中调用的。在这个代码片段中，我们看到一个填充了所需参数的Address对象。

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

The Address is later used in a query for the GeocodeModel to process and determine the geographical coordinates.

​地址稍后用于GeocodeModel的查询，以处理和确定地理坐标。

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

Navigation

导航

A very important function of the Map type is navigation from one place to a destination with possible waypoints along the route. The route will be divided up into a series of segments. At the end of each segment is a vertex called a maneuver. The segments contain information about the time and distance to the end of the segment. The maneuvers contain information about what to do next, how to get onto the next segment, if there is one. So a maneuver contains navigational information, for example "turn right now".

​地图类型的一个非常重要的功能是从一个地方导航到目的地，沿途可能有航路点。这条路线将分为一系列路段。在每个分段的末尾是一个称为机动的顶点。这些片段包含有关片段结束的时间和距离的信息。这些动作包含了下一步要做什么、如何进入下一段（如果有的话）的信息。因此，机动包含导航信息，例如“现在右转”。

To find a suitable route we will need to use a RouteQuery to define the selection criteria and adding any required waypoints. The RouteModel should return a list of routeSegments that defines the route to the destination complete with navigation advice at the joins between segments, called routeManeuvers

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

There are many options that you can add to the query to narrow the criteria. The RouteQuery properties can include

​可以向查询中添加许多选项来缩小条件范围。RouteQuery属性可以包括

numberAlternativeRoutes	The number of alternative routes 备选路线的数量
travelModes	Travel modes 旅行方式
routeOptimizations	Required route optimizations 所需的路线优化
segmentDetail	Level of detail in segments 细分片断的详细程度
maneuverDetail	Level of detail in maneuvers between segments 分段间机动的详细程度
waypoints	A list of waypoints 航路点列表
excludedAreas	A list of excluded areas that the route must not cross 路线不得穿过的排除区域列表
featureTypes	Relevant map features, for example highway, ferry 相关地图特征，例如高速公路、渡轮

In the following example a default RouteQuery is declared within RouteModel.

​在以下示例中，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()
        }
    }
}

The user enters some information such as the starting point of the route, some waypoints and the destination. All of these locations are waypoints so the locations from start to finish will be entered as a sequence of waypoints. Then other query properties can be set that may be specific to this trip.

用户输入一些信息，如路线的起点、一些航路点和目的地。所有这些位置都是航路点，因此从开始到结束的位置将作为一系列航路点输入。然后，可以设置可能特定于此行程的其他查询属性。

// 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();

The routeInfoModel ListModel is used to grab the results of the query and construct a suitable list for display.

​routeInfoModel ListModel用于获取查询结果并构建合适的列表进行显示。

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

The ListModel routeInfoModel can be filled with values using a code, that loops through the segments extracting the segment length, instruction text and distance to the next instruction. The extracted data is formatted for display as it is retrieved.

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

For more information on the example see the Map Viewer (QML) example.

​有关该示例的更多信息，请参阅地图查看器（QML）示例。

Zoom, Pinch and Flickable

缩放、收缩和拖动

The Map item also supports user interface interactions with the map using tactile and mouse gestures. That is features such as swiping to pan, pinching to zoom.

​Map项还支持使用触觉和鼠标手势与地图进行用户界面交互。这些功能包括滑动平移、捏合缩放。

Enabling and configuring pinch and flickable is easy within the MapView type.

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

Zoom can also be controlled by other objects like sliders, with binding to the Map zoomLevel.

​缩放也可以通过滑块等其他对象进行控制，并绑定到Map zoomLevel。

QML Types

Maps

GeoJsonData	A model to represent, load and save GeoJSON documents 用于表示、加载和保存GeoJSON文档的模型
Map	Type displays a map 类型显示地图
MapCircle	Type displays a geographic circle on a Map 类型在地图上显示地理圆圈
MapCopyrightNotice	Item displays the current valid copyright notice for a Map element 项目显示Map元素的当前有效版权声明
MapItemGroup	Type is a container for map items 类型是地图项的容器
MapItemView	Used to populate Map from a model 用于从模型填充Map
MapPolygon	Type displays a polygon on a Map 类型在地图上显示多边形
MapPolyline	Type displays a polyline on a map 类型在地图上显示多段线
MapQuickItem	Type displays an arbitrary Qt Quick object on a Map Type在Map上显示任意Qt Quick对象
MapRectangle	Type displays a rectangle on a Map 类型在地图上显示矩形
MapRoute	Type displays a Route on a Map 类型在地图上显示路线
cameraCapabilities	Type holds information about the camera capabilities for a specific map type Type包含特定地图类型的相机功能信息
mapType	Type holds information about a map type 类型包含有关地图类型的信息

Geocoding

GeocodeModel

Type provides support for searching operations related to geographic information 类型为与地理信息相关的搜索操作提供支持

Routing

RouteModel	Type provides access to routes 类型提供对路线的访问
RouteQuery	Type is used to provide query parameters to a RouteModel 类型用于向RouteModel提供查询参数
route	Type represents one geographical route 类型代表一条地理路线
routeManeuver	Type represents the information relevant to the point at which two routeSegments meet 类型表示与两条路线分段相交点相关的信息
routeSegment	Type represents a segment of a Route 类型表示路线的一段

Example

示例

The above snippets are taken from the Map Viewer (QML) example.

​以上代码段取自地图查看器（QML）示例。

Places BackendMaps QML API

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