QGeoCoordinate Class
QGeoCoordinate 类定义了地球表面上的地理位置。更多内容...
| 头文件： | #include <QGeoCoordinate> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Positioning) target_link_libraries(mytarget PRIVATE Qt6::Positioning) |
| qmake： | QT += positioning |
公共类型
| enum | CoordinateFormat { Degrees, DegreesWithHemisphere, DegreesMinutes, DegreesMinutesWithHemisphere, DegreesMinutesSeconds, DegreesMinutesSecondsWithHemisphere } |
| enum | CoordinateType { InvalidCoordinate, Coordinate2D, Coordinate3D } |
属性
公开职能
| QGeoCoordinate() | |
| QGeoCoordinate(double latitude, double longitude) | |
| QGeoCoordinate(double latitude, double longitude, double altitude) | |
| QGeoCoordinate(const QGeoCoordinate &other) | |
(since 6.2) | QGeoCoordinate(QGeoCoordinate &&other) |
| ~QGeoCoordinate() | |
| double | altitude() const |
| QGeoCoordinate | atDistanceAndAzimuth(qreal distance, qreal azimuth, qreal distanceUp = 0.0) const |
| qreal | azimuthTo(const QGeoCoordinate &other) const |
| qreal | distanceTo(const QGeoCoordinate &other) const |
| bool | isValid() const |
| double | latitude() const |
| double | longitude() const |
| void | setAltitude(double altitude) |
| void | setLatitude(double latitude) |
| void | setLongitude(double longitude) |
(since 6.2) void | swap(QGeoCoordinate &other) |
| QString | toString(QGeoCoordinate::CoordinateFormat format = DegreesMinutesSecondsWithHemisphere) const |
| QGeoCoordinate::CoordinateType | type() const |
(since 6.2) QGeoCoordinate & | operator=(QGeoCoordinate &&other) |
| QGeoCoordinate & | operator=(const QGeoCoordinate &other) |
相关非成员
| bool | operator!=(const QGeoCoordinate &lhs, const QGeoCoordinate &rhs) |
| QDataStream & | operator<<(QDataStream &stream, const QGeoCoordinate &coordinate) |
| bool | operator==(const QGeoCoordinate &lhs, const QGeoCoordinate &rhs) |
| QDataStream & | operator>>(QDataStream &stream, QGeoCoordinate &coordinate) |
详细说明
QGeoCoordinate 由纬度、经度以及（可选的）海拔高度定义。
使用type()来确定一个坐标是二维坐标（仅包含纬度和经度）还是三维坐标（包含纬度、经度和海拔）。使用distanceTo()和azimuthTo()来计算坐标之间的距离和方位角。
坐标值应采用 WGS84 坐标系指定。有关地理术语的更多信息，请参阅关于坐标的这篇文章以及另一篇关于包括 WGS84在内的大地测量系统的文章。
此处的方位角等同于以真北为基准的罗盘方位角。
该类在 QML 中也可通过geoCoordinate 访问。
成员类型文档
enum QGeoCoordinate::CoordinateFormat
定义了toString() 函数的可用格式化选项。
| 常量 | 值 | 描述 |
|---|---|---|
QGeoCoordinate::Degrees | 0 | 返回以十进制度数格式表示的坐标字符串。 |
QGeoCoordinate::DegreesWithHemisphere | 1 | 返回以十进制度数格式表示坐标的字符串，使用“N”、“S”、“E”或“W”来指示坐标所在的半球。 |
QGeoCoordinate::DegreesMinutes | 2 | 返回以度-分格式表示的坐标字符串。 |
QGeoCoordinate::DegreesMinutesWithHemisphere | 3 | 返回以度-分格式表示的坐标字符串，使用“N”、“S”、“E”或“W”来指示坐标所在的半球。 |
QGeoCoordinate::DegreesMinutesSeconds | 4 | 返回以度-分-秒格式表示的坐标字符串。 |
QGeoCoordinate::DegreesMinutesSecondsWithHemisphere | 5 | 返回以度-分-秒格式表示的坐标字符串，使用“N”、“S”、“E”或“W”来指示坐标所在的半球。 |
另请参阅 toString()。
enum QGeoCoordinate::CoordinateType
定义坐标的类型。
| 常量 | 值 | 描述 |
|---|---|---|
QGeoCoordinate::InvalidCoordinate | 0 | 无效坐标。如果坐标的纬度或经度值无效，则该坐标无效。 |
QGeoCoordinate::Coordinate2D | 1 | 纬度和经度值均有效的坐标。 |
QGeoCoordinate::Coordinate3D | 2 | 纬度和经度值均有效，且包含海拔值的坐标。 |
属性文档
altitude : double
该属性存储海拔高度（以米为单位）。
如果未设置海拔高度，则该属性未定义（qQNaN()）。
虽然该属性是在 Qt 5.5 中引入的，但相关的访问器函数自该类的第一个版本起就已存在。
访问函数：
| double | altitude() const |
| void | setAltitude(double altitude) |
[read-only] isValid : bool
该属性表示该地理坐标的有效性。
如果longitude 和latitude 属性已设置为有效值，则该地理坐标即为有效。
虽然该属性是在 Qt 5.5 中引入的，但相关的访问器函数自该类的第一个版本起就已存在。
访问函数：
| bool | isValid() const |
latitude : double
该属性存储以十进制度数表示的纬度。
如果未设置纬度，则该属性未定义（qQNaN()）。正纬度表示北半球，负纬度表示南半球。设置纬度时，新值应采用WGS84坐标系格式。
为了有效，纬度必须在 -90 到 90 之间（包含 90）。
虽然该属性是在 Qt 5.5 中引入的，但相关的访问器函数自该类的第一个版本起就已存在。
访问函数：
| double | latitude() const |
| void | setLatitude(double latitude) |
longitude : double
该属性存储以十进制度数表示的经度。
如果未设置经度，则该属性未定义（qQNaN()）。正经度表示东半球，负经度表示西半球。设置经度时，新值应采用WGS84坐标系格式。
为了有效，经度必须在 -180 到 180 之间（包含 -180 和 180）。
虽然该属性是在 Qt 5.5 中引入的，但相关的访问器函数自该类的第一个版本起便已存在。
访问函数：
| double | longitude() const |
| void | setLongitude(double longitude) |
成员函数文档
QGeoCoordinate::QGeoCoordinate()
创建一个坐标。在调用setLatitude()和setLongitude()之前，该坐标将处于无效状态。
QGeoCoordinate::QGeoCoordinate(double latitude, double longitude)
根据给定的latitude 和longitude 构建一个坐标。
如果纬度不在-90到90（含）之间，或者经度不在-180到180（含）之间，则所有值均未设置，且type()的返回值将为QGeoCoordinate::InvalidCoordinate 。
另请参阅 isValid()。
QGeoCoordinate::QGeoCoordinate(double latitude, double longitude, double altitude)
根据给定的latitude 、longitude 和altitude 构建一个坐标。
如果纬度不在-90到90之间（含-90和90），或者经度不在-180到180之间（含-180和180），则所有值均未设置，且type()将返回QGeoCoordinate::InvalidCoordinate 。
请注意，altitude 表示海拔高度（单位为米）。
另请参阅 isValid()。
QGeoCoordinate::QGeoCoordinate(const QGeoCoordinate &other)
根据other 中的内容构建一个坐标。
[constexpr noexcept default, since 6.2] QGeoCoordinate::QGeoCoordinate(QGeoCoordinate &&other)
通过从other 移动来构建一个坐标。
注意：作为 移动源的 QGeoCoordinate对象 只能被销毁或进行赋值。调用除析构函数或赋值运算符以外的其他函数，其行为未定义。
该函数在 Qt 6.2 中引入。
[noexcept] QGeoCoordinate::~QGeoCoordinate()
删除坐标对象。
double QGeoCoordinate::altitude() const
返回海拔高度（以米为单位，相对海平面）。
如果未设置海拔，则返回值未定义。
注意： 这是 altitude 属性的获取 函数。
另请参阅 setAltitude() 和type()。
[invokable] QGeoCoordinate QGeoCoordinate::atDistanceAndAzimuth(qreal distance, qreal azimuth, qreal distanceUp = 0.0) const
返回从当前坐标沿大圆方向，以azimuth （或方位角）为方向行进distance 米后到达的坐标。此计算基于地球为球体的假设。
海拔高度将增加distanceUp 。
如果该坐标无效，则返回一个无效坐标。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] qreal QGeoCoordinate::azimuthTo(const QGeoCoordinate &other) const
返回从该坐标到由 `other` 指定的坐标之间的方位角（或航向角），单位为度。计算中不考虑高度。
返回的方位角是指从原点沿两坐标之间的大圆线到other 的方位角。此计算基于地球为球体的假设。
如果该坐标的类型或other 的类型为QGeoCoordinate::InvalidCoordinate ，则返回0。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] qreal QGeoCoordinate::distanceTo(const QGeoCoordinate &other) const
返回从该坐标到由other 指定的坐标之间的距离（以米为单位）。计算中不考虑海拔高度。
此计算返回两个坐标之间的大圆距离，并假设地球为球体以进行此计算。
如果该坐标的类型或other 的类型为QGeoCoordinate::InvalidCoordinate ，则返回0。
注意： 可通过元对象系统和QML调用此 函数。参见Q_INVOKABLE 。
bool QGeoCoordinate::isValid() const
如果 `longitude ` 和 `latitude ` 有效，则返回 `true `。
注意： 这是 isValid 属性的获取器 函数。
double QGeoCoordinate::latitude() const
返回纬度，单位为十进制度。如果未设置纬度，则返回值未定义。
正纬度表示北半球，负纬度表示南半球。
注意： 这是 latitude 属性的获取器 函数。
另请参阅 setLatitude() 和type()。
double QGeoCoordinate::longitude() const
返回经度，单位为十进制度。如果未设置经度，则返回值未定义。
正经度表示东半球，负经度表示西半球。
注意： 这是 longitude 属性的获取 函数。
另请参阅 setLongitude() 和type()。
void QGeoCoordinate::setAltitude(double altitude)
将海拔高度（海拔高度，单位：米）设置为altitude 。
注意： 这是属性altitude 的设置 函数。
另请参阅 altitude()。
void QGeoCoordinate::setLatitude(double latitude)
将纬度（以十进制度数表示）设置为latitude 。该值应采用WGS84坐标系。
纬度值必须在 -90 到 90 之间（含 -90 和 90），才视为有效。
注意： 这是属性latitude 的设置 函数。
另请参阅 latitude()。
void QGeoCoordinate::setLongitude(double longitude)
将经度（以十进制度数表示）设置为longitude 。该值应采用WGS84坐标系。
为确保有效，经度必须在-180到180之间（含-180和180）。
注意： 这是属性longitude 的设置 函数。
另请参阅 longitude()。
[noexcept, since 6.2] void QGeoCoordinate::swap(QGeoCoordinate &other)
将该坐标与other 互换。此操作速度极快，且绝不会失败。
该函数在 Qt 6.2 中引入。
[invokable] QString QGeoCoordinate::toString(QGeoCoordinate::CoordinateFormat format = DegreesMinutesSecondsWithHemisphere) const
将该坐标作为字符串返回，格式为指定的format 。
例如，如果该坐标的纬度为 -27.46758，经度为 153.027892，海拔为 28.1，则根据format 的不同，返回的字符串如下：
| format value | 返回的字符串 |
|---|---|
| Degrees | -27.46758°, 153.02789°, 28.1m |
| DegreesWithHemisphere | 南纬 27.46758°，东经 153.02789°，28.1 米 |
| DegreesMinutes | -27° 28.054'，153° 1.673'，28.1m |
| DegreesMinutesWithHemisphere | 南纬27° 28.054'，东经153° 1.673'，28.1米 |
| DegreesMinutesSeconds | -27° 28' 3.2"，153° 1' 40.4"，28.1米 |
| DegreesMinutesSecondsWithHemisphere | 南纬27° 28' 3.2"，东经153° 1' 40.4"，28.1米 |
如果未设置海拔高度，则省略海拔字段。
如果坐标无效，则返回空字符串。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
QGeoCoordinate::CoordinateType QGeoCoordinate::type() const
返回该坐标的类型。
[noexcept, since 6.2] QGeoCoordinate &QGeoCoordinate::operator=(QGeoCoordinate &&other)
该操作将 `other ` 移入并赋值至该坐标，并返回该坐标的引用。
注意： 被移动的QGeoCoordinate 对象 只能被销毁或被赋值。调用除析构函数或赋值运算符以外的其他函数将产生未定义的行为。
该函数于 Qt 6.2 中引入。
QGeoCoordinate &QGeoCoordinate::operator=(const QGeoCoordinate &other)
将other 赋值给该坐标，并返回该坐标的引用。
相关的非成员
bool operator!=(const QGeoCoordinate &lhs, const QGeoCoordinate &rhs)
如果坐标 `lhs ` 的纬度、经度或海拔与坐标 `rhs ` 的纬度、经度或海拔不一致，则返回 `true `；否则返回 `false`。
QDataStream &operator<<(QDataStream &stream, const QGeoCoordinate &coordinate)
将给定的coordinate 写入指定的stream 。
另请参阅 《Qt 数据类型的序列化》。
bool operator==(const QGeoCoordinate &lhs, const QGeoCoordinate &rhs)
如果坐标lhs 的纬度、经度和海拔与坐标rhs 的纬度、经度和海拔相同，则返回true ；否则返回false 。
如果纬度为 +/- 90 度，则经度将被忽略。
QDataStream &operator>>(QDataStream &stream, QGeoCoordinate &coordinate)
从指定的stream 中读取一个坐标，并将其写入给定的coordinate 中。
另请参阅 《Qt 数据类型的序列化》。
© 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.
