QML Places API

概要

Places API を使うと、ユーザは興味のある場所を発見し、住所や連絡先などの詳細情報を閲覧することができます。場所によっては、画像やレビューなどの追加コンテンツを持つこともあります。Places APIでは、場所やカテゴリを管理することもできます。また、場所には道や道路、交通機関を含めることができ、ナビゲーションの最適化や補助が可能になります。ナビゲーションの詳細については、routeをご覧ください。

導入概念

プラグイン

Plugin はバックエンドの抽象化です。あるPlugin は REST サーバーから場所にアクセスするかもしれないし、別のものはローカルデータベースから場所にアクセスするかもしれない。以下は、"osm "という名前を与えて、Plugin オブジェクトをインスタンス化する。Plugin という名前は、どのバックエンドを選択するかを示す。プラグインはまた、parameters 、基本的にキーと値のペアのセットを提供することができる。指定できるparameters は、Plugin バックエンドによって異なります。それぞれのPlugin で可能なparameters やニュアンスについては、プラグインリファレンスを参照してください。

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 の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 の代わりに、MapItemView とともにPlaceSearchModel を使用することができます。まず、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を使用して場所を保存および削除する方法を示しています。

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

さらに詳しく

上記のスニペットは、プレイス機能のほんの一部です。images やreviews などのリッチなコンテンツや、より詳細な説明や解説については、以下に示すPlaces Typesを参照してください。

Places(QML)のサンプルでは、APIの使い方をより包括的に紹介しています。

Placesのデータ型

データ型

モデル