Back to Qt.io
Contact Us Blog Download Qt

PlaceSearchModel QML Type

提供对地点搜索结果的访问。更多

Import Statement: import QtLocation 6.9
Since: QtLocation 5.5

属性

方法

详细说明

PlaceSearchModel 为searchArea 中的地点搜索结果提供了一个模型。可以设置searchTerm 和categories 属性，以将搜索结果限制为符合这些条件的地点。

PlaceSearchModel 返回赞助商搜索结果和有机搜索结果。赞助商搜索结果的sponsored 属性将设置为 true。

该模型返回以下角色的数据：

角色类型描述
类型枚举搜索结果的类型。
标题字符串描述搜索结果的字符串。
图标地点图标表示搜索结果的图标。
距离真实仅当type 角色为PlaceResult 时有效，从searchArea 中心到地点的距离。如果没有指定searchArea ，则距离为 NaN。
地点Place仅当type 角色为PlaceResult 时有效，代表地点的对象。
赞助bool仅当type 角色为PlaceResult 时有效，如果搜索结果是赞助结果，则为 true。

搜索结果类型

type 角色可以有以下值：

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

使用Loader 来创建一个委托，根据搜索结果类型选择不同的Components，通常会很有帮助。

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 个搜索结果[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 属性将始终为空。

另请参阅 Favorites 。


incremental : bool [since QtLocation 5.12]

该属性控制分页对PlaceSearchModel 的影响。如果为 true，调用previousPage 或nextPage 将不会重置模型，而是将新结果追加到模型中。默认为假。

此属性在 QtLocation 5.12 中引入。


limit : int

该属性保留了将返回的条目的数量限制。


nextPagesAvailable : bool [read-only]

该属性显示是否有一个或多个额外的搜索结果页面可用。

另请参阅 nextPage().


plugin : Plugin

该属性包含用于执行搜索的Plugin 。


previousPagesAvailable : bool [read-only]

该属性表示是否有一页或多页搜索结果。

另请参见 previousPage()。


recommendationId : string

该属性包含用于查找类似地点推荐的 placeId。


relevanceHint : enumeration

该属性包含搜索查询中使用的相关性提示。向提供者提供的提示有助于但不决定结果的排序。例如，距离提示可能会使距离较近的地方排名靠前，但这并不一定意味着搜索结果会严格按照距离排序。提供程序可以完全忽略该提示。

SearchResultModel.UnspecifiedHint未向提供程序提供相关性提示。
SearchResultModel.DistanceHint该地点与用户当前位置的距离对用户很重要。该提示只有在使用圆形搜索区域时才有意义。
SearchResultModel.LexicalPlaceNameHint地名的词法排序（按字母升序）对用户很重要。该提示对于基于本地数据存储的提供程序非常有用。

searchArea : variant

该属性包含搜索区域。模型返回的搜索结果将在搜索区域内。

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

对指定搜索区域的支持可能因plugin 后端实现的不同而不同。例如，有些可能只支持搜索中心，而有些可能只支持地理矩形。


searchTerm : string

该属性包含查询中使用的搜索词。搜索词是一个自由格式的文本字符串。


status : enum [read-only]

该属性用于保存模型的状态。它可以是

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

visibilityScope : enum

该属性包含要搜索的地点的可见性范围。只有具有指定可见性的地点才会在搜索结果中返回。

可见性范围可以是

地点.未指定可见性未指定明确的可见性范围，任何可见性的地点都可能成为搜索结果的一部分。
地点.设备可见性只有存储在本地设备上的地点才会成为搜索结果的一部分。
地点私有可见性只有当前用户私人可见的地点才会成为搜索结果的一部分。
地点公共可见性只有公开的地点才会出现在搜索结果中。

方法文档

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.正在加载。如果模型更新成功，状态将设置为PlaceSearchModel.Ready。如果出现错误，状态将设置为PlaceSearchModel.Error，模型将被清除。

如果proposedSearchIndex 没有引用 ProposedSearchResult，则此方法不会执行任何操作。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.