PlaceSearchModel QML Type

プレイス検索結果へのアクセスを提供します。詳細...

• 継承されたメンバーを含む全メンバーのリスト

プロパティ

• categories : list<Category>
• count : int
• favoritesMatchParameters : VariantMap
• favoritesPlugin : Plugin
• incremental : bool (since QtLocation 5.12)
• limit : int
• nextPagesAvailable : bool
• plugin : Plugin
• previousPagesAvailable : bool
• recommendationId : string
• relevanceHint : enumeration
• searchArea : variant
• searchTerm : string
• status : enum
• visibilityScope : enum

信号

• dataChanged()

方法

• void cancel()
• Variant data(int index, string role)
• string errorString()
• void nextPage()
• void previousPage()
• void reset()
• void update()
• void updateWith(int proposedSearchIndex)

詳細

PlaceSearchModel は、searchArea 内の場所の検索結果のモデルを提供します。searchTerm とcategories プロパティを設定することで、検索結果をそれらの条件に一致する場所に制限することができます。

PlaceSearchModel は、スポンサー検索結果とオーガニック検索結果の両方を返します。スポンサードサーチの結果は、sponsored ロールが true に設定されます。

このモデルは以下のロールのデータを返します：

検索結果の種類

type 役割は以下の値を取ることができます：

Loader を使用して、検索結果の種類に応じて異なるComponentを選択するデリゲートを作成すると便利です。

Component {
    id: resultDelegate
    Loader {
        Component {
            id: placeResult

            Column {
                Text { text: title }
                Text { text: place.location.address.text }
            }
        }

        Component {
            id: otherResult
            Text { text: title }
        }

        sourceComponent: type == PlaceSearchModel.PlaceResult ? placeResult :
                                                                otherResult
    }
}

更新された場所と削除された場所の検出

PlaceSearchModel はプラグインのバックエンドから更新または削除された場所を探します。場所が更新され、その場所がモデル内に存在することを検知した場合、Place::getDetails を呼び出し、詳細を更新します。もしプレイスが削除されたことを検知した場合、そのプレイスがモデル内に存在するのであれば、そのプレイスはモデルから削除されます。

例

次の例は、PlaceSearchModel を使って、指定された位置の近くにあるピザレストランを検索する方法を示しています。searchTerm とsearchArea がモデルに提供され、update() が検索クエリを実行するために使用されます。このモデルは、検索結果をインクリメンタルにフェッチするのではなく、update （）が実行されたときに1回のフェッチを実行することに注意してください。count には、フェッチ中に返された検索結果の数が設定されます。

import QtQuick
import QtPositioning
import QtLocation

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

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

    Component.onCompleted: update()

}

ページング

PlaceSearchModel API はページングを制限付きでサポートしています。nextPage() とpreviousPage() 関数、そしてlimit プロパティを使用することで、ページングされた検索結果にアクセスすることができます。limit プロパティが設定されている場合、検索結果ページには最大でlimit の項目（place result 型）が含まれます。例えば、バックエンドに合計5つの検索結果[a,b,c,d,e]があり、最初のページが表示され、リミット3が設定されているとすると、a,b,cが返されます。nextPage()はd,eを返すでしょう。nextPagesAvailable とpreviousPagesAvailable プロパティは、さらに他のページをチェックするために使用できます。現時点では、APIはバックから利用可能なアイテムの総数を取得する手段をサポートしていません。nextPage （）、previousPage （）、limit （）のサポートは、plugin 。

CategoryModel およびQPlaceManagerも参照のこと 。

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

categories : list<Category> [read-only]

このプロパティは、検索時に使用するカテゴリのリストを保持します。返される検索結果は、少なくとも1つのカテゴリに一致する場所となります。

count : int [read-only]

このプロパティはモデルが持つ検索結果の数を保持します。

バックエンドで利用可能な検索結果の総数を指すものではないことに注意してください。検索結果の総数は現在APIではサポートされていません。

favoritesMatchParameters : VariantMap

このプロパティは、検索結果の場所をfavoritesPlugin のお気に入りにマッチさせる方法を指定するためのパラメータのセットを保持します。

デフォルトでは、パラメータマップは空であり、お気に入りプラグインは代替識別子でマッチングすることを意味します。通常、アプリケーション開発者はこのプロパティを設定する必要はありません。

お気に入りプラグインが代替識別子によるマッチングをサポートしていない場合、どのようなキー・バリュー・パラメータを設定すればよいかは、プラグインのドキュメントを参照する必要があります。

favoritesPlugin : Plugin

このプロパティは、お気に入りの検索に使用されるPlugin を保持します。検索結果のうち、favoritesPluginで相互参照または照合可能な場所には、そのfavorite プロパティにfavoritesPluginの対応するPlace が設定されます。

favoritesPlugin が設定されていない場合、検索結果の場所のfavorite プロパティは常に null になります。

Favoritesも参照してください 。

incremental : bool [since QtLocation 5.12]

このプロパティは、ページングがPlaceSearchModel にどのような影響を与えるかを制御します。true の場合、previousPage またはnextPage を呼び出してもモデルはリセットされず、代わりに新しい結果がモデルに追加されます。デフォルトはfalseです。

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

limit : int

このプロパティは、返されるアイテムの数の上限を保持する。

nextPagesAvailable : bool [read-only]

このプロパティは、検索結果の追加ページが1ページ以上あるかどうかを保持する。

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

plugin : Plugin

このプロパティは、検索に使用されるPlugin を保持する。

previousPagesAvailable : bool [read-only]

このプロパティは、検索結果の前のページが1つ以上あるかどうかを保持する。

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

recommendationId : string

このプロパティは、類似の場所の推奨を見つけるために使用されるplaceIdを保持します。

relevanceHint : enumeration

このプロパティは、検索クエリで使用される関連性のヒントを保持する。このヒントは、結果の順位付けを決定するのではなく、手助けをするためにプロバイダに与えられます。例えば、距離のヒントはより近い場所に高いランキングを与えるかもしれないが、必ずしも結果が距離に従って厳密に並べられることを意味しない。プロバイダはヒントを完全に無視することもできます。

searchArea : variant

このプロパティは検索領域を保持する。モデルによって返される検索結果は、検索領域内にある。

このプロパティがgeoCircle に設定されている場合、そのradius プロパティは未設定のままでもかまいません。その場合、Plugin が検索のための適切な半径を選択します。

検索領域を指定するためのサポートは、plugin バックエンドの実装によって異なります。例えば、検索中心のみをサポートするものもあれば、ジオ・レクタングルのみをサポートするものもあります。

searchTerm : string

このプロパティは、クエリで使用される検索語を保持する。検索語は自由形式のテキスト文字列です。

status : enum [read-only]

このプロパティはモデルの状態を保持する。以下のいずれかになります：

visibilityScope : enum

このプロパティは、検索する場所の可視範囲を保持する。指定された可視性を持つ場所のみが検索結果に返されます。

可視性の範囲は以下のいずれかです：

Signal ドキュメント

dataChanged()

このシグナルは、基礎となるデータストアに重大な変更が加えられたときに発せられる。

このシグナルはアプリケーションの判断で処理されるべきものです。モデルによって提供されるデータは古くなっている可能性があるため、モデルはいつか更新されるべきですが、ユーザが何もせずに結果が変更された場合、即時の再更新はユーザを不安にさせるかもしれません。

対応するハンドラはonDataChanged です。

メソッドのドキュメント

void cancel()

進行中の検索操作を直ちにキャンセルし、モデルのステータスをPlaceSearchModel.Ready に設定する。モデルは、操作が開始される前に持っていた検索結果を保持します。

操作が進行中でない場合、cancel() を起動しても何の効果もありません。

update() およびstatusも参照してください 。

Variant data(int index, string role)

指定された行index における、指定されたrole のデータを返す。

string errorString()

この読み取り専用プロパティは、最新の場所検索モデルエラーのテキスト表示を保持する。エラーが発生していない場合、またはモデルがクリアされた場合は、空の文字列が返される。

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

void nextPage()

検索結果の次のページを表示するようにモデルを更新します。次のページがない場合、このメソッドは何もしません。

void previousPage()

検索結果の前のページを表示するようにモデルを更新します。前のページがない場合、このメソッドは何もしません。

void reset()

モデルをリセットします。すべての検索結果はクリアされ、未解決のリクエストはすべて中止され、考えられるエラーはクリアされます。モデルのステータスはPlaceSearchModel.Null に設定されます。

void update()

提供されたクエリパラメータに基づいてモデルを更新します。モデルには、型のプロパティによって指定された検索パラメータにマッチする場所のリストが入力されます。検索条件は、searchTerm 、categories 、searchArea 、limit などのプロパティを設定することで指定される。これらのプロパティのサポートは、plugin によって異なるかもしれない。update() は次に、処理するために、plugin に基準のセットを提出する。

モデルが更新されている間、モデルのstatus はPlaceSearchModel.Loading にセットされる。モデルが正常に更新された場合、status はPlaceSearchModel.Ready にセットされ、更新が完了しなかった場合、status はPlaceSearchModel.Error にセットされ、モデルはクリアされる。

PlaceSearchModel {
    id: model
    plugin: backendPlugin
    searchArea: QtPositioning.circle(QtPositioning.coordinate(10, 10))
    ...
}

MouseArea {
    ...
    onClicked: {
        model.searchTerm = "pizza";
        model.categories = null;  //not searching by any category
        model.searchArea.center.latitude = -27.5;
        model.searchArea.center.longitude = 153;
        model.update();
    }
}

cancel() およびstatusも参照のこと 。

void updateWith(int proposedSearchIndex)

インデックスproposedSearchIndex の ProposedSearchResult に基づいてモデルを更新します。提案された検索にマッチする場所のリストがモデルに入力されます。モデルのステータスはPlaceSearchModel.Loading に設定されます。モデルが正常に更新された場合、ステータスはPlaceSearchModel.Ready に設定されます。エラーが発生した場合、ステータスはPlaceSearchModel.Error に設定され、モデルはクリアされます。

proposedSearchIndex が ProposedSearchResult を参照していない場合、このメソッドは何もしません。