另见 翻译。
版权 © 2024 万维网联盟。 W3C® 免责声明, 商标 和 许可文档规则适用。
地理定位提供与托管设备相关的地理位置信息的访问。
本节描述了本文档发布时的状态。当前的 W3C 发布的列表以及此技术报告的最新修订可以在 W3C 技术报告索引 中找到, 地址是 https://www.w3.org/TR/。
自从该规范在2022年9月1日成为 W3C 推荐标准以来,以下实质性的补充和/或修正已被提议:
更详细的变更列表可以在 D. 变更日志 部分找到。文档的审阅者可以通过其独特的样式识别候选的补充和/或修正。
本文档由 设备和传感器工作组 和 Web应用工作组 发布为推荐标准,采用 推荐流程。它包含了 候选修订, 引入了自上次推荐以来的实质性更改和新特性。
W3C 推荐将此规范广泛部署为 Web 标准。
W3C 推荐标准是一种规范,经过广泛的共识构建后,由 W3C 及其成员支持,并且 工作组成员承诺为实现提供 免版税许可。 未来对该推荐的更新可能会包含 新特性。
候选补充内容在文档中标记。
候选修正内容在文档中标记。
本文档是由 W3C 专利 政策下运作的各小组制作的。 W3C 维护有一个 关于任何专利披露的公开列表 (设备和传感器工作组),以及一个 关于任何专利披露的公开列表 (Web应用工作组) ,这些披露与每个小组的交付物有关;这些页面还包含 披露专利的说明。如果某个个人知道某个专利,并认为该专利包含 必要的专利声明 ,则必须根据 W3C 专利政策第6条进行披露。
本文档受 2023年11月3日的 W3C 过程文件约束。
本节为非规范性内容。
地理定位 定义了一个与仅主机设备相关的位置 信息的高级接口。常见的位置来源包括全球定位 系统(GPS)和从网络信号推断的位置,例如 IP 地址、RFID、WiFi 和蓝牙 MAC 地址,以及 GSM/CDMA 蜂窝 ID,还有用户输入。该 API 本身与底层位置 信息源无关,并不保证返回设备的实际位置。
如果最终用户 授予权限, 地理定位:
GeolocationPosition
接口。
getCurrentPosition
()
方法进行“单次”位置更新,并能够通过
watchPosition
()
方法接收主机设备位置显著变化时的更新。
PositionOptions
的 maximumAge
,
允许应用程序请求一个缓存位置,其年龄不大于指定的值(仅缓存最后一个位置)。
GeolocationPositionError
,用于
处理在 获取位置 时发生的错误。
enableHighAccuracy
,
支持请求“高精度”位置数据,但该请求可以被用户代理忽略。
本节为非规范性内容。
本规范仅提供一个脚本 API 用于检索与主机设备相关的地理位置 信息。地理位置数据以世界大地坐标系 [WGS84] 表示。它不包括 提供任何形式的标记语言,也不包括 定义一个新的 URL 方案来构建识别地理位置的 URL。
本节非规范性。
该API旨在支持“单次”位置请求和重复的位置更新。以下示例展示了常见的使用案例。
本节非规范性。
请求用户的当前位置。如果用户允许,您将获得一个位置对象。
本节非规范性。
请求能够监视用户的当前位置。如果用户允许,您将获得用户位置的持续更新。
本节非规范性。
通过调用 clearWatch
()
方法来停止监视位置变化。
本节非规范性。
当发生错误时,watchPosition
()
或 getCurrentPosition
()
方法的第二个参数会返回一个 GeolocationPositionError
错误对象,您可以根据它来找出可能出错的原因。
本节非规范性。
默认情况下,API 总是尝试返回缓存的位置信息,只要它之前获取过位置。在这个示例中,我们接受一个位置,其年龄不超过 10 分钟。如果用户代理没有足够新的缓存位置对象,它将自动获取一个新的位置。
本节非规范性。
如果你需要及时获取位置信息,你可以使用 PositionOptions
的 timeout
成员来限制你愿意等待的时间,以 获取位置。
本节非规范性。
默认允许列表中的
'self'
允许 API 在同源嵌套框架中使用,但禁止第三方内容使用该 API。
可以通过向
allow
="geolocation"
属性添加到
iframe
元素来选择性启用第三方使用:
另外,可以通过指定 HTTP 响应头来在第一方上下文中禁用 API:
请参见 权限策略 了解更多有关
Permissions-Policy
HTTP 头的详细信息。
本节非规范性。
本规范中定义的 API 用于检索托管设备的地理位置。在几乎所有情况下,这些信息也揭示了设备用户的位置,从而可能侵犯用户的隐私。
本节非规范性。
地理位置 是一种 强大的功能,在与 Web 应用程序共享任何位置数据之前,必须
从最终用户处获得 明确的权限。这一要求通过
检查权限 步骤来规范性地强制执行,这些步骤是
getCurrentPosition
()
和
watchPosition
()
方法所依赖的。
终端用户通常通过用户界面给予 明确许可,该界面通常提供一系列的权限 生命周期,供终端用户选择。
权限的 生命周期
在不同的用户代理之间有所不同,但通常是基于时间的(例如,“一天”),或者直到浏览器关闭,用户甚至可能被赋予永久授权的选择。权限的 生命周期 决定了用户代理在多长时间内 授予 权限,在该时间段后,权限将自动恢复为默认的 权限状态,并在后续使用时提示终端用户重新做出选择。
尽管不同用户代理的权限 生命周期 细节有所不同,但本规范建议默认情况下,用户代理应将生命周期限制为一个浏览会话(参见 3.4 检查使用 API 的权限,以获得规范性要求)。
本节非规范性。
本节适用于“接收者”,通常指使用 地理位置 的开发者。尽管用户代理或本规范无法强制执行这些要求,但开发者需要仔细阅读本节并尽力遵守以下建议。开发者还需要意识到,他们所在司法辖区可能有关于用户位置数据使用和访问的隐私法。
接收者应该仅在必要时请求位置信息,并且仅将该信息用于为其提供信息的任务。接收者应在任务完成后销毁位置信息,除非用户明确允许保留该信息。接收者还需要采取措施保护这些信息免受未经授权的访问。如果位置信息被存储,用户应当有权更新和删除该信息。
位置数据的接收者应避免在未经用户明确同意的情况下转发位置数据。转发时应谨慎,并建议使用加密。
接收者应明确且显著地披露他们正在收集位置信息、收集的目的、数据的保留时间、数据的安全性、数据是否被共享以及如何共享、用户如何访问、更新和删除数据,以及用户关于数据的任何其他选择。这些披露需要包括对上述指南的任何例外的解释。
本节非规范性。
实施者应考虑以下可能会对用户隐私产生负面影响的方面:在某些情况下,用户可能会无意中授权用户代理向网站公开他们的位置。在其他情况下,托管在某个 URL 上的内容可能会发生变化,导致先前授予的位置权限不再适用,或者用户可能改变主意。
预测或防止这些情况本质上是困难的。缓解和深入的防御措施是实施者的责任,而本规范并未对其做出规定。然而,在设计这些措施时,实施者应当使用户意识到位置共享,并提供可以撤销权限的用户界面。
地理位置是一个 默认的强大特性,由 名称
"geolocation"
标识。
当 检查权限 使用该 API 时,用户代理 可以 建议基于时间的 权限 有效期,例如 "24小时"、"1周",或者选择 永久记住该权限 授予 权限。然而,推荐 用户代理优先限制 权限 有效期 限制为单个会话:例如,可以一直有效,直到 环境设置对象 被销毁,最终用户 离开 当前 源,或相关的浏览器标签页被关闭。
在发布时,地理位置功能没有与之相关的安全性考虑。然而,建议读者阅读 3. 隐私性考虑。
WebIDL[Exposed=Window]
interface Geolocation
{
undefined getCurrentPosition
(
PositionCallback
successCallback,
optional PositionErrorCallback
? errorCallback = null,
optional PositionOptions
options = {}
);
long watchPosition
(
PositionCallback
successCallback,
optional PositionErrorCallback
? errorCallback = null,
optional PositionOptions
options = {}
);
undefined clearWatch
(long watchId);
};
callback PositionCallback
= undefined (
GeolocationPosition
position
);
callback PositionErrorCallback
= undefined (
GeolocationPositionError
positionError
);
Geolocation
的实例是使用以下表格中的内部插槽创建的:
内部插槽 | 描述 |
---|---|
[[cachedPosition]] |
一个 GeolocationPosition ,初始化为 null。
它是对最后获得位置的引用,并充当缓存。用户代理 MAY 随时将
[[cachedPosition]] 清除,方法是将其重置为 null,
无论出于何种原因。
|
[[watchIDs]] |
初始化为空的 列表,
包含 unsigned long
项目。
|
getCurrentPosition
(successCallback, errorCallback, options)方法步骤如下:
Document
不是
完全激活:Document
不是
完全激活:
POSITION_UNAVAILABLE
。
watchPosition
(successCallback, errorCallback, options)方法步骤如下:
Document
不是
完全激活:Document
不是
完全激活:
POSITION_UNAVAILABLE
。
unsigned long
,大于零。
[[watchIDs]]
。
当调用 clearWatch()
时,用户代理 必须:
[[watchIDs]]
。
要请求位置,传入一个 Geolocation
geolocation,一个 PositionCallback
successCallback,一个 PositionErrorCallback?
errorCallback,一个 PositionOptions
options,以及一个可选的 watchId:
[[watchIDs]]
。
Document
。
PERMISSION_DENIED
。
PERMISSION_DENIED
。
PermissionDescriptor
,其name
为 "geolocation"
。
PERMISSION_DENIED
。
要获取位置,传入 PositionCallback
successCallback,一个 PositionErrorCallback?
errorCallback,PositionOptions
options,以及一个可选的 watchId。
[[watchIDs]]
不包含 watchId,终止此算法。
EpochTimeStamp
,表示当前时间。
timeout
的和。
[[cachedPosition]]
。
"geolocation"
。
maximumAge
大于 0:
maximumAge
的值。
timestamp
的值大于 cacheTime,并且 cachedPosition.[[isHighAccuracy]]
等于
options.enableHighAccuracy
:
enableHighAccuracy
的值。
double
,使用
[WGS84]
坐标系统。经度测量从本初子午线向东或向西的距离。
double?
,以米为单位,相对于
[WGS84]
椭球体,或者为 null
如果不可用。高度测量距离海平面的高度。
double
,以米为单位。精度表示测量坐标与实际位置的接近程度。
double?
,或者为
null
如果不可用,表示 95% 置信水平,以米为单位。高度精度表示测量的高度与实际高度的接近程度。
double?
,以米每秒为单位,或者为
null
如果不可用。速度表示设备的移动速度。
double?
,以度为单位,或者为
null
如果不可用或者设备静止。方向表示设备相对于真北的移动方向。
GeolocationPosition
,传入 positionData,acquisitionTime 和 options.enableHighAccuracy
。
[[cachedPosition]]
设置为 position。
GeolocationPosition
,传递 acquisitionTime 和
options。enableHighAccuracy
。
[[cachedPosition]]
设置为
position。
report
"。
回调错误,传入 errorCallback 和 PERMISSION_DENIED
。
TIMEOUT
。
POSITION_UNAVAILABLE
。
当指示要回调错误时,给定一个 PositionErrorCallback?
callback 和一个 unsigned short
code:
GeolocationPositionError
实例,其 code
属性初始化为 code。
report
"。
WebIDLdictionary PositionOptions
{
boolean enableHighAccuracy
= false;
[Clamp] unsigned long timeout
= 0xFFFFFFFF;
[Clamp] unsigned long maximumAge
= 0;
};
enableHighAccuracy
成员提供了一个提示,
表示应用程序希望接收最准确的位置信息。
此成员的目的是允许应用程序通知实现它们不需要高精度的地理定位修正,因此实现可以避免使用消耗大量电量的地理定位提供者(例如,GPS)。
timeout
成员表示获取位置的最大时间长度(以毫秒为单位),在此时间过后,获取位置会超时。
等待文档可见以及获取使用
API 的权限的时间不包括在 timeout
成员所覆盖的时间内。timeout
成员仅在开始获取位置时适用。
maximumAge
成员指示 Web 应用程序愿意接受缓存的位置信息,其缓存时间不超过指定的时间(以毫秒为单位)。
WebIDL[Exposed=Window, SecureContext]
interface GeolocationPosition
{
readonly attribute GeolocationCoordinates
coords
;
readonly attribute EpochTimeStamp timestamp
;
[Default] object toJSON
();
};
coords
属性包含地理坐标。
timestamp
属性表示获取位置信息时的时间。
toJSON()
方法返回
GeolocationPosition
对象的 JSON 表示。
GeolocationPositionError
的实例被创建时,
包含以下表格中的内部槽:
内部槽 | 描述 |
---|---|
[[isHighAccuracy]] |
一个 boolean 值,用于记录
enableHighAccuracy
成员的值,当此
GeolocationPosition 被
创建时。
|
以下 任务来源 由本规范定义。
PositionCallback
和 PositionErrorCallback
,当执行
位置请求时使用。
WebIDL[Exposed=Window, SecureContext]
interface GeolocationCoordinates
{
readonly attribute double accuracy
;
readonly attribute double latitude
;
readonly attribute double longitude
;
readonly attribute double? altitude
;
readonly attribute double? altitudeAccuracy
;
readonly attribute double? heading
;
readonly attribute double? speed
;
[Default] object toJSON
();
};
latitude 和 longitude 属性是地理坐标,
以十进制度表示。 latitude
和 longitude
属性表示位置,指定为 WGS84 坐标系统中的角度实数。
accuracy
属性表示位置的精度半径,单位为米。
altitude
属性表示位置的高度,
以 [WGS84] 椭球体为基准,以米为单位。
altitudeAccuracy
属性表示高度精度,单位为米(例如,10
米)。
heading
属性表示设备的行驶方向,单位为度,范围是 0° ≤ heading
< 360°,相对于正北方向按顺时针方向计算。
speed
属性表示设备当前速度的水平分量的大小,单位是米每秒。
toJSON()
方法返回 GeolocationCoordinates
对象的 JSON
表示形式。
一个新的
GeolocationPosition
是通过以下步骤使用一个 map
positionData,EpochTimeStamp
timestamp 和布尔值 isHighAccuracy 构建的:
GeolocationCoordinates
实例。
GeolocationPosition
实例,
其 coords
属性初始化为
coords,timestamp
属性初始化为
timestamp,其 [[isHighAccuracy]]
内部槽位设置为 isHighAccuracy。
一个新的 GeolocationPosition
是通过以下步骤使用
EpochTimeStamp
timestamp 和布尔值
isHighAccuracy 构建的:
GeolocationCoordinates
实例:
latitude
属性为十进制度数的地理坐标。
longitude
属性为十进制度数的地理坐标。
accuracy
属性为非负实数。该值 应当 对应于纬度和经度值的 95% 置信水平。
altitude
属性为大于 [WGS84]
椭球体的高度,或如果实现无法提供高度信息则为 null
。
altitudeAccuracy
属性为非负实数,或者如果实现无法提供高度信息则为 null
。
如果提供了高度精度信息,则 应当 对应于 95% 置信水平。
speed
属性为非负实数,或者如果实现无法提供速度信息则为 null
。
heading
属性为角度值,或者如果实现无法提供航向信息则为 null
。
如果设备静止(即 speed
属性为 0),
则将 heading
初始化为
NaN
。
GeolocationPosition
实例,
其 coords
属性初始化为
coords,timestamp
属性
初始化为 timestamp,其 [[isHighAccuracy]]
内部槽位设置为 isHighAccuracy。
WebIDL[Exposed=Window]
interface GeolocationPositionError
{
const unsigned short PERMISSION_DENIED
= 1;
const unsigned short TIMEOUT
= 3;
readonly attribute unsigned short code
;
readonly attribute DOMString message
;
};
PERMISSION_DENIED
(数值 1)
POSITION_UNAVAILABLE
(数值 2)
TIMEOUT
(数值 3)
timeout
时间内未能成功
获取位置。
message
属性是一个面向开发者的文本描述,用于描述 code
属性。
本规范定义了一个由标记字符串 "geolocation"
识别的 受政策控制的功能。它的 默认允许列表 是 “self”。
标记为非规范性部分的部分,以及本规范中的所有编写指南、图表、示例和注释,都是非规范性的。本规范中的其他所有内容均为规范性的。
本文档中的关键字 MAY(可能)、MUST(必须)、RECOMMENDED(推荐) 和 SHOULD(应该) 应按 BCP 14 [RFC2119] [RFC8174] 中所述进行解释,仅在它们完全以大写形式出现时,如此处所示。
WebIDLpartial interface Navigator {
[SameObject] readonly attribute Geolocation
geolocation
;
};
[Exposed=Window]
interface Geolocation
{
undefined getCurrentPosition
(
PositionCallback
successCallback,
optional PositionErrorCallback
? errorCallback = null,
optional PositionOptions
options = {}
);
long watchPosition
(
PositionCallback
successCallback,
optional PositionErrorCallback
? errorCallback = null,
optional PositionOptions
options = {}
);
undefined clearWatch
(long watchId);
};
callback PositionCallback
= undefined (
GeolocationPosition
position
);
callback PositionErrorCallback
= undefined (
GeolocationPositionError
positionError
);
dictionary PositionOptions
{
boolean enableHighAccuracy
= false;
[Clamp] unsigned long timeout
= 0xFFFFFFFF;
[Clamp] unsigned long maximumAge
= 0;
};
[Exposed=Window, SecureContext]
interface GeolocationPosition
{
readonly attribute GeolocationCoordinates
coords
;
readonly attribute EpochTimeStamp timestamp
;
[Default] object toJSON
();
};
[Exposed=Window, SecureContext]
interface GeolocationCoordinates
{
readonly attribute double accuracy
;
readonly attribute double latitude
;
readonly attribute double longitude
;
readonly attribute double? altitude
;
readonly attribute double? altitudeAccuracy
;
readonly attribute double? heading
;
readonly attribute double? speed
;
[Default] object toJSON
();
};
[Exposed=Window]
interface GeolocationPositionError
{
const unsigned short PERMISSION_DENIED
= 1;
const unsigned short POSITION_UNAVAILABLE
= 2;
const unsigned short TIMEOUT
= 3;
readonly attribute unsigned short code
;
readonly attribute DOMString message
;
};
accuracy
attribute for GeolocationCoordinates
§9.1
altitude
attribute for GeolocationCoordinates
§9.2
altitudeAccuracy
attribute
for GeolocationCoordinates
§9.2
[[cachedPosition]]
internal slot
for Geolocation
§6.1
clearWatch()
method for
Geolocation
§6.4
code
attribute for
GeolocationPositionError
§10.2
coords
attribute for
GeolocationPosition
§8.1
enableHighAccuracy
member for
PositionOptions
§7.1
geolocation
attribute for
Navigator
§5.
Geolocation
interface
§6.
"geolocation"
§3.4
GeolocationCoordinates
interface
§9.
GeolocationPosition
interface
§8.
GeolocationPositionError
interface
§10.
getCurrentPosition
method for Geolocation
§6.2
heading
attribute
for GeolocationCoordinates
§9.3
[[isHighAccuracy]]
internal slot
for GeolocationPosition
§8.4
latitude
attribute for GeolocationCoordinates
§9.1
longitude
attribute for GeolocationCoordinates
§9.1
maximumAge
member for
PositionOptions
§7.3
message
attribute for GeolocationPositionError
§10.3
PERMISSION_DENIED
§10.1
POSITION_UNAVAILABLE
§10.1
PositionCallback
§6.
PositionErrorCallback
§6.
PositionOptions
字典
§7.
speed
attribute for
GeolocationCoordinates
§9.4
timeout
member for
PositionOptions
§7.2
TIMEOUT
§10.1
timestamp
attribute
for GeolocationPosition
§8.2
[[watchIDs]]
internal slot for
Geolocation
§6.1
watchPosition
method
for Geolocation
§6.3
EpochTimeStamp
allow
属性(用于 iframe
元素)
Document
)
iframe
元素
Document
)
list
)
list
)
map
)
list
)
list
)
permission
)
permission
)
name
(用于 PermissionDescriptor
)
PermissionDescriptor
boolean
类型
[Clamp]
扩展属性
[Default]
扩展属性
DOMString
接口
double
类型
[Exposed]
扩展属性
long
类型
object
类型
[SameObject]
扩展属性
[SecureContext]
扩展属性
undefined
类型
unsigned long
类型
unsigned short
类型
本节为非规范性内容。
本规范基于行业内的早期工作,包括Aza Raskin的研究、Google Gears地理定位API和LocationAware.org。
还要感谢Alec Berntson、Alissa Cooper、Steve Block、Greg Bolsinga、Lars Erik Bolstad、Aaron Boodman、Dave Burke、Chris Butler、Max Froumentin、Shyam Habarakada、Marcin Hanclik、Ian Hickson、Brad Lassey、Angel Machin、Cameron McCormack、Daniel Park、Stuart Parmenter、Olli Pettay、Chris Prince、Arun Ranganathan、Carl Reed、Thomas Roessler、Dirk Segers、Allan Thomson、Martin Thomson、Doug Turner、Erik Wilde、Matt Womer和Mohamed Zergaoui。
本节为非规范性内容。
自2021年首次公开工作草案以来,地理定位已进行以下规范性更改:
自2016年第二版发布以来,本规范已进行以下实质性更改:
errorCallback
现在可为空。callbacks
不再被视为“事件处理器”对象(即,具有.handleEvent()
方法的对象),而是被专门视为IDL回调函数。[NoInterfaceObject]
,因此Geolocation
和本规范的其他接口现在在全局作用域中。此外,接口名称从NavigatorGeolocation
更改为Geolocation
。
查看 提交历史 获取完整的更改列表。
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: