PositionSource QML 类型

PositionSource 类型提供了设备的当前位置。更多...

导入语句	import QtPositioning

所有成员的列表，包括继承的成员

属性

active : bool
name : string
parameters : list<PluginParameter> (自 Qt 定位 5.14)
position : Position
preferredPositioningMethods : enumeration
sourceError : enumeration
supportedPositioningMethods : enumeration
updateInterval : int
valid : bool

方法

Variant backendProperty(string name) (自 Qt 定位 5.14)
bool setBackendProperty(string name, Variant value) (自 Qt 定位 5.14)
start()
stop()
update(int timeout)

详细描述

PositionSource 类型提供了关于用户设备当前位置的信息。该位置作为 Position 类型提供，包含从 GPS 和其他类似系统中可用的所有标准参数，包括经度、纬度、速度和精度细节。

由于不同平台和设备上提供不同的位置来源，这些来源根据其基本类型（卫星、非卫星和所有定位方法）进行分类。当前平台上的可用方法可以在 supportedPositioningMethods 属性中列举。

为了指示哪些方法适合您的应用程序，请设置 preferredPositioningMethods 属性。如果首选的方法不可用，则选择平台的默认位置数据来源。如果没有默认来源可用（因为运行时平台未安装或已禁用），则将 valid 属性设置为 false。

可以使用updateInterval属性来指示您的应用程序希望多久接收一次位置更新。可以使用start()、stop() 和 update()方法来控制PositionSource的操作，以及active属性，当设置该属性时，相当于调用start() 或 stop()。

当PositionSource处于活动状态时，可以通过简单地在绑定中使用position属性（作为另一个项属性的值）或提供onPositionChanged信号处理器的实现来检索位置更新。

使用示例

以下示例显示了一个简单的PositionSource，每秒接收更新并将经纬度打印到控制台。

PositionSource {
    id: src
    updateInterval: 1000
    active: true

    onPositionChanged: {
        var coord = src.position.coordinate;
        console.log("Coordinate:", coord.longitude, coord.latitude);
    }
}

控制操作状态

如上所述，PositionSource提供了两种方法来控制其操作状态

通过使用active 可绑定属性。
通过使用start()和stop()方法。

注意：非常重要的是不要混合这些方法。如果使用可绑定的active属性来控制PositionSource对象，但后来在代码的另一部分调用start() 或 stop，则绑定会断裂，这可能导致例如，UI元素不再连接到任何底层对象。

请考虑以下糟糕的代码示例，其中将active属性绑定到CheckBox状态，并在onClicked信号处理程序中调用stop()破坏了绑定。

Window {
    width: 640
    height: 480
    visible: true

    PositionSource {
        id: posSource
        name: "geoclue2"
        active: cb.checked
    }

    Column {
        anchors.centerIn: parent
        spacing: 20
        CheckBox {
            id: cb
        }
        Button {
            id: btn
            text: "Stop"
            onClicked: {
                posSource.stop()
            }
        }
    }
}

一旦点击停止按钮，就执行stop()，并破坏active属性的绑定。此时CheckBox UI元素不再控制PositionSource对象。

在这种情况下，一个简单的修复方法是总是在从onClicked处理程序更新CheckBox状态。只要CheckBox未被选中，就会通知active属性，并相应地更新PositionSource对象的状态。UI也会处于一致的状态。

Button {
    id: btn
    text: "Stop"
    onClicked: {
        cb.checked = false
    }
}

注意：使用update()请求单个位置更新不会对active属性的绑定产生影响，因此可以一起使用而不会出现任何问题。

另请参阅：QtPositioning::Position、QGeoPositionInfoSource、PluginParameter和Qt可绑定属性。

属性说明

active : bool

此属性指示位置源是否处于活动状态。将此属性设置为false等于调用stop，将此属性设置为true等于调用start。

另请参阅：start、stop和update。

名称 : 字符串

此属性包含当前提供位置信息的插件的唯一内部名称。

设置此属性将使位置源使用特定的定位提供程序。如果在更改名称属性时位置源处于活动状态，它将变为非活动状态。如果指定的定位提供程序无法加载，位置源将变为无效。

更改名称属性可能会导致updateInterval、supportedPositioningMethods和preferredPositioningMethods属性也发生变化。

参数 : 列表<插件参数> [默认值，自 Qt 位置 5.14 以来]

此属性包含插件参数列表。

该属性是在 Qt 位置 5.14 中引入的。

位置 : 位置

此属性包含最后已知的位置数据。它是一个只读属性。

位置类型有不同的位置成员变量，其有效性可以使用适当的有效性函数进行检查（例如，有时更新没有速度或高度数据）。

但是，每当接收到一个positionChanged信号时，至少可以假设position::coordinate::latitude、position::coordinate::longitude和position::timestamp是有效的。

另请参阅：start、stop和update。

首选定位方法 : 枚举

此属性包含当前源的首选定位方法。

位置源.NoPositioningMethods - 没有首选定位方法。
位置源.SatellitePositioningMethods - 应首选基于卫星的定位方法，如GPS。
位置源.NonSatellitePositioningMethods - 应首选非基于卫星的方法。
位置源.AllPositioningMethods - 任何定位方法均可接受。

源错误 : 枚举

此属性包含最后与位置源发生的错误。

位置源.AccessError - 由于应用程序缺少所需的权限，远程定位后端连接设置失败。
位置源.ClosedError - 定位后端关闭了连接，例如在用户切换到关闭位置服务的情况下。一旦重新启用位置服务，常规更新将恢复。
位置源.NoError - 未发生错误。
位置源.UnknownSourceError - 发生未识别的错误。
位置源.UpdateTimeoutError - 无法在指定的时间内检索当前位置，或此位置源确定无法提供进一步的常规更新。

支持的位置方法 : 枚举

该属性包含当前源支持的位置方法。

位置源.NoPositioningMethods - 不支持定位方法（没有源）。
位置源.SatellitePositioningMethods - 支持基于卫星的定位方法，如GPS。
PositionSource.NonSatellitePositioningMethods - 支持非卫星定位方法。
PositionSource.AllPositioningMethods - 支持基于卫星和非卫星的定位方法。

updateInterval : int

此属性保存更新之间的期望间隔（毫秒）。

另请参阅QGeoPositionInfoSource::updateInterval。

valid : bool

如果 PositionSource 对象已获取有效的后端插件以提供数据，则此属性为 true。如果为 false，则 PositionSource 上的其他方法将没有效果。

应用程序应检查此属性以确定在运行时平台上的定位是否可用和已启用，并相应地进行反应。

方法文档

[自 Qt 定位 5.14 以来] Variant backendProperty(string name)

如果存在，返回名为 name 的特定于后端的属性值。否则（包括在未初始化的 PositionSource 上调用时），返回值将无效。支持的后端特定属性列于并描述于 Qt 定位插件#默认插件。

此方法是在 Qt 定位 5.14 中引入的。

另请参阅 backendProperty 和 QGeoPositionInfoSource::setBackendProperty。

[自 Qt 定位 5.14 以来] bool setBackendProperty(string name, Variant value)

将名为 name 的特定于后端的属性设置为 value。在成功时返回 true，否则返回 false，包括在未初始化的 PositionSource 上调用时。支持的后端特定属性列于并描述于 Qt 定位插件#默认插件。

此方法是在 Qt 定位 5.14 中引入的。

另请参阅backendProperty 和 QGeoPositionInfoSource::setBackendProperty。

start()

从位置源请求更新。如果设置了，则使用 updateInterval，否则使用默认间隔。如果没有可用的源，则此方法没有效果。

注意：调用此方法会断开 active 属性的绑定。

另请参阅stop、update 和 active。

stop()

停止从位置源更新。如果没有可用的源或它未处于活动状态，则此方法没有效果。

注意：调用此方法会断开 active 属性的绑定。

另请参阅start、update 和 active。

update(int timeout)

请求从位置源请求单个更新的便捷方法。如果没有可用的源，则此方法没有效果。

如果位置源未处于活动状态，则将在接收更新所需的时间或请求超时之前激活它。请求超时期是特定于源的。

timeout 以毫秒为单位指定。如果 timeout 为零（默认值），则默认为适合该源的合理超时期。

另请参阅start、stop 和 active。