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 タイプを使用して実行されます。

以下のコード例は、Map Viewer (QML)のサンプルに含まれる `map ` コンポーネントの一部です。これらのスニペットは、`GeocodeModel ` コンポーネントの宣言を示しています。

このスニペットでは、GeocodeModel にプラグインと2つのシグナルハンドラが含まれていることがわかります。1つはステータスの変更用 onStatusChanged 、もう1つは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と呼ばれる）を含む、目的地までの経路を定義するrouteSegmentのリストを返す必要があります。

クエリに追加して条件を絞り込むことができるオプションは多数あります。「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 のListModelには、コードを使用して値を格納できます。このコードでは、区間をループ処理し、区間の長さ、案内文、および次の案内地点までの距離を抽出します。抽出されたデータは、取得される際に表示用にフォーマットされます。

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	Typeは地図を表示します
MapCircle	Map上に地理的円を表示するタイプ
MapCopyrightNotice	アイテムは、Map要素の現在有効な著作権表示を表示します
MapItemGroup	この型は、マップアイテムのコンテナです
MapItemView	モデルからマップにデータを設定するために使用される
MapPolygon	タイプは、地図上にポリゴンを表示します
MapPolyline	Typeは、マップ上にポリラインを表示します
MapQuickItem	このタイプは、マップ上に任意のQt Quick オブジェクトを表示します
MapRectangle	Typeは、Map上に矩形を表示します
MapRoute	このタイプは、地図上にルートを表示します
cameraCapabilities	このタイプは、特定のマップタイプにおけるカメラの機能に関する情報を保持します
mapType	この型は、地図タイプに関する情報を保持します

ジオコーディング

GeocodeModel

Typeは、地理情報に関連する検索操作をサポートします

ルート検索

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

例

上記のコードスニペットは、Map Viewer (QML)のサンプルから抜粋したものです。

Places バックエンド Maps 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.