Map QML Type

「マップ」タイプでは、地図が表示されます。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧
• MapはQML Mapsプラグインの一部です。

プロパティ

• activeMapType : mapType
• bearing : real (since QtLocation 5.9)
• center : coordinate
• color : color
• copyrightsVisible : bool
• error : enumeration
• errorString : string
• fieldOfView : real (since QtLocation 5.9)
• mapItems : list<MapItem>
• mapReady : bool
• maximumFieldOfView : real (since QtLocation 5.9)
• maximumTilt : real (since QtLocation 5.9)
• maximumZoomLevel : real
• minimumFieldOfView : real (since QtLocation 5.9)
• minimumTilt : real (since QtLocation 5.9)
• minimumZoomLevel : real
• plugin : Plugin
• supportedMapTypes : list<mapType>
• tilt : real (since QtLocation 5.9)
• visibleArea : rect
• visibleRegion : geoShape
• zoomLevel : real

信号

• copyrightLinkActivated(string link)

方法

• void addMapItem(MapItem item)
• void addMapItemGroup(MapItemGroup itemGroup)
• void addMapItemView(MapItemView itemView)
• void alignCoordinateToPoint(coordinate coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void fitViewportToGeoShape(geoShape, margins)
• void fitViewportToMapItems(list<MapItems> items)
• void fitViewportToVisibleMapItems()
• point fromCoordinate(coordinate coordinate, bool clipToViewPort)
• void pan(int dx, int dy)
• void prefetchData()
• void removeMapItem(MapItem item)
• void removeMapItemGroup(MapItemGroup itemGroup)
• void removeMapItemView(MapItemView itemView)
• void setBearing(real bearing, coordinate coordinate)
• coordinate toCoordinate(QPointF position, bool clipToViewPort)

詳細説明

「Map」タイプは、地図や地球の画像を表示するために使用され、地図の表面に紐付けられたインタラクティブなオブジェクトも表示する機能を備えています。

地球の表面を 2 次元で可視化する方法にはさまざまなものがありますが、そのすべてに何らかの「投影法」、つまり 3 次元座標（緯度、経度、高度）と画面上の 2 次元座標（ピクセル単位の X 座標および Y 座標）との間の数学的な関係が関わっています。

地図データ源によって異なる投影法が使用される場合がありますが、Map タイプでは、これらを 1 つの交換可能な単位、つまり「Map プラグイン」として扱います。Map プラグインは、データソースと、そのデータを画面上に表示するために必要なその他のすべての詳細で構成されています。

現在使用中のMapプラグインは、Mapアイテムのplugin プロパティに格納されています。Mapアイテムに画像を表示するには、このプロパティを設定する必要があります。適切なプラグインを取得する方法については、Plugin 型を参照してください。

Mapアイテムに表示される地理的領域は「ビューポート」と呼ばれ、これはcenter およびzoomLevel プロパティによって定義されます。center プロパティには、ビューポートの中心を指定するgeoCoordinate が含まれており、zoomLevel は地図の縮尺を制御します。各プロパティの値に関する詳細については、それぞれのプロパティを参照してください。

地図が表示されると、表示範囲内のすべての地理座標は、画面上のピクセルのX座標およびY座標に対応付けられます。これら2つの座標間の変換を行うために、Mapクラスは汎用性の高いtoCoordinate およびfromCoordinate 関数を提供しています。

Map オブジェクト

マップ関連のオブジェクトは、Qt Quick 内のMapオブジェクトの本体内で宣言でき、自動的にマップ上に表示されます。プログラムでオブジェクトを追加するには、まずそのオブジェクトがMapを親として作成されていることを確認してください（例：Component::createObject の引数として指定する場合など）。 その後、そのオブジェクトの型がMapCircle 、MapRectangle 、MapPolyline 、MapPolygon 、MapRoute 、またはMapQuickItem のいずれかである場合、Mapに対してaddMapItem メソッドを呼び出します。逆の操作、つまり上記のタイプのマップオブジェクトをMapから削除するためのremoveMapItem メソッドも存在します。

Map オブジェクトの移動、サイズ変更、形状変更は、通常、Map 自体との特別なやり取りを必要としません。Map オブジェクトのこれらのプロパティを変更すると、表示が自動的に更新されます。

パフォーマンス

マップは OpenGL (ES) および Qt Scene Graph スタックを使用してレンダリングされるため、GL アクセラレーション対応のハードウェアが利用可能な環境では、非常に高いパフォーマンスを発揮します。

「オンライン」マップの場合、ネットワークの帯域幅や遅延が、ユーザーが感じるパフォーマンスに大きく影響する可能性があります。これを軽減するために広範なキャッシュが行われますが、その軽減策が常に完璧であるとは限りません。

一般的に、頂点数の多いポリゴンやポリラインなど、大規模で複雑なマップアイテムは、UI のパフォーマンスに悪影響を及ぼす可能性があります。

使用例

以下のスニペットは、単純な Map と、それを使用するために必要な Plugin タイプを示しています。マップはノルウェーのオスロを中心に、ズームレベル 14 に設定されています。

import QtQuick
import QtLocation
import QtPositioning

Window {
    ...
    Plugin {
        id: mapPlugin
        name: "osm"
    }

    Map {
        id: map
        anchors.fill: parent
        plugin: mapPlugin
        center: QtPositioning.coordinate(59.91, 10.75) // Oslo
        zoomLevel: 14
        property geoCoordinate startCentroid

        PinchHandler {
            id: pinch
            target: null
            onActiveChanged: if (active) {
                map.startCentroid = map.toCoordinate(pinch.centroid.position, false)
            }
            onScaleChanged: (delta) => {
                map.zoomLevel += Math.log2(delta)
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            onRotationChanged: (delta) => {
                map.bearing -= delta
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            grabPermissions: PointerHandler.TakeOverForbidden
        }
        WheelHandler {
            id: wheel
            // workaround for QTBUG-87646 / QTBUG-112394 / QTBUG-112432:
            // Magic Mouse pretends to be a trackpad but doesn't work with PinchHandler
            // and we don't yet distinguish mice and trackpads on Wayland either
            acceptedDevices: Qt.platform.pluginName === "cocoa" || Qt.platform.pluginName === "wayland"
                             ? PointerDevice.Mouse | PointerDevice.TouchPad
                             : PointerDevice.Mouse
            rotationScale: 1/120
            property: "zoomLevel"
        }
        DragHandler {
            id: drag
            target: null
            onTranslationChanged: (delta) => map.pan(-delta.x, -delta.y)
        }
        Shortcut {
            enabled: map.zoomLevel < map.maximumZoomLevel
            sequence: StandardKey.ZoomIn
            onActivated: map.zoomLevel = Math.round(map.zoomLevel + 1)
        }
        Shortcut {
            enabled: map.zoomLevel > map.minimumZoomLevel
            sequence: StandardKey.ZoomOut
            onActivated: map.zoomLevel = Math.round(map.zoomLevel - 1)
        }
    }
}

プロパティのドキュメント

activeMapType : mapType

現在アクティブなmap type へのアクセス。

このプロパティを設定することで、アクティブなmap type を変更できます。取り得る値については、supportedMapTypes プロパティを参照してください。

「mapType」も参照してください 。

bearing : real [since QtLocation 5.9]

このプロパティは、マップの方位を保持します。デフォルト値は 0 です。マップに使用されているプラグインが方位をサポートしている場合、この値の有効範囲は 0 から 360 までとなります。マップに使用されているプラグインが方位をサポートしていない場合、このプロパティを変更しても何の効果もありません。

このプロパティは、QtLocation 5.9で導入されました。

center : coordinate

このプロパティには、マッピングビューポートの中心となる座標が格納されます。無効な中心座標は無視されます。

デフォルト値は、任意の有効な座標です。

color : color

このプロパティは、マップ要素の背景色を指定します。

copyrightsVisible : bool

このプロパティは、著作権表示の表示設定を指定します。通常、この表示は画面の左下隅に表示されます。デフォルトでは、このプロパティはtrue に設定されています。

error : enumeration [read-only]

この読み取り専用プロパティには、最後に発生したマッピングサービスプロバイダーのエラーが格納されます。

• Map.NoError - エラーは発生していません。
• Map.xml-ph-0000@deepl.internal— エラーは発生していません。Map.NotSupportedError — マッププラグインのプロパティが設定されていないか、プラグインに関連付けられたマッピングマネージャーが存在しません。
• Map.xml-ph-0000@deepl.internal— エラーは発生していません。Map.NotSupportedError — プラグインが、渡されたパラメータのいずれかを認識できませんでした。
• Map.MissingRequiredParameterError - プラグインが、期待していたパラメータのいずれかを見つけられませんでした。
• Map.ConnectionError - プラグインがバックエンドサービスまたはデータベースに接続できませんでした。

QGeoServiceProvider::Errorも参照してください 。

errorString : string [read-only]

この読み取り専用プロパティは、最新のマッピングプロバイダのエラーのテキスト表示を保持します。エラーが発生していない場合は、空の文字列が返されます。

また、テキスト表現が関連付けられていないエラーが発生した場合も、空の文字列が返されることがあります。

QGeoServiceProvider::errorString()も参照してください 。

fieldOfView : real [since QtLocation 5.9]

このプロパティは、地図を表示するために使用されるカメラの視野角（度単位）を保持します。地図のプラグインプロパティが設定されていない場合、またはプラグインがマッピング機能をサポートしていない場合、値は 45 度になります。

この値を変更すると、カメラと地図間の距離も暗黙的に変更されることに注意してください。そのため、傾斜角が 0 度の場合、このプロパティにどのような値を設定しても、結果として得られる画像は同一になります。

このパラメータの詳細については、ウィキペディアの「視野角」および「視角」に関する記事を参照してください。

このプロパティは QtLocation 5.9 で導入されました。

minimumFieldOfView およびmaximumFieldOfViewも参照してください 。

mapItems : list<MapItem> [read-only]

マップ内のすべての項目のリストを、順不同で返します。これらの項目には、型宣言の一部として静的に宣言された項目に加え、動的に宣言された項目（addMapItem 、MapItemView ）も含まれます。

addMapItem 、removeMapItem 、およびclearMapItemsも参照してください 。

mapReady : bool [read-only]

このプロパティは、マップが正常に初期化され、使用可能な状態にあるかどうかを示します。fromCoordinate やtoCoordinate などの一部のメソッドは、マップが使用可能な状態になるまでは動作しません。Map のアーキテクチャ上、すべてが期待どおりに動作するようにするため、Component.onCompleted の代わりに、このプロパティから発せられるシグナルを使用することをお勧めします。

maximumFieldOfView : real [since QtLocation 5.9]

このプロパティには、マップの有効な最大視野角（度単位）が格納されます。

使用されるplugin による最小チルト視野角は、このプロパティの上限となります。plugin プロパティが設定されていない場合、またはプラグインがマッピングをサポートしていない場合、このプロパティは179 となります。

このプロパティは QtLocation 5.9 で導入されました。

fieldOfView およびminimumFieldOfViewも参照してください 。

maximumTilt : real [since QtLocation 5.9]

このプロパティは、マップの有効な最大傾斜角（度単位）を保持します。

使用されているplugin によって定義された最大チルトは、このプロパティの上限となります。plugin プロパティが設定されていない場合、またはプラグインがマッピングに対応していない場合、このプロパティの値は89.5 となります。

QtLocation 5.12 以降、プラグインは現在のズームレベルに応じて、この値をさらに制限することができます。

このプロパティは、QtLocation 5.9で導入されました。

「 tilt 」および「minimumTilt 」も参照してください 。

maximumZoomLevel : real

このプロパティは、マップの有効な最大ズームレベルを保持します。

最大ズームレベルは、使用されるplugin によって定義されます。plugin プロパティが設定されていない場合、またはプラグインがマッピングをサポートしていない場合、このプロパティは30 となります。

minimumFieldOfView : real [since QtLocation 5.9]

このプロパティは、マップの有効な最小視野角（度単位）を保持します。

使用されるplugin による最小チルト視野角は、このプロパティの下限値となります。plugin プロパティが設定されていない場合、またはプラグインがマッピングをサポートしていない場合、このプロパティは1 となります。

このプロパティは QtLocation 5.9 で導入されました。

fieldOfView およびmaximumFieldOfViewも参照してください 。

minimumTilt : real [since QtLocation 5.9]

このプロパティは、マップの有効な最小チルト角（度単位）を保持します。

使用されているplugin によって定義される最小チルトは、このプロパティの下限となります。plugin プロパティが設定されていない場合、またはプラグインがマッピングをサポートしていない場合、このプロパティの値は0 となります。

QtLocation 5.12 以降、プラグインは現在のズームレベルに応じて、この値をさらに制限することができます。

このプロパティは、QtLocation 5.9で導入されました。

「 tilt 」および「maximumTilt 」も参照してください 。

minimumZoomLevel : real

このプロパティは、マップの有効な最小ズームレベルを保持します。

使用されているplugin によって定義される最小ズームレベルは、このプロパティの下限となります。ただし、返される値はキャンバスのサイズにも依存しており、地図がどちらの軸においてもビューポートより小さくなるのを防ぐため、ユーザーが指定した値や、使用されているプラグインによって定義された最小ズームレベルよりも高くなる場合があります。

plugin プロパティが設定されていない場合、またはプラグインがマッピングをサポートしていない場合、このプロパティの値は `0` になります。

plugin : Plugin

このプロパティには、マッピング機能を提供するプラグインが格納されます。

これは書き込みが1回のみ可能なプロパティです。マップにプラグインが関連付けられると、そのプラグインに対する変更の試みはすべて無視されます。

supportedMapTypes : list<mapType> [read-only]

この読み取り専用プロパティは、このマップがサポートするmap types のセットを保持します。

「activeMapType」も参照してください 。

tilt : real [since QtLocation 5.9]

このプロパティは、マップのチルト角（度単位）を保持します。デフォルト値は 0 です。この値の有効範囲は [minimumTilt,maximumTilt ] です。マップに使用されているプラグインがチルトに対応していない場合、このプロパティを変更しても効果はありません。

このプロパティは QtLocation 5.9 で導入されました。

minimumTilt およびmaximumTiltも参照してください 。

visibleArea : rect

このプロパティは、Map QML 要素内の表示領域を保持します。これは、Map 要素を基準とした座標を持つ rect です。そのサイズは、Map 要素のサイズに合わせてクリップされます。visibleArea が null の場合、Map 全体が表示されます。

visibleRegion : geoShape

このプロパティは、マップのビューポートを占有する領域を保持します。カメラは、その形状の中心に配置され、画面上に形状全体が表示されるように可能な限り最大の整数倍のズームレベルに設定されます。したがって、このプロパティが設定された直後に読み返した場合、返される領域は設定された領域と同等か、それ以上になります。

このプロパティを設定すると、マップのcenter およびzoomLevel が暗黙的に変更されます。これらのプロパティに以前に設定されていた値はすべて上書きされます。

zoomLevel : real

このプロパティは、マップのズームレベルを保持します。

ズームレベルが大きいほど、より詳細な情報が表示されます。ズームレベルは常に非負の値です。デフォルト値は 8.0 です。使用しているプラグインによっては、タイルが利用可能な範囲である [minimumZoomLevel,maximumZoomLevel] 以外の値が受け入れられる場合もあれば、制限される場合もあります。

Signal ドキュメント

copyrightLinkActivated(string link)

このシグナルは、ユーザーが著作権表示内のlink をクリックしたときに発火します。アプリケーションは、そのリンクをブラウザで開くか、その内容をユーザーに表示する必要があります。

メソッドのドキュメント

void addMapItem(MapItem item)

指定されたitem をMapに追加します（例：MapQuickItem 、MapCircle ）。そのオブジェクトがすでにMapに含まれている場合は、再度追加されることはありません。

例として、現在の位置を表すMapCircle がある場合を考えてみましょう：

import QtQuick
import QtPositioning
import QtLocation

PositionSource {
    id: positionSource
}

Map {
    id: map
    property MapCircle circle

    Component.onCompleted: {
        circle = Qt.createQmlObject('import QtLocation; MapCircle {}', page)
        circle.center = positionSource.position.coordinate
        circle.radius = 5000.0
        circle.color = 'green'
        circle.border.width = 3
        map.addMapItem(circle)
    }
}

mapItems 、removeMapItem 、およびclearMapItemsも参照してください 。

void addMapItemGroup(MapItemGroup itemGroup)

指定されたitemGroup に含まれるマップ項目をMapに追加します（例：MapQuickItem 、MapCircle ）。

MapItemGroup およびremoveMapItemGroupも参照してください 。

void addMapItemView(MapItemView itemView)

itemView をマップに追加します。

「 MapItemView 」および「removeMapItemView 」も参照してください 。

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

coordinate をpoint に合わせます。このメソッドは、center という QML プロパティが提供する機能を事実上拡張するもので、座標を Map 要素の中心以外の位置に合わせることができます。これは、シーンの中心（カーソルなど）をマップの中心に正確に配置しないアプリケーションで役立ちます。

マップが傾いており、coordinate がカメラの後ろにある場合、あるいはマップの準備が整っていない場合（mapReady を参照）、このメソッドを呼び出しても何の効果もありません。

Qt 5.10でのこのAPIのリリースは、テクノロジープレビューです。

centerも参照してください 。

void clearData()

現在選択されているプラグインによって収集されたマップデータを消去します。

関連項目： plugin 。

void clearMapItems()

マップからすべてのアイテムおよびアイテムグループを削除します。

関連項目： mapItems 、addMapItem 、removeMapItem 、addMapItemGroup 、およびremoveMapItemGroup 。

void fitViewportToGeoShape(geoShape, margins)

ビューポートを特定の地理的形状geoShape に合わせます。margins は画面ピクセル単位で指定します。

visibleRegionも参照してください 。

void fitViewportToMapItems(list<MapItems> items = {})

引数が指定されていない場合、現在のビューポートをすべてのマップアイテムの境界に合わせて調整します。カメラはマップアイテムの中心に配置され、画面上にすべてのマップアイテムが表示される最大の整数倍のズームレベルに設定されます。items が指定された場合、現在のビューポートは指定されたマップアイテムの境界のみに合わせて調整されます。

fitViewportToVisibleMapItemsも参照してください 。

void fitViewportToVisibleMapItems()

現在のビューポートを、表示されているすべての地図アイテムの境界に合わせます。カメラは地図アイテムの中心に配置され、画面上にすべての地図アイテムが表示されるように、可能な限り最大の整数倍のズームレベルに設定されます。

fitViewportToMapItemsも参照してください 。

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

coordinate に対応するマップアイテムからの相対位置を返します。

clipToViewPort がtrue である場合、または指定されていない場合、coordinate が現在のビューポート内にないときは、無効なQPointF を返します。

void pan(int dx, int dy)

x軸方向にdx ピクセル、y軸方向にdy ピクセルの位置からマップのパンを開始します。

dx の値が正の場合、マップは右方向に移動し、負の場合は左方向に移動します。dy の値が正の場合、マップは下方向に移動し、負の場合は上方向に移動します。

パン操作中は、center およびzoomLevel の値が変化する場合があります。

void prefetchData()

このアイドル期間中にマップのプリフェッチを可能にするオプションのヒント

void removeMapItem(MapItem item)

指定されたitem をMapから削除します（例：MapQuickItem 、MapCircle ）。MapItemが存在しない場合、または以前にMapに追加されていない場合、このメソッドは何も行いません。

mapItems 、addMapItem 、およびclearMapItemsも参照してください 。

void removeMapItemGroup(MapItemGroup itemGroup)

itemGroup およびそこに含まれる項目をマップから削除します。

「 MapItemGroup 」および「addMapItemGroup 」も参照してください 。

void removeMapItemView(MapItemView itemView)

itemView およびそれによってインスタンス化された項目を Map から削除します。

MapItemView およびaddMapItemViewも参照してください 。

void setBearing(real bearing, coordinate coordinate)

マップの方位をbearing に設定し、coordinate を軸として回転させます。マップに使用されているプラグインが方位をサポートしている場合、bearing の有効範囲は0から360の間となります。 マップに使用されているプラグインが方位角をサポートしていない場合、マップが傾いていてcoordinate がカメラの背後にある場合、またはマップの準備が整っていない場合（mapReady を参照）、このメソッドを呼び出しても何の効果もありません。

Qt 5.10 でのこの API のリリースは、テクノロジープレビューです。

coordinate toCoordinate(QPointF position, bool clipToViewPort)

マップアイテムを基準として、position に対応する座標を返します。

clipToViewPort がtrue である場合、または指定されていない場合、position が現在のビューポート内にないときは無効な座標を返します。