PositionSource QML Type

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

Import Statement: import QtPositioning

所有成员（包括继承成员）的列表

属性

active : bool
name : string
parameters : list<PluginParameter> (since QtPositioning 5.14)
position : Position
preferredPositioningMethods : enumeration
sourceError : enumeration
supportedPositioningMethods : enumeration
updateInterval : int
valid : bool

方法

Variant backendProperty(string name) (since Qt Positioning 5.14)
bool setBackendProperty(string name, Variant value) (since Qt Positioning 5.14)
start()
stop()
update(int timeout)

详细说明

PositionSource 类型提供有关用户设备当前位置的信息。位置信息以Position 类型提供，其中包含 GPS 和其他类似系统通常提供的所有标准参数，包括经度、纬度、速度和精度详情。

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

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

updateInterval 属性可用于指示应用程序希望接收位置更新的频率。start()、stop() 和update() 方法以及active 属性可用于控制 PositionSource 的运行，设置属性时，相当于调用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 属性与复选框状态绑定，在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按钮，stop() 将被执行，而active 属性的绑定将被破坏。此时，CheckBox UI 元素不再控制 PositionSource 对象。

在这种情况下，直接的解决方法是通过onClicked 处理程序更新 CheckBox 状态。一旦取消选中 CheckBox，active 属性就会收到通知，PositionSource 对象的状态也会相应更新。用户界面也将处于一致的状态。

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

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

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

属性文档

active : bool

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

另请参阅 start,stop, 和update 。

name : string

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

设置该属性会使PositionSource 使用特定的定位提供程序。如果在更改 name 属性时，PositionSource 处于活动状态，则会变成非活动状态。如果无法加载指定的定位提供程序，位置源将失效。

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

parameters : list<PluginParameter> [default, since QtPositioning 5.14]

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

该属性在 QtPositioning 5.14 中引入。

position : Position

该属性保存最后已知的位置数据。这是一个只读属性。

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

不过，只要收到positionChanged 信号，至少可以认为 position::coordinate::latitude、position::coordinate::longitude 和 position::timestamp 是有效的。

另请参阅 start 、stop 和update 。

preferredPositioningMethods : enumeration

此属性保存当前来源的首选定位方法。

PositionSource.NoPositioningMethods - 无首选定位方法。
PositionSource.SatellitePositioningMethods - 首选基于卫星的定位方法，如 GPS。
PositionSource.NonSatellitePositioningMethods - 首选非卫星定位方法。
PositionSource.AllPositioningMethods - 可接受任何定位方法。

sourceError : enumeration

.AccessError（访问错误）- 该属性包含PositionSource 上一次出现的错误。

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

supportedPositioningMethods : enumeration

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

PositionSource.NoPositioningMethods - 不支持定位方法（无信号源）。
PositionSource.SatellitePositioningMethods - 支持基于卫星的定位方法，如 GPS。
PositionSource.NonSatellitePositioningMethods - 支持非卫星定位方法。
PositionSource.AllPositioningMethods - 同时支持基于卫星和非卫星的定位方法。

updateInterval : int

该属性保存所需的更新间隔（毫秒）。

另请参阅 QGeoPositionInfoSource::updateInterval().

valid : bool

如果PositionSource 对象已获得有效的后端插件来提供数据，则此属性为 true。如果为 false，PositionSource 上的其他方法将不起作用。

应用程序应检查此属性，以确定运行时平台上的定位功能是否可用和启用，并做出相应的反应。

方法文档

[since Qt Positioning 5.14] Variant backendProperty(string name)

如果存在，则返回名为name 的后端特定属性的值。否则（包括在未初始化的PositionSource 上调用），返回值将无效。支持的后端特定属性在Qt Positioning plugins#Default plugins 中列出并描述。

该方法在Qt Positioning 5.14 中引入。

另请参阅 backendProperty 和QGeoPositionInfoSource::setBackendProperty 。

[since Qt Positioning 5.14] bool setBackendProperty(string name, Variant value)

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

该方法在Qt Positioning 5.14 中引入。

另请参阅 backendProperty 和QGeoPositionInfoSource::setBackendProperty 。

start()

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

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

另请参阅 stop,update, 和active 。

stop()

停止更新位置源。如果没有可用的源或源未激活，此方法将不起作用。

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

另请参阅 start,update, 和active 。

update(int timeout)

从位置源请求单次更新的便捷方法。如果没有可用的位置源，该方法将不起作用。

如果位置源未激活，则在接收更新或请求超时之前，位置源将一直处于激活状态。请求超时的时间段取决于源的具体情况。

timeout 的单位是毫秒。如果timeout 为零（默认值），则默认为适合源的合理超时时间。

另请参阅 start,stop, 和active 。

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