变更说明Qt Positioning

Qt 6 的变更，是出于让该框架更高效、更易于使用的有意识努力。

我们力求在每次发布中保持所有公开 API 的二进制和源代码兼容性。但在努力使 Qt 成为更优秀的框架的过程中，某些变更在所难免。

在本主题中，我们将总结Qt Positioning 中的这些变更，并提供相应的处理指南。

破坏性公共 API 变更

本节包含关于破坏源代码兼容性的 API 更改的信息。

重命名 QGeoPolygon::path()

QGeoPolygon::path() 和QGeoPolygon::setPath() 方法分别重命名为QGeoPolygon::perimeter() 和QGeoPolygon::setPerimeter()。在 QML 方面，QGeoPolygon::perimeter 属性可照常使用，无需任何更改。

使用QGeoShape 作为QGeoLocation 的边界区域

QGeoLocation 类及其QML对应的Location 已更新，现使用QGeoShape 代替QGeoRectangle 来表示边界区域。

C++

QGeoLocation::boundingBox() 和QGeoLocation::setBoundingBox() 分别被QGeoLocation::boundingShape() 和QGeoLocation::setBoundingShape() 所取代。现在使用QGeoShape 对象作为底层数据存储。

QML

QGeoLocation::boundingBox 属性已被QGeoLocation::boundingShape 取代。该属性自QtPositioning 6.2起可用，因此请务必更新QML文件中的导入版本。

import QtPositioning 6.2

移除 QGeoShape::extendShape()

QGeoShape::extendShape() 方法在 Qt 5.9 中已弃用，并在 Qt 6 中最终被移除。如果需要为这些类使用此功能，请使用QGeoRectangle::extendRectangle() 和QGeoCircle::extendCircle()。

将信号 error 重命名为 errorOccurred

在 Qt 5 中，多个Qt Positioning 类都具有error() 信号，这与error() 方法存在冲突。在 Qt 6 中，我们将这些信号重命名为errorOccurred() 。具体而言：

• QGeoAreaMonitorSource::error() 已重命名为QGeoAreaMonitorSource::errorOccurred()。
• QGeoPositionInfoSource::error() 已重命名为QGeoPositionInfoSource::errorOccurred()。
• QGeoSatelliteInfoSource::error() 已重命名为QGeoSatelliteInfoSource::errorOccurred()。

移除更新超时信号

在 Qt 5 中，QGeoPositionInfoSource::updateTimeout() 和QGeoSatelliteInfoSource::requestTimeout() 信号用于通知在指定超时时间内无法获取当前位置或卫星信息的情况。这些信号在 Qt 6 中已被移除。取而代之的是带有新错误类型的errorOccurred() 信号。具体而言：

• QGeoPositionInfoSource 使用errorOccurred() 信号并附带新的QGeoPositionInfoSource::UpdateTimeoutError 错误代码。
• QGeoSatelliteInfoSource 使用带有新错误代码QGeoSatelliteInfoSource::UpdateTimeoutError 的errorOccurred() 信号。

PositionSource QML 对象也进行了相同的更改。已移除PositionSource::updateTimeout() 信号。取而代之的是带有PositionSource.UpdateTimeoutError 的PositionSource::sourceError 属性。

重新设计 NMEA 支持

在 Qt 5 中，我们有一个serialnmea定位插件，以及PositionSource 对象中的nmeaSource 属性。

该插件通过串口提供对 NMEA 数据流的访问，而 QML 对象则负责从 TCP 套接字或本地文件读取 NMEA 数据流。

在 Qt 6 中，我们将所有这些功能整合到了该插件中，该插件现已更名为nmea。它现在能够处理所有三种 NMEA 数据源：串行端口、TCP 套接字和本地文件。更多详细信息请参阅插件说明。

PositionSource 对象的nmeaSource 属性现已移除。

其他 API 变更

本节包含不破坏源代码兼容性的 API 改进。尽管如此，这些改进可能会对应用程序逻辑产生影响，因此了解这些内容仍然很有帮助。

正确重置错误

在 Qt 5 中，QGeoAreaMonitorSource 、QGeoPositionInfoSource 和QGeoSatelliteInfoSource 类的错误从未被重置。这种行为并不合理，因为在这些类或其子类上调用startUpdates() 、startMonitoring() 或requestUpdates() 实际上意味着开始一个新的工作会话，这意味着我们不应关注之前的错误。从 Qt 6 开始，一旦调用上述方法之一，我们会将错误重置为NoError 。

添加QGeoAddress::streetNumber

QGeoAddress 类新增了streetNumber 属性，该属性存储门牌号、楼宇名称或其他可用于区分不同地址的信息。可通过streetNumber()和setStreetNumber()在C++代码中访问此属性。

QGeoAddress::street 现在仅包含街道名称。

Address 的 QML 对应项也是如此。现在，Address::street 属性仅用于街道名称，而Address::streetNumber 属性用于其他重要的地址详细信息。

为PositionSource::update()

timeout 以毫秒为单位指定。如果timeout 为零（默认值），则会根据数据源情况默认设置一个合理的超时时间。

重构QGeoSatelliteInfo 、QGeoPositionInfo 和QGeoAreaMonitorInfo 类

这些类现在在其实现中使用了 `QExplicitlySharedDataPointer `。这意味着这些类实现了“写时复制”（copy-on-write）机制。这使得它们的复制成本很低，因此可以按值传递。

另一项改进是增加了对高效移动操作的支持。

Qt Positioning 插件实现的变更

本节介绍了插件接口的变更信息。

在 Qt 5 中，我们曾有两个版本的插件接口：

• QGeoPositionInfoSourceFactory 该版本提供了基本功能。
• QGeoPositionInfoSourceFactoryV2 该版本则扩展了基类，允许为创建的对象提供自定义参数。

在 Qt 6 中，我们将这两种实现合并为一种，仅保留了 `QGeoPositionInfoSourceFactory ` 类。该类的方法现在支持传递自定义参数。

以下是插件类声明的示例：

class MyPlugin : public QObject, public QGeoPositionInfoSourceFactory
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.qt.position.sourcefactory/6.0"
                      FILE "plugin.json")
    Q_INTERFACES(QGeoPositionInfoSourceFactory)

public:
    QGeoPositionInfoSource *positionInfoSource(QObject *parent, const QVariantMap &parameters) override;
    QGeoSatelliteInfoSource *satelliteInfoSource(QObject *parent, const QVariantMap &parameters) override;
    QGeoAreaMonitorSource *areaMonitor(QObject *parent, const QVariantMap &parameters) override;
};