Qt Location 开放式街道地图插件

概述

该地理服务插件允许应用程序使用Qt Location API 访问基于开放街道地图位置的服务。

数据、图像和地图信息由ThunderForest、OpenStreetMap和贡献者提供。数据根据开放数据库许可证提供。

可使用插件密钥 "osm "加载开放街道地图地理服务插件。

注：标准地图类型依赖于（部分）免费数据提供者。我们会尽量为评估和开发目的选择有用的数据提供商，但您有责任选择适合您生产需要的数据提供商。强烈建议仔细阅读并遵守各供应商的服务条款。OpenStreetMap 维基百科中提供了替代数据提供商的列表。本插件提供的可用地图类型可能会根据每种类型的可行公开提供商的实际可用性进行更改（或删除），恕不另行通知。这也意味着可以使用通过 HTTPS 提供磁贴的提供商。这与在 Android 等平台上使用 OSM 插件有关，因为 Qt 默认不支持 SSL。为了防止这些变化，要么使用不同的地理服务插件，要么将插件参数osm.mapping.providersrepository.address 设为用户指定的存储库，以便完全控制为每种地图类型选择提供商。自 Qt 5.9.6 起，用于地理编码和地点的默认 nomatim 端点也改为只支持 HTTPS。

参数

可选参数

下表列出了可传递给 Open Street Map 插件的可选参数。

注意： 自 Qt 5.5 起，以下所有参数必须以osm 作为前缀。以前的版本不需要前缀。

参数	说明
osm.geocoding.host	向地理编码服务器发出网络请求时设置的 URL 字符串。该参数应设置为具有正确 OSM API 的有效服务器网址。如果未指定，将使用默认网址。注： API 文档可在Project OSM Nominatim 获取。
osm.geocoding.debug_query	指示插件在地理编码回复中注入到 nomatim 的查询 url，用于调试。
osm.geocoding.include_extended_data	指示插件在返回的位置对象中包含 Nominatim 特有的信息（如几何形状和类别），作为扩展属性（extendedAttributes）公开。
osm.mapping.cache.directory	映射磁贴缓存目录的绝对路径，用作网络磁盘缓存。默认的缓存位置是QStandardPaths::writableLocation() 所返回位置中的`QtLocation/osm` 子目录，调用时以QStandardPaths::GenericCacheLocation 作为参数。在没有共享缓存概念的系统中，将使用特定于应用程序的QStandardPaths::CacheLocation 代替。
osm.mapping.cache.disk.cost_strategy	用于在磁盘上缓存映射图块的成本策略。有效值为bytesize和unitary。使用bytesize 时，相关大小参数(osm.mapping.cache.disk.size) 将被解释为字节。使用unitary 时，它们将被解释为磁贴数量。该参数的默认值是bytesize。
osm.mapping.cache.disk.size	映射磁贴的磁盘缓存大小。使用bytesize作为代价策略时，缓存的默认大小为 50 MiB；使用unitary作为代价策略时，缓存的默认大小为 1000 个磁贴。
osm.mapping.cache.memory.cost_strategy	用于在内存中缓存映射图块的代价策略。有效值是bytesize和unitary。使用bytesize 时，相关大小参数(osm.mapping.cache.memory.size) 将被解释为字节。使用unitary 时，它们将被解释为图块数。该参数的默认值是bytesize。
osm.mapping.cache.memory.size	映射磁贴的内存缓存大小。使用bytesize作为代价策略时，缓存的默认大小为 3 MiB；使用unitary作为代价策略时，缓存的默认大小为 100 个贴图。
osm.mapping.cache.texture.cost_strategy	用于在内存中缓存解压缩贴图的代价策略。有效值是bytesize和unitary。使用bytesize 时，相关的大小参数（osm.mapping.cache.texture.size）将被解释为字节。使用unitary 时，它们将被解释为图块数。该参数的默认值是bytesize。
osm.mapping.cache.texture.size	贴图瓦片的纹理缓存大小。当使用bytesize作为代价策略时，缓存的默认大小为 6 MiB；当使用unitary作为代价策略时，缓存的默认大小为 30 个贴图。请注意，纹理缓存有一个硬性最小值，它取决于地图视口的大小（它必须包含足够的数据来显示当前显示屏上可见的贴图）。该值是除最小值之外要使用的缓存量。
osm.mapping.custom.dataacopyright	自定义数据版权字符串，用于通过 urlprefix 参数设置Map::activeMapType 至MapType.CustomMap 。该版权仅在使用上述自定义地图时使用。如果为空，将不显示自定义地图的数据版权。
osm.mapping.custom.host	自定义磁贴服务器的 url 字符串。此参数应设置为提供正确 OSM API 的有效服务器URL。后缀"%z/%x/%y.png "将被添加到网址中。自 6.5 版起，如果网址以".png "结尾，则不会添加后缀。如果服务器需要 apikey，则必须将其添加到 url 字符串中。要使用该服务器，应将Map 的Map::activeMapType 参数设置为支持的映射类型，其类型为MapType.CustomMap 。只有设置了该插件参数，该地图类型才可用，在这种情况下，它总是Map::supportedMapTypes[supportedMapTypes.length-1]。注意：将 mapping.custom.host 参数设置为新服务器后，地图磁贴缓存将对旧的 custommap 风格无效。
osm.mapping.custom.mapcopyright	通过 urlprefix 参数将Map::activeMapType 设置为MapType.CustomMap 时使用的自定义地图版权字符串。该版权仅在使用上述自定义地图时使用。如果为空，自定义地图将不显示地图版权。
osm.mapping.highdpi_tiles	是否请求高分辨率瓷砖。有效值为true和false。默认值为false。请注意，并非所有地图类型都有高分辨率。如果目前没有高 dpi 地图类型可用，将此参数设置为 true 甚至可能没有任何效果。高分辨率磁贴的提供商信息文件命名为`street-hires`,`satellite-hires`,`cycle-hires`,`transit-hires`,`night-transit-hires`,`terrain-hires` 和`hiking-hires` 。这些文件从低 dpi 对应文件的相同位置获取。
osm.mapping.offline.directory	包含用作离线存储的地图贴图的目录的绝对路径。如果指定了该目录，它将与网络磁盘缓存一起工作，但不会自动插入、删除或更新磁贴。磁贴的格式与网络磁盘缓存相同。该属性没有默认值，如果不设置该属性，则不会索引任何目录，只会使用网络磁盘缓存来减少网络使用或作为当前缓存磁贴的离线存储。
osm.mapping.prefetching_style	该参数用于提示引擎如何执行磁贴预取。默认值`TwoNeighbourLayers` 可使引擎预取当前磁贴图层上一层和下一层的磁贴，从而在放大或缩小当前缩放级别时提供就绪的磁贴。`OneNeighbourLayer` 只预取最接近当前缩放级别的图层。最后，`NoPrefetching` 允许禁用预取，因此只有可见的磁贴才会被获取。请注意，根据活动地图类型，此提示可能会被忽略。
osm.mapping.providersrepository.address	OpenStreetMap 插件会从远程资源库检索提供者信息。这样做是为了避免默认情况下使用硬编码服务器，因为这些服务器可能无法使用。默认情况下，该信息是从maps-redirect.qt.io 获取的。设置此参数可将提供程序存储库地址更改为用户指定的地址，其中必须包含`street`,`satellite`,`cycle`,`transit`,`night-transit`,`terrain` 和`hiking` 文件，每个文件都必须包含有效的提供程序信息。
osm.mapping.providersrepository.disabled	默认情况下，OpenStreetMap 插件从远程资源库检索提供商信息，以避免因硬编码服务不可用而导致服务丢失。不过，该插件仍包含后备硬编码提供商数据，以防提供商存储库无法访问。将该参数设置为"true"后，插件将只使用硬编码 url，从而防止插件从远程资源库获取提供程序数据。
osm.places.debug_query	将此参数设置为 "true"，可在每个结果中添加名为 "requestUrl "的扩展属性，其中包含查询所用的 url。默认为false。
osm.places.host	向地点服务器发出网络请求时设置的 URL 字符串。该参数应设置为具有正确 OSM API 的有效服务器网址。如果未指定，将使用默认网址。注： API 文档可在Project OSM Nominatim 获取。
osm.places.page_size	页面中的结果数量。注意该值可能会在服务器端被箝制。标准 Nominatim 实例的最大值通常为 50。
osm.routing.apiversion	定义（自定义）OSRM 服务器 api 版本的字符串。有效值为v4和v5，默认为v5。只有设置了`osm.routing.host` 且是 OSRM v4 服务器时，才应设置此参数。
osm.routing.host	向路由服务器发出网络请求时设置的 URL 字符串。该参数应设置为具有正确 OSRM API 的有效服务器网址。如果未指定，将使用默认URL。注： API 文档和源代码可从Project OSRM 获取。
osm.useragent	网络请求时设置的用户代理字符串。该参数应设置为能唯一标识应用程序的值。请注意，提供商可能会阻止不设置此参数的应用程序，而将其留给库存插件用户代理（例如，用于地理编码的Nominatim）。

参数使用示例

下面的示例展示了如何创建 OSM 插件实例，并为用户代理提供参数，必要时还会为磁贴提供商提供自定义服务器网址和相应的版权信息。此外，还可以选择另一个路由服务器，而不是公共的 osrm 服务器。

QML

Plugin {
    name: "osm"
    PluginParameter { name: "osm.useragent"; value: "My great Qt OSM application" }
    PluginParameter { name: "osm.mapping.host"; value: "http://osm.tile.server.address/" }
    PluginParameter { name: "osm.mapping.copyright"; value: "All mine" }
    PluginParameter { name: "osm.routing.host"; value: "http://osrm.server.address/viaroute" }
    PluginParameter { name: "osm.geocoding.host"; value: "http://geocoding.server.address" }
}

其他特定插件信息

磁贴缓存

磁贴缓存在QStandardPaths::writableLocation (QStandardPaths::GenericCacheLocation) 的QtLocation/osm 目录中。在没有共享缓存概念的系统中，会使用特定于应用程序的QStandardPaths::CacheLocation 代替。

GeoServices 项目叠加插件

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