Qt Location OpenStreetMap 插件
概述
此地理服务插件允许应用程序通过Qt Location API访问OpenStreetMap的基于位置的服务。
数据、影像和地图信息由ThunderForest、OpenStreetMap及其贡献者提供。这些数据遵循开放数据库许可协议。
可通过插件键“osm”加载 OpenStreetMap 地理服务插件。
注意： 标准地图类型 依赖于（部分）免费的数据提供商。 我们力求提供适用于评估和开发目的的选项，但在生产环境中选择符合您需求的数据提供商是您的责任。强烈建议您仔细阅读并遵守各提供商的服务条款。OpenStreetMap维基中提供了替代数据提供商的列表。 该插件提供的可用地图类型可能会根据每种类型实际可用的公开访问提供商情况而发生变更（或被移除），恕不另行通知。这也意味着可能会使用通过 HTTPS 提供地图瓦片的提供商。当在 Android 等平台上使用 OSM 插件时，这一点尤为重要，因为这些平台上的 Qt 默认不支持 SSL。 若要避免这些变化，应使用其他地理服务插件，或将插件参数osm.mapping.providersrepository.address设置为用户指定的存储库，以便完全控制每种地图类型所使用的提供商。 自 Qt 5.9.6 起，用于地理编码和地点识别的默认 nominatim 端点也已更改为仅支持 HTTPS。
参数
可选参数
下表列出了可传递给 Open Street Map 插件的可选参数。
注意：自 Qt 5.5起， 以下所有参数都必须以osm 为前缀。以前的版本不需要前缀。
| 参数 | 描述 |
|---|---|
| osm.geocoding.host | 向地理编码服务器发起网络请求时设置的 URL 字符串。该参数应设置为包含正确 OSM API 的有效服务器 URL。若未指定，将使用默认URL。 注意： API 文档可在Project OSM Nominatim 上查阅。 |
| osm.geocoding.debug_query | 指示插件将发送到Nominatim的查询URL注入到地理编码响应中，用于调试目的。 |
| osm.geocoding.include_extended_data | 指示插件将 Nominatim 特有的信息（例如几何形状和类）包含在返回的 Location 对象中，并作为 extendedAttributes 暴露出来。 |
| osm.mapping.cache.directory | 用作网络磁盘缓存的地图图块缓存目录的绝对路径。 缓存的默认位置是QStandardPaths::writableLocation() 返回的路径下的 |
| 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 时，相关的 size 参数（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.datacopyright | 当通过 urlprefix 参数将Map::activeMapType 设置为MapType.CustomMap 时，将使用自定义数据版权声明字符串。该版权声明仅在使用上述 CustomMap 时生效。若为空，则自定义地图上不会显示任何数据版权声明。 |
| osm.mapping.custom.host | 自定义瓦片服务器的 URL 字符串。该参数应设置为提供正确 OSM API 的有效服务器 URL。URL 后缀“%z/%x/%y.png”将被添加到 URL 中。自 6.5 版本起，如果 URL 以“.png”结尾，则不会添加该后缀。 如果服务器需要 API 密钥，则必须将其添加到 URL 字符串中。要使用该服务器，应将Map 中的Map::activeMapType 参数设置为支持的地图类型，其类型为MapType.CustomMap 。此地图类型仅在设置了此插件参数时才可用，此时其值始终为Map::supportedMapTypes[supportedMapTypes.length - 1]。 注意：将 mapping.custom.host 参数设置为 新服务器后，旧版 custommap 样式的地图图块缓存将无法使用。 |
| osm.mapping.custom.mapcopyright | 当通过 urlprefix 参数将Map::activeMapType 设置为MapType.CustomMap 时，将使用自定义地图版权声明字符串。此版权声明仅在使用上述 CustomMap 时生效。若为空，则自定义地图上不会显示任何地图版权声明。 |
| osm.mapping.highdpi_tiles | 是否请求高 dpi 图块。有效值为true和false。默认值为false。 请注意，并非所有地图类型都提供高 dpi 版本。如果当前没有地图类型提供高 dpi 版本，将此参数设置为 true 甚至可能没有任何效果。高 dpi 图块的提供商信息文件命名为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 的有效服务器 URL。若未指定，将使用默认URL。 注意： 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。若未指定，将使用默认URL。 注意： API 文档和源代码可在Project OSRM 上获取。 |
| osm.useragent | 进行网络请求时设置的用户代理字符串。该参数应设置为能唯一标识应用程序的值。请注意，服务提供商可能会屏蔽未设置此参数的应用程序，使其保持为默认插件的用户代理（例如，Nominatim用于地理编码） |
参数使用示例
以下示例演示了如何创建一个 OSM 插件实例，其中提供了 useragent 参数，并在必要时指定自定义服务器 URL 以及瓦片提供商的相应版权信息。此外，还可以选择除公共 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 。
© 2026 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.
