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]

该属性包含一个用于搜索的类别列表。返回的搜索结果将包含至少符合其中一个类别的地点。

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]

无论是否还有一页或多页搜索结果，该属性均成立。

另请参阅 nextPage()。

plugin : Plugin

该属性保存了Plugin ，该对象将用于执行搜索。

previousPagesAvailable : bool [read-only]

无论之前是否有页面搜索结果，该属性均成立。

另请参阅 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)

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