Place QML Type

「場所」タイプは、注目すべき位置である場所を表します。詳細...

• 継承されたメンバーを含むすべてのメンバーの一覧

プロパティ

• attribution : string
• categories : list<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : string
• placeId : string
• plugin : Plugin
• primaryEmail : string
• primaryFax : string
• primaryPhone : string
• primaryWebsite : string
• ratings : Ratings
• reviewModel : ReviewModel
• status : enumeration
• supplier : Supplier
• visibility : enumeration

方法

• void copyFrom(Place original)
• string errorString()
• void getDetails()
• void initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

詳細な説明

「Place」タイプは、物理的な場所とその場所を説明する追加のメタデータを表します。これに対し、「Location 」、「Address 」、「geoCoordinate 」タイプは、場所がどこにあるかを記述するために使用されます。「Place」の基本的なプロパティは、「name 」と「location 」です。

Placeオブジェクトは通常、検索モデルから取得され、一般的には基本プロパティのみが設定されています。detailsFetched プロパティを使用すると、Plugin からさらにプロパティ値を取得する必要があるかどうかを判定できます。これは、getDetails()メソッドを呼び出すことで実行できます。 取得操作の進行状況は、status プロパティで監視できます。このプロパティは、詳細が取得されている間はPlace.Fetchingに設定されます。

Place 型には、その場所に関する情報を保持する多くのプロパティがあります。その場所への連絡方法の詳細は、contactDetails プロパティから取得できます。また、主要なphone 、fax 、email 、およびwebsite を取得するための便利なプロパティも用意されています。

各場所には、0個以上のcategories が割り当てられます。カテゴリは通常、レストランやホテルなど、特定の種類の場所を検索する際に使用されます。一部の場所にはratings オブジェクトがあり、その場所の品質を示します。

場所のメタデータはsupplier によって提供され、この は、場所の詳細が表示される際に、ユーザーに対してattribution メッセージを表示するよう要求する場合があります。

場所には関連付けられたicon があり、これを使用して地図上に場所を表示したり、ビュー内のデリゲートを装飾したりすることができます。

場所には、追加のリッチコンテンツが関連付けられている場合があります。現在サポートされているリッチコンテンツには、編集者による説明、レビュー、画像が含まれます。これらは、コンテンツを取得するための一連のモデルとして公開されています。場所の編集者による説明は、editorialModel プロパティから取得できます。場所のレビューは、reviewModel プロパティから取得できます。場所の写真ギャラリーには、imageModel プロパティを使用してアクセスできます。

場所には、正式なAPIで扱われていない追加の属性が存在する場合があります。extendedAttributes プロパティを使用すると、これらの属性にアクセスできます。利用可能な拡張属性の種類は、各Plugin によって異なります。

「Place」は、ほとんどの場合「plugin 」に関連付けられています。「plugin 」プロパティを設定してからでないと、「save()」、「remove()」、または「getDetails()」を呼び出すことはできません。「reviewModel 」、「imageModel 」、および「editorialModel 」は、「plugin 」プロパティが設定されている場合にのみ有効です。

場所の保存

Plugin が対応している場合、Place型を使用して場所を保存できます。まず、新しいPlaceを作成し、そのプロパティを設定します：

Place {
    id: myPlace
    plugin: myPlugin

    name: "Brisbane Technology Park"
    location: Location {
        address: Address {
            street: "53 Brandl Street"
            city: "Eight Mile Plains"
            postalCode: "4113"
            country: "Australia"
        }
        coordinate {
            latitude: -27.579646
            longitude: 153.100308
        }
    }

    visibility: Place.PrivateVisibility
}

次に、save() メソッドを呼び出します：

    myPlace.save();

status プロパティは、Place.Savingに変化し、保存が成功した場合はPlace.Readyに、エラーが発生した場合はPlace.Errorに変わります。

placeId プロパティが設定されている場合、バックエンドは既存の場所を更新し、そうでない場合は新しい場所を作成します。成功すると、placeId プロパティに新しく保存された場所の識別子が設定されます。

注意事項

Places APIは現在、core の詳細情報の保存のみを目的として設計されています。画像やレビューなどのリッチコンテンツ、あるいはサプライヤーや評価といった詳細情報の保存は、サポート対象外です。通常、管理者は保存時にこれらのフィールドを無視し、値が入力されている場合は警告メッセージを表示する場合があります。

Places API が保存をサポートしているのは、以下の主要な詳細情報のみです：

• name
• 場所 ID
• 場所
• 連絡先情報
• アイコン
• カテゴリ（場所を説明するタグのような名称）
• 公開範囲

プロバイダーによっては、これらのうちの一部のみをサポートしている場合があります。詳細については、プラグインのドキュメントを参照してください。

評価、拡張属性、画像、レビュー、編集記事、サプライヤーなどのプロパティの保存は、Places API では明示的にサポートされていません。

プラグイン間の保存

プラグイン間で場所を保存する際、注意すべき点がいくつかあります。ID、カテゴリ、アイコンなど、場所のフィールドの一部はプラグイン固有のエンティティです。例えば、あるマネージャーでのカテゴリが、別のマネージャーでは認識されない場合があります。そのため、あるプラグインから別のプラグインへ場所を直接保存することはできません。

一般的に、プラグイン間の保存は、「お気に入り」セクションで説明されているように、favorites として保存することを推奨します。ただし、別のアプローチとして、新しい場所を作成し、その（宛先）プラグインを設定してから、copyFrom()メソッドを使用して元の場所の詳細をコピーする方法もあります。copyFrom() を使用すると、宛先プラグインでサポートされているデータのみがコピーされ、場所識別子などのプラグイン固有のデータはコピーされません。コピーが完了すると、その場所は保存可能な状態になります。

以下のスニペットは、copyFrom メソッドを使用して、場所を別のプラグインに保存する例を示しています：

var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

プレイスの削除

場所を削除するには、有効な `placeId ` プロパティを持つ `Place` オブジェクトが存在することを確認し、その `remove()` メソッドを呼び出します。保存が成功した場合は、`status ` プロパティが `Place.Removing` に変化し、その後 `Place.Ready` になります。エラーが発生した場合は `Place.Error` になります。

お気に入り

Places API は「お気に入り」の概念をサポートしています。お気に入りは通常、2 つのプラグインを使用して実装されます。1 つ目のプラグインは一般的に場所の読み取り専用ソース（オリジンプラグイン）であり、2 つ目の読み書き可能なプラグイン（デスティネーションプラグイン）は、オリジンプラグインからの場所をお気に入りとして保存するために使用されます。

各 Place には favorite プロパティがあり、これは宛先プラグインからの対応する場所（場所自体は元プラグインから取得されます）を格納することを目的としています。元の場所と「お気に入り」インスタンスの両方が利用可能であるため、開発者はユーザーにどのプロパティを表示するかを選択できます。たとえば、「お気に入り」には、元の名前ではなく表示すべき変更された名前が設定されている場合があります。

Text { text: place.favorite ? place.favorite.name : place.name }

以下は、新しい「お気に入り」インスタンスを保存する方法を示しています。まず、「お気に入り」インスタンスを作成・初期化する呼び出しを行い、その後、そのインスタンスを保存します。

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

以下は、お気に入りの削除方法を示しています：

place.favorite.remove();
    ...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

PlaceSearchModel にはfavouritesPluginプロパティがあります。このプロパティが設定されている場合、検索中に見つかった場所について、favouritesPluginと照合され、対応する「お気に入り」の場所があるかどうかが確認されます。ある場合は、Placeのfavouriteプロパティが設定され、ない場合はfavouriteプロパティはnullのままとなります。

PlaceSearchModelも参照してください 。

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

attribution : string

このプロパティには、その場所に関するリッチテキスト形式の帰属情報文字列が格納されています。一部のプロバイダーでは、場所が表示されるたびに、その帰属情報をユーザーに表示することを義務付けている場合があります。このプロパティの内容が空でない場合は、ユーザーに表示する必要があります。

categories : list<Category> [read-only]

このプロパティには、この場所が属するカテゴリのリストが格納されます。場所に割り当て可能なカテゴリは、plugin ごとに異なります。

contactDetails : ContactDetails [read-only]

このプロパティには、この場所の連絡先情報（電話番号やウェブサイトのURLなど）が格納されています。このプロパティは、contactDetail オブジェクトのマップです。

detailsFetched : bool [read-only]

このプロパティは、その場所の詳細情報が取得済みかどうかを示します。このプロパティの値が false の場合、その場所の詳細情報はまだ取得されていません。取得を行うには、getDetails() メソッドを呼び出します。

getDetails()も参照してください 。

editorialModel : EditorialModel [read-only]

このプロパティには、その場所に関する編集上の説明を取得するために使用できるモデルが格納されています。

extendedAttributes : ExtendedAttributes [read-only]

このプロパティには、場所の拡張属性が格納されます。拡張属性とは、その場所のプロパティではカバーされていない、その場所に関する追加情報のことです。

favorite : Place

このプロパティには、場所のお気に入りインスタンスが格納されます。

icon : Icon

このプロパティには、その場所を表すために使用できるグラフィックアイコンが格納されています。

imageModel : ImageModel [read-only]

このプロパティには、その場所の画像を取得するために使用できるモデルが格納されています。

location : QtPositioning::Location

このプロパティには、座標、住所、およびバウンディングボックスを取得するために使用できる場所の位置情報が格納されています。

name : string

このプロパティには、その場所を表すために使用できる場所の名前が格納されています。

placeId : string

このプロパティには、その場所の一意の識別子が格納されます。場所識別子は、それを生成したPlugin に対してのみ意味を持ち、Plugins 間で転送することはできません。場所IDは普遍的に一意であるとは保証されませんが、それを生成したPlugin 内では一意です。

場所識別子のみがわかっている場合、その他のすべての場所データはPlugin から取得できます。

    place.plugin = myPlugin;
    place.placeId = "known-place-id";
    place.getDetails();

plugin : Plugin

このプロパティには、この場所を提供したPlugin が格納されており、これを使用してサービスに関する詳細情報を取得することができます。

primaryEmail : string [read-only]

このプロパティには、その場所の主なメールアドレスが格納されます。この場所に「メール」の連絡先情報が定義されていない場合、このプロパティは空の文字列になります。これは、

    var primaryEmail;
    if (place.contactDetails["email"].length > 0)
        primaryEmail = place.contactDetails["email"][0].value;

primaryFax : string [read-only]

このプロパティには、その場所の主なFAX番号が格納されます。この場所に「FAX」の連絡先情報が定義されていない場合、このプロパティは空の文字列になります。これは、

    var primaryFax;
    if (place.contactDetails["fax"].length > 0)
        primaryFax = place.contactDetails["fax"][0].value;

primaryPhone : string [read-only]

このプロパティには、その場所の主な電話番号が格納されます。この場所に「電話番号」の連絡先情報が定義されていない場合、このプロパティは空の文字列になります。これは、以下の記述と同等です：

    var primaryPhone;
    if (place.contactDetails["phone"].length > 0)
        primaryPhone = place.contactDetails["phone"][0].value;

primaryWebsite : string [read-only]

このプロパティには、その場所のメインのWebサイトのURLが格納されます。この場所に「Webサイト」の連絡先情報が定義されていない場合、このプロパティは空の文字列になります。これは、

    var primaryWebsite;
    if (place.contactDetails["website"].length > 0)
        primaryWebsite = place.contactDetails["website"][0].value;

ratings : Ratings

このプロパティには、その場所の評価が格納されています。評価は、その場所の質を示す指標となります。

reviewModel : ReviewModel [read-only]

このプロパティには、その場所に関するレビューを取得するために使用できるモデルが格納されています。

status : enumeration [read-only]

このプロパティは、その場所のステータスを保持します。以下のいずれかになります：

場所のステータスは、status プロパティをハンドラ関数に接続し、そのハンドラ関数でステータスの変更を処理することで確認できます。

place.statusChanged.connect(statusChangedHandler);
    ...
function statusChangedHandler() {
    if (statusChangedHandler.prevStatus === Place.Saving) {
        switch (place.status) {
        case Place.Ready:
            console.log('Save successful');
            break;
        case Place.Error:
            console.log('Save failed');
            break;
        default:
            break;
        }
    }
    statusChangedHandler.prevStatus = place.status;
}

supplier : Supplier

このプロパティには、場所データの提供元が格納されます。提供元とは、通常、その場所に関するデータを収集した企業や組織のことです。

visibility : enumeration

このプロパティは、その場所の可視性を保持します。以下のいずれかになります：

なお、可視性は、デバイス上のアプリケーションのユーザーインターフェースにおける場所の表示方法には影響しません。代わりに、場所の共有に関する動作を定義します。

メソッドのドキュメント

void copyFrom(Place original)

original のプレースからこのプレースへデータをコピーします。このプレースのプラグインでサポートされているデータのみがコピーされ、プレース識別子などのプラグイン固有のデータはコピーされません。

string errorString()

最後の操作のエラーに関する説明を文字列として返します。最後の操作が正常に完了した場合は、文字列は空になります。

void getDetails()

このメソッドは、場所の詳細情報の取得を開始します。

取得処理が進行中は、status プロパティがPlace.Fetchingに変わります。成功した場合、オブジェクトのプロパティが更新され、status はPlace.Readyに、detailsFetched はtrueに設定されます。エラーが発生した場合は、status がPlace.Errorに設定されます。エラーの詳細を取得するには、errorString()メソッドを使用できます。

void initializeFavorite(Plugin destinationPlugin)

指定された場所のお気に入りインスタンスを作成し、それを宛先プラグイン「destinationPlugin 」に保存します。このメソッドは、favouriteプロパティがnull でない場合、何も実行しません。

void remove()

このメソッドは、その場所に対して削除操作を実行します。

保存処理が進行中は、status プロパティがPlace.Removingに変わります。成功した場合、status はPlace.Readyに設定されます。エラーが発生した場合、status はPlace.Errorに設定されます。エラーの詳細を取得するには、errorString()メソッドを使用できます。

void save()

このメソッドは、その場所に対して保存処理を実行します。

保存操作の進行中は、status プロパティがPlace.Savingに変わります。成功した場合、status はPlace.Readyに設定されます。エラーが発生した場合は、status はPlace.Errorに設定されます。エラーの詳細を取得するには、errorString()メソッドを使用できます。

placeId プロパティが以前に空だった場合、保存操作が成功すると、自動的に有効な値が割り当てられます。

なお、PlaceSearchModel は、更新が検出されたすべてのPlaceに対してPlace::getDetails を呼び出します。その結果、PlaceSearchModel 内のPlaceが正常に保存されるたびに、Placeの詳細情報の取得が行われ、Saving 、Ready 、Fetching 、Ready という一連の状態変化が生じます。