PositionSource QML Type

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

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

属性

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

方法

• var backendProperty(string name) (since Qt Positioning 5.14)
• bool setBackendProperty(string name, var value) (since Qt Positioning 5.14)
• void start()
• void stop()
• void 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 属性绑定到了 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 ` 处理程序中更新复选框的状态。一旦复选框被取消选中，active 属性将收到通知，PositionSource 对象的状态也会相应更新。同时，用户界面也将保持一致的状态。

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

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

属性文档

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

该属性存储了当前源的首选定位方法。

sourceError : enumeration

该属性存储了PositionSource 最近发生的错误。

supportedPositioningMethods : enumeration

该属性存储了当前源支持的定位方法。

updateInterval : int

该属性存储两次更新之间所需的间隔（以毫秒为单位）。

另请参阅 QGeoPositionInfoSource::updateInterval()。

valid : bool

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

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

方法文档

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

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

该方法自Qt Positioning 5.14 起引入。

另请参阅 setBackendProperty 和QGeoPositionInfoSource::setBackendProperty 。

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

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

该方法在Qt Positioning 5.14 中引入。

另请参阅 backendProperty 和QGeoPositionInfoSource::setBackendProperty 。

void start()

向位置来源请求更新。如果已设置updateInterval ，则使用该间隔；否则使用默认间隔。如果没有可用来源，此方法将不起作用。

另请参阅 stop()、update() 以及active 。

void stop()

停止从位置源获取更新。如果没有可用源或源处于非活动状态，此方法将无效果。

另请参阅 start()、update() 和active 。

void update(int timeout)

一种用于向位置源请求单次更新的便捷方法。如果没有可用源，此方法将不起作用。

如果位置源处于非活动状态，系统将将其激活，直至收到更新或请求超时为止。请求超时时间因源而异。

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

另请参阅 start()、stop() 以及active 。