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}にはプラグインと2つのシグナルハンドラが含まれています。一つはステータスの変更 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 routeManeuverは、目的地までのルートを定義するrouteSegments のリストを返す。

条件を絞り込むために、クエリーに追加できるオプションはたくさんあります。RouteQuery プロパティには以下が含まれます。

numberAlternativeRoutes	代替ルートの数
travelModes	旅行モード
routeOptimizations	必要なルート最適化
segmentDetail	セグメントの詳細度
maneuverDetail	セグメント間のマヌーバの詳細レベル
waypoints	ウェイポイントのリスト
excludedAreas	ルートが通過してはならない除外エリアのリスト
featureTypes	関連する地図の特徴（高速道路、フェリーなど

次の例では、デフォルトのRouteQuery が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()
        }
    }
}

ユーザーは、ルートの出発点、いくつかのウェイポイント、目的地などの情報を入力します。これらの場所はすべてウェイポイントなので、スタートからゴールまでの場所はウェイポイントのシーケンスとして入力されます。それから、この旅に特有の他のクエリプロパティを設定することができます。

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

この例の詳細については、Map Viewer (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	ItemはMap要素に対して現在有効な著作権表示を行う。
MapItemGroup	タイプはマップアイテムのコンテナである
MapItemView	モデルからMapに入力するために使用される
MapPolygon	型は地図上に多角形を表示する
MapPolyline	型は地図上に折れ線を表示する
MapQuickItem	型はマップ上に任意のQt Quick オブジェクトを表示する
MapRectangle	型は地図上に矩形を表示する
MapRoute	型はマップ上にルートを表示する
cameraCapabilities	タイプは、特定のマップタイプのカメラ機能に関する情報を保持する
mapType	タイプはマップタイプに関する情報を保持する

ジオコーディング

GeocodeModel

型は地理情報に関連する検索操作をサポートする

ルーティング

RouteModel	型はルートへのアクセスを提供する。
RouteQuery	型は RouteModel にクエリパラメータを提供するために使用される。
route	型は 1 つの地理的ルートを表す
routeManeuver	型は 2 つの RouteSegment が交差する地点に関連する情報を表す
routeSegment	型はルートのセグメントを表す

例

上記のスニペットはMap Viewer (QML) の例から抜粋したものです。

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