Map QML Type

Mapタイプは地図を表示します。詳細...

• 継承メンバを含む全メンバ一覧
• MapはQML Maps Pluginの一部です。

プロパティ

• 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次元的に視覚化するさまざまな方法がありますが、そのすべてに何らかの投影が関係しています。つまり、3D座標（緯度、経度、高度）と画面上の2D座標（ピクセル単位のXとY）の間の数学的関係です。

地図データの異なるソースは異なる投影を使うことができ、Map タイプの観点からは、これらを1つの置き換え可能な単位、Map プラグインとして扱います。Mapプラグインはデータソースと、そのデータを画面に表示するために必要なその他の詳細から構成されます。

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

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

マップが表示されるとき、表示可能な地理座標はそれぞれ、画面上のあるピクセルの X 座標と Y 座標にマップされます。この2つの間の変換を行うために、MapはtoCoordinate とfromCoordinate 関数を提供しており、これらは一般的に有用です。

地図オブジェクト

マップ関連のオブジェクトはQt Quick 、マップオブジェクトのボディの中で宣言することができ、自動的にマップ上に現れます。プログラムでオブジェクトを追加するには、まずそのオブジェクトがマップを親として作成されていることを確認してください（例えば、Component::createObject の引数で）。次に、このオブジェクトのタイプがMapCircle 、MapRectangle 、MapPolyline 、MapPolygon 、MapRoute 、MapQuickItem のいずれかである場合、マップ上でaddMapItem メソッドを呼び出します。対応するremoveMapItem メソッドも存在し、上記のタイプのマップオブジェクトをマップから削除することができます。

マップオブジェクトを移動させたり、サイズを変えたり、形を変えたりすることは、通常、マップ自体との特別なインタラクションを必要としません - マップオブジェクトのこれらのプロパティを変更すると、自動的に表示が更新されます。

パフォーマンス

マップはOpenGL (ES)とQt Scene Graphsスタックを使ってレンダリングされます。

オンライン "マップの場合、ネットワーク帯域幅と待ち時間が、ユーザーのパフォーマンス知覚に大きく影響します。これを緩和するために広範なキャッシュが実行されますが、このような緩和は必ずしも完全ではありません。

一般的に、ポリゴンやポリラインのような頂点数の多い大きく複雑なマップアイテムは、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から360の間です。マップに使用されているプラグインが方位をサポートしていない場合、このプロパティを変更しても効果はありません。

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

center : coordinate

このプロパティは、マッピングビューポートの中心を占める座標を保持する。無効な中心座標は無視される。

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

color : color

このプロパティは、マップ要素の背景色を保持する。

copyrightsVisible : bool

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

error : enumeration [read-only]

この読み取り専用プロパティは、最後に発生したマッピング・サービス・プロバイダ・エラーを保持する。

• マップ。NoError - エラーは発生していません。
• Map.NotSupportedError -マップ・プラグイン・プロパティが設定されていないか、プラグインに関連付けられているマッピング・マネージャがありません。
• Map.UnknownParameterError -プラグインが指定されたパラメータを認識できませんでした。
• Map.MissingRequiredParameterError - プラグインが指定したパラメータが見つかりません。
• Map.ConnectionError - プラグインがバックエンド サービスまたはデータベースに接続できませんでした。

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

errorString : string [read-only]

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

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

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

fieldOfView : real [since QtLocation 5.9]

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

この値を変更すると、カメラとマップ間の距離も暗黙のうちに変更されるため、傾斜角度が0度の場合、このプロパティに使用されるどの値でも、結果として得られる画像は同じであることに注意してください。

このパラメータの詳細については、WikipediaのField of viewと Angle of viewの記事を参照してください。

このプロパティは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

このプロパティは、マッピング機能を提供するプラグインを保持します。

これはライトワンス・プロパティです。一度マップにプラグインが関連付けられると、プラグインを変更しようとしても無視されます。

supportedMapTypes : list<mapType> [read-only]

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

activeMapTypeも参照のこと 。

tilt : real [since QtLocation 5.9]

このプロパティはマップの傾きを度単位で保持する。この値の有効範囲は [minimumTilt,maximumTilt ] です。マップに使用されているプラグインが傾きをサポートしていない場合、このプロパティを変更しても効果はありません。

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

minimumTilt とmaximumTiltも参照して ください。

visibleArea : rect

このプロパティは Map QML 要素内の可視領域を保持します。このプロパティの座標は Map 要素からの相対座標です。そのサイズは Map 要素のサイズにクランプされます。visibleArea が NULL の場合、Map 全体が表示されます。

visibleRegion : geoShape

このプロパティは、マップのビューポートを占める領域を保持する。カメラはシェイプの中心に配置され、シェイプ全体がスクリーン上に見えるように、可能な限り最大の積分ズームレベルで配置される。これは、このプロパティが設定された直後にこのプロパティを読み返すと、返される領域が設定された領域と等しいか大きくなることを意味する。

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

zoomLevel : real

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

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

シグナル・ドキュメント

copyrightLinkActivated(string link)

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

メソッド・ドキュメント

void addMapItem(MapItem item)

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

例として、現在位置を表す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 に含まれるマップアイテムをマップに追加します （例えば、MapQuickItem,MapCircle ）。

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

void addMapItemView(MapItemView itemView)

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

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

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

coordinate pointこのメソッドは、center qml プロパティによって提供される機能を効果的に拡張し、Map 要素の中心以外のポイントに座標を合わせることを可能にします。これは、シーンの中心（例えば、カーソル）がマップの中心に正確に配置されないようなアプリケーションで便利です。

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

この API の Qt 5.10 でのリリースは技術プレビューです。

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 をマップから削除する（例：MapQuickItem,MapCircle ）。MapItem が存在しないか、以前にマップに追加されていない場合、このメソッドは何も行いません。

mapItems,addMapItem,clearMapItemsも参照してください 。

void removeMapItemGroup(MapItemGroup itemGroup)

itemGroup とその中に含まれるアイテムをマップから削除します。

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

void removeMapItemView(MapItemView itemView)

itemView と、それによってインスタンス化されたアイテムをマップから削除します。

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

void setBearing(real bearing, coordinate coordinate)

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

この API の Qt 5.10 でのリリースは技術プレビューです。

coordinate toCoordinate(QPointF position, bool clipToViewPort)

マップアイテムからの相対座標position に対応する座標を返す。

clipToViewPort がtrue である場合、またはposition がカ レ ン ト ビ ュ ーポー ト 内にない場合には無効な座標を返す。