PlaceSearchModel QML 类型

提供对位置搜索结果的访问。更多信息...

导入语句	import QtLocation 6.7
自	QtLocation 5.5

所有成员列表，包括继承成员

属性

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

方法

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

详细说明

PlaceSearchModel 提供了对搜索区域内的位置搜索结果的模型。可以通过设置 searchTerm 和 categories 属性来限制搜索结果以匹配这些标准。

PlaceSearchModel 返回赞助搜索结果和有机搜索结果。赞助搜索结果将设置 sponsored 角色为 true。

模型返回以下角色的数据

角色	类型	描述
type	enum	搜索结果的类型。
title	string	描述搜索结果的字符串。
icon	PlaceIcon	表示搜索结果的图标。
distance	real	仅在`type`角色是`PlaceResult`时有效，表示从搜索区域中心到地点的距离。如果没有指定`searchArea`，距离值为NaN。
地点	地点	仅在`type`角色是`PlaceResult`时有效，表示地点的对象。
赞助	bool	仅在`type`角色是`PlaceResult`时有效，如果搜索结果是赞助结果则为true。

搜索结果类型

type角色可取以下值

PlaceSearchModel.UnknownSearchResult	搜索结果的内容未知。
PlaceSearchModel.PlaceResult	搜索结果包含地点。
PlaceSearchModel.ProposedSearchResult	搜索结果包含可能相关的建议搜索。

根据搜索结果类型使用Loader创建代理通常很有帮助，它可以根据搜索结果类型选择不同的组件。

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条记录（类型为地点结果）。例如，如果后端总共有5个搜索结果[b,a,c,d,e]，并且假设显示了第一页并且设置了3的限制，则返回b,a,c。执行 nextPage()会返回d,e。可以使用 nextPagesAvailable和 previousPagesAvailable属性来检查是否有更多页面。目前，该API不支持从后端检索项目总数的手段。请注意，根据plugin的不同，对 nextPage()、previousPage()和limit的支持可能有所不同。

另请参阅 CategoryModel 和 QPlaceManager。

属性文档

categories : list<Category> [只读]

此属性保存用于搜索的分类列表。返回的搜索结果将是与至少一个分类匹配的地方。

count : int [只读]

此属性保存模型的结果数量。

注意，这并不指后端中可用的总搜索结果数量。API目前不支持搜索结果的总数。

favoritesMatchParameters : VariantMap

此属性保存用于指定如何将搜索结果位置与favoritesPlugin中的收藏匹配的一组参数。

默认情况下，参数映射为空，表示收藏插件通过替代标识符进行匹配。通常，应用程序开发者不需要设置此属性。

在收藏插件不支持通过替代标识符进行匹配的情况下，应查阅插件文档，以了解需要设置哪些精确的键值参数。

favoritesPlugin : Plugin

此属性保存将要用于搜索收藏的Plugin。任何可以从搜索中交叉引用或与favoritesPlugin匹配的地方，它们的favorite属性都将设置为来自favoritesPlugin的相应Place。

如果未设置favoritesPlugin，结果中的地方favorite属性将始终为null。

另请参阅 收藏。

incremental : bool [始于 QtLocation 5.12]

此属性控制分页如何影响PlaceSearchModel。如果为true，则调用previousPage或nextPage将不会重置模型，但新结果将追加到模型中。默认为false。

此属性是在QtLocation 5.12中引入的。

limit : int

此属性保存将要返回的项目数量限制。

nextPagesAvailable : bool [只读]

此属性表示是否有更多搜索结果页面可用。

另请参阅 nextPage()。

plugin : Plugin

此属性保存将要用于执行搜索的Plugin。

previousPagesAvailable : bool [只读]

此属性表示是否有更多前面搜索结果页面可用。

另请参阅 previousPage()。

recommendationId : string

此属性存储用于查找类似地点的placeId。

relevanceHint : 枚举

此属性持有用于搜索查询的相关提示。提示被提供给供应商以帮助但不会规定结果排序。例如，距离提示可能会使更近的地点获得更高的排名，但这并不一定意味着结果将严格按照距离排序。供应商可能完全忽略该提示。

SearchResultModel.UnspecifiedHint	未向供应商提供相关提示。
SearchResultModel.DistanceHint	地点与用户当前位置的距离对用户很重要。此提示仅在圆形搜索区域中使用时才有意义。
SearchResultModel.LexicalPlaceNameHint	地点名称的词汇顺序（按字母顺序升序排序）与用户相关。此提示对基于本地数据存储的供应商很有用。

searchArea : variant

此属性存储搜索区域。模型返回的搜索结果将在搜索区域内。

如果此属性设置为geocircle，则其radius属性可以未设置，在这种情况下，插件将选择适合搜索的适当半径。

指定搜索区域的支持可变，具体取决于插件后端实现。例如，一些可能仅支持搜索中心，而另一些可能仅支持地理矩形。

searchTerm : string

此属性存储查询中使用的搜索词。搜索词是一个自由文本字符串。

status : 枚举 [只读]

此属性存储模型的状态。它可以是一个

PlaceSearchModel.Null	尚未执行搜索查询。模型为空。
PlaceSearchModel.Ready	搜索查询已完成，结果可用。
PlaceSearchModel.Loading	正在执行搜索查询。
PlaceSearchModel.Error	在执行先前搜索查询时发生错误。

visibilityScope : 枚举

此属性存储要搜索地点的可见范围。只有具有指定可见性的地点才会出现在搜索结果中。

可见范围可以是以下之一

Place.UnspecifiedVisibility	未指定明确的可见范围，任何可见性的地点都可能包含在搜索结果中。
Place.DeviceVisibility	仅存储在本地设备上的地点将包含在搜索结果中。
Place.PrivateVisibility	仅对当前用户私有的地点包括在搜索结果中。
Place.PublicVisibility	仅对公开的地点包括在搜索结果中。

方法文档

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，则此方法不执行任何操作。