Back to Qt.io
Contact Us Blog Download Qt

GeocodeModel QML Type

GeocodeModel 类型支持与地理信息相关的搜索操作。更多

Import Statement: import QtLocation 6.9
Since: QtLocation 5.5

属性

信号

方法

详细说明

GeocodeModel 类型作为模型/视图分组的一部分，用于将地址或搜索字符串与地理位置相匹配。如何使用或显示生成的地理位置由附加到 GeocodeModel 的任何视图（例如MapItemView 或ListView ）决定。

与Map 和RouteModel 一样，GeocodeModel 运行所需的所有数据都来自服务插件。这些数据包含在plugin 属性中，在 GeocodeModel 执行任何有用的工作之前，必须将其设置为服务插件。

插件设置完成后，query 属性可用于指定要匹配的地址或搜索字符串。如果启用了autoUpdate ，模型将自动更新其输出。否则，可以使用update 方法。默认情况下，autoUpdate 是禁用的。

GeocodeModel 中存储和返回的数据由Location 对象组成，是一个角色名称为 "locationData "的列表。有关其结构和内容的详细信息，请参阅Location 文档。

使用示例

下面的代码段由两部分组成，首先是对象的声明，其次是使用对象的一段程序代码。我们将 geocodeModel 的autoUpdate 属性设置为 false，并在查询设置完成后调用update 。在这种情况下，由于我们在query 中使用的是字符串值，即使启用了autoUpdate ，也只会发生一次更新。但是，如果我们提供一个Address 对象，在设置其属性时可能会无意中触发多个请求。

Plugin {
    id: aPlugin
}

GeocodeModel {
    id: geocodeModel
    plugin: aPlugin
    autoUpdate: false
}
{
    geocodeModel.query = "53 Brandl St, Eight Mile Plains, Australia"
    geocodeModel.update()
}

属性文档

autoUpdate : bool

该属性控制模型是否会根据所附查询的变化自动更新。该属性的默认值为 "false"。

如果将此值设为 "true "并使用地址或coordinate 作为查询，请注意对象属性的任何变化都会触发一个新请求。如果在启用自动更新的同时调整对象的许多属性，就会产生大量无用（随后被丢弃）的请求。


bounds : geoshape

该属性包含用于将结果限制在该区域内的边界区域。如果查询只填写了部分内容，这一点尤其有用，因为服务会尝试对指定数据的所有匹配结果进行（反向）地理编码。

接受的类型有georectangle 和geocircle 。


count : int [read-only]

该属性表示模型当前有多少个地点。除其他用途外，您还可以在通过GeocodeModel::get - 方法访问位置时使用此值。


error : enumeration [read-only]

此只读属性保存地理编码请求的最新错误值。

  • GeocodeModelNoError.- 未发生错误。
  • GeocodeModel.CombinationError - 在合并多个来源的结果时发生错误。
  • GeocodeModel.CommunicationError - 与服务提供商通信时发生错误。
  • GeocodeModel.EngineNotSetError - 模型的插件属性未设置或没有与插件关联的地理编码管理器。
  • GeocodeModel.MissingRequiredParameterError - 未指定必填参数。
  • GeocodeModel.ParseError - 服务提供商的响应格式无法识别。
  • GeocodeModel.UnknownError - 发生的错误不属于任何其他类别。
  • GeocodeModel.UnknownParameterError - 插件无法识别所给参数之一。
  • GeocodeModel.UnsupportedOptionError - 地理编码提供程序不支持请求的操作。当加载的引擎不支持特定地理编码请求（如反向地理编码）时，可能会出现这种情况。

errorString : string [read-only]

此只读属性保存最新地理编码错误的文字表述。如果未发生错误或模型已重置，则返回空字符串。

如果发生的错误没有相关的文字表述，也会返回空字符串。


limit : int

该属性保存结果的最大数量。limit 和offset 值仅适用于自由字符串地理编码（即在搜索查询中使用地址或坐标时不考虑这些值）。

如果 limit 为-1，将返回整个结果集，否则最多返回 limit 结果。limit 和offset 结果可一起用于实现分页。


offset : int

该属性表示不返回结果的第一个 "偏移 "数。limit 和偏移值仅适用于自由字符串地理编码（即在搜索查询中使用地址或坐标时不考虑它们）。

limit 和偏移结果可一起用于实现分页。


plugin : Plugin

该属性包含提供实际地理编码服务的插件。请注意，所有插件并不一定都提供地理编码（例如，可能只提供路由或地图）。

另请参阅 Plugin 。


query : QVariant

该属性保存地理编码请求的数据。该属性接受三种类型的查询，它们决定了要执行的数据和操作类型：

  • 地址 - 地理编码（地址到坐标）
  • coordinate - 反向地理编码（坐标到地址）
  • 字符串 - 地理编码（地址到坐标）

status : enumeration [read-only]

此只读属性保存模型的当前状态。


信号文档

locationsChanged()

该信号在模型中的位置发生变化时发出。

注意： 相应的处理程序是onLocationsChanged 。

另请参阅 count 。


方法文档

void cancel()

取消任何未执行的请求并清除错误。模型状态将设置为GeocodeModel.Null 或GeocodeModel.Ready。


Location get(int index)

返回给定index 的Location 。使用count 属性检查可用位置的数量。位置索引从 0 开始，因此可访问范围为 0......（count - 1）。

如果访问超出范围，将返回 0（空对象）并发出警告。


void reset()

重置模型。所有位置数据都会被清除，任何未执行的请求都会被中止，可能出现的错误也会被清除。模型状态将设置为GeocodeModel.Null


void update()

指示GeocodeModel 更新其数据。当autoUpdate 禁用时，这将非常有用，因为它可以在查询发生更改时强制刷新。


© 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.