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() が実行された際に一度だけ一括取得を行う点に注意してください。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 が格納されます。検索結果の中から、favouritesPluginと照合または一致する場所がある場合、その場所のfavorite プロパティには、favouritesPlugin内の対応するPlace が設定されます。

favouritesPlugin が設定されていない場合、検索結果に含まれる場所の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 のバックエンドの実装によって異なる場合があります。たとえば、検索中心点のみをサポートするものもあれば、ジオレクタングル（geo rectangles）のみをサポートするものもあります。

searchTerm : string

このプロパティには、クエリで使用された検索語が格納されます。検索語は自由形式のテキスト文字列です。

status : enum [read-only]

このプロパティはモデルのステータスを保持します。値は以下のいずれかになります：

visibilityScope : enum

このプロパティは、検索対象となる場所の公開範囲を指定します。検索結果には、指定された公開範囲に該当する場所のみが表示されます。

可視性の範囲は、以下のいずれかになります：

Signal ドキュメント

dataChanged()

このシグナルは、基となるデータストアに大幅な変更が加えられた際に発信されます。

アプリケーションはこのシグナルに対して、独自の判断で対応する必要があります。モデルから提供されるデータは古くなっている可能性があるため、いずれはモデルを再更新する必要がありますが、ユーザーが何も操作していないにもかかわらず結果が変化すると、直ちに再更新を行うとユーザーを戸惑わせる恐れがあります。

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

メソッドのドキュメント

void cancel()

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

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

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

Variant data(int index, string role)

指定されたrole の、指定された行index にあるデータを返します。

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を参照していない場合、このメソッドは何も実行しません。