QML Places API

概要

Places API を使用すると、ユーザーは関心のある場所を検索し、住所や連絡先情報などの詳細を確認できます。場所によっては、画像やレビューなどの追加コンテンツが関連付けられている場合もあります。 また、Places API を使用すると、場所やカテゴリを管理し、保存や削除を行うことができます。場所には経路、道路、交通手段などが含まれる場合もあり、これによりナビゲーションの最適化や支援が可能になります。ナビゲーションの詳細については、routes を参照してください。

基本概念

プラグイン

Plugin は、バックエンドの抽象化です。あるPlugin はRESTサーバーから場所にアクセスする一方、別の はローカルデータベースから場所にアクセスする場合があります。以下のコードは、「osm」という名前を指定してPlugin オブジェクトをインスタンス化しています。Plugin という名前は、どのバックエンドを選択するかを指定します。 プラグインには、一連のparameters が提供されることもあります。これは基本的にキーと値のペアの集合という形式をとります。指定可能なparameters は、Plugin のバックエンドごとに異なります。利用可能なparameters や、各Plugin の微妙な違いに関するドキュメントについては、「Plugin References」を参照してください。

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

モデル、ビュー、およびデリゲート

QML Places APIは、モデル、ビュー、デリゲートという概念を基盤として構築されています。

以下の「一般的なユースケース」セクションでは、これらの概念がどのように組み合わさるかを具体的な例で示します。

一般的なユースケース

場所の検索

検索は、`PlaceSearchModel` を通じて行われます。`plugin ` プロパティは、検索操作を実行する対象となるバックエンドを指定します。検索パラメータは、`searchTerm ` や `searchArea` などのプロパティを通じて指定できます。その後、`update()` メソッドを呼び出すことで、検索操作を開始できます。 簡略化のため、以下のスニペットではモデルの構築が完了した時点でupdate()を呼び出していますが、通常はボタンのクリックなどのユーザー操作に応じてupdate()が呼び出されます。検索操作が進行中は、PlaceSearchModel::status プロパティがLoading 状態に移行し、正常に完了するとReady 状態に移行します。

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "food"
    searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);

    Component.onCompleted: update()

}

ListView を使用した検索結果の表示

ListView を使用すると、モデルによって見つかった検索結果を表示できます。これは結果が表示される視覚領域を定義するもので、以下の例では親コンポーネント全体を埋め尽くしています。ListView には、フリック操作に反応して適切にスクロールする機能が組み込まれています。

以下のスニペットでは、検索モデルがListView のmodel プロパティに割り当てられています。モデルが新しい結果で更新されると、ListView はモデルの新しいデータ項目を反映するように自動的に更新されます。

ListView のdelegate プロパティには、単純なデリゲートがバインドされています。PlaceSearchModel は一連のroles を公開しており、以下ではそのうちのtitleおよびplaceロールが使用されています。これらはそれぞれstring型およびPlace 型です。基本的に、ビューに表示されるべき各データ項目について、ビューはデリゲートを呼び出してその項目の視覚的表現を作成します。

ListView { anchors.fill: parent model: searchModel delegate: Component { Row { spacing: 5 Marker { height: parent.height } Column { Text { text: title; font.bold: true } Text { text: place.location.address.text } } } } }

完全なソースコードについては、「Places List」の例を参照してください。

MapItemView を使用した検索結果の表示

ListView の代わりに、PlaceSearchModel をMapItemView と組み合わせて使用し、地図上にマーカーを表示することができます。まず、Map を使用して、地図が占める視覚的な領域を定義します。この例では、親要素の全体を埋めるように設定されています。その他にも、地図を提供するplugin や、地図のcenter およびzoomLevel などのプロパティが指定されます。

Map 内では、MapItemView が宣言されており、model プロパティには検索モデルが設定されています。また、MapQuickItem で構成されるdelegate を使用して、マーカー画像が表示されています。検索モデルによって見つかったすべての場所に対して、マーカーが表示されます。デリゲートはplaceロールを使用してマーカーの位置を決定します。

MapView { id: view anchors.fill: parent map.plugin: myPlugin; map.center: positionSource.lastSearchPosition map.zoomLevel: 13 MapItemView { model: searchModel parent: view.map delegate: MapQuickItem { coordinate: place.location.coordinate anchorPoint.x: image.width * 0.5 anchorPoint.y: image.height sourceItem: Column { Image { id: image; source: "marker.png" } Text { text: title; font.bold: true } } } } }

完全なソースコードについては、「Places Map」の例を参照してください。

場所の詳細情報の取得

帯域幅を節約するため、バックエンドによっては、詳細情報が部分的にしか設定されていない場所のみを返す場合があります。これは、利用可能な詳細情報がすべて取得済みかどうかを示すPlace::detailsFetched プロパティで確認できます。取得されていない場合は、Place::getDetails()メソッドを呼び出して、残りの詳細情報を取得できます。

if (!place.detailsFetched)
    place.getDetails();

場所の保存と削除

一部のバックエンドでは、場所の保存や削除をサポートしている場合があります。これらは、それぞれ `Place::save()` メソッドおよび `Place::remove()` メソッドを呼び出すことで実行できます。 なお、Place を保存するには、保存先のバックエンドを指定するためにPlugin を割り当てる必要があります。保存操作が行われている間、status プロパティはSaving 状態に移行し、正常に完了するとReady 状態に移行します。以下のスニペットは、JavaScriptを使用してPlacesを保存および削除する方法を示しています。

//creating and saving a place
var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = myPlugin;
place.name = "New York";
place.location.coordinate.latitude = 40.7
place.location.coordinate.longitude = -74.0
place.save();

//removing a place
place.remove();

詳細

上記のスニペットは、Placesの機能のごく一部しか示していません。images やreviews などのより豊富なコンテンツ、およびより詳細な説明については、以下に示すPlacesのタイプを参照してください。

API の使用方法に関するより包括的なデモについては、「Places (QML)」のサンプルも参照してください。

Places タイプ

データ型

モデル