另请参阅 翻译。
Copyright © 2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
地理位置提供对与托管设备关联的地理位置信息的访问。
本节描述了本文档在发布时的状态。当前的 W3C 出版物列表以及本技术报告的最新修订版可以在位于 https://www.w3.org/TR/ 的 W3C 标准和草案索引中找到。
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:
Referenced in:
自本规范于 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 本身与底层位置信息源无关,并且不保证该 API 返回设备的实际位置。
如果最终用户授予权限, 地理位置:
GeolocationPosition
接口提供位置数据,如纬度、经度、高度、速度和方向,以及获取的位置数据的精度和获取位置的大致时间。
getCurrentPosition
()
方法支持“一次性”位置更新,并通过 watchPosition
()
方法支持在承载设备的位置发生重大变化时接收更新。
PositionOptions
的 maximumAge
,
允许应用程序请求年龄不大于指定值的缓存位置(仅缓存最后一个位置)。
GeolocationPositionError
的形式接收在获取位置时发生的错误更新。
enableHighAccuracy
,支持请求“高精度”位置数据,尽管用户代理可以忽略该请求。
本节内容不具规范性。
本规范仅限于提供一个脚本 API,用于检索与承载设备关联的地理位置信息。地理位置信息以世界大地测量系统坐标 [WGS84] 的形式提供。它不包括提供任何类型的标记语言,也不包括定义用于构建标识地理位置的 URL 的新 URL 方案。
本节内容不具规范性。
该 API 设计用于支持“一次性”位置请求和重复位置更新。以下示例说明了常见的用例。
本节内容不具规范性。
请求用户的当前位置。如果用户允许,您将获得一个位置对象。
本节内容不具规范性。
请求监视用户当前位置的能力。如果用户允许,您将获得用户位置的持续更新。
本节内容不具规范性。
通过调用
clearWatch
()
方法停止监视位置更改。
本节内容不具规范性。
发生错误时,
watchPosition
()
或
getCurrentPosition
()
方法的第二个参数会使用
GeolocationPositionError
错误进行调用,这可以帮助您找出可能出错的地方。
本节内容不具规范性。
默认情况下,只要 API 具有先前获取的位置,它总是尝试返回缓存的位置。在此示例中,我们接受年龄不超过 10 分钟的位置。如果用户代理没有足够新的缓存位置对象,它会自动获取新位置。
本节内容不具规范性。
如果您需要以时间敏感的方式获取位置信息,可以使用 PositionOptions
timeout
成员来限制您愿意等待获取位置的时间。
本节内容不具规范性。
'self'
的默认允许列表
允许在同源嵌套框架中使用 API,但阻止第三方内容使用 API。
可以通过向
iframe
元素添加
allow
="geolocation"
属性来选择性地启用第三方使用:
或者,可以通过指定 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。它是对最后获取位置的引用,并用作缓存。用户代理可以随时出于任何原因通过将其重置为 null 来逐出 [[cachedPosition]] 。
|
[[watchIDs]] |
初始化为一个空的 列表,其中包含 unsigned long
项。
|
getCurrentPosition
(successCallback,
errorCallback, options)
方法的步骤如下:
Document
不是完全激活:Document
不是完全激活:
POSITION_UNAVAILABLE
。
watchPosition
(successCallback,
errorCallback, options)
方法的步骤如下:
Document
不是完全激活:Document
不是完全激活:
POSITION_UNAVAILABLE
。
unsigned long
。
[[watchIDs]]
。
当调用 clearWatch()
时,用户代理必须:
[[watchIDs]]
中移除 watchId。
要请求位置,传递一个 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"
。
GeolocationPositionError
:
GeolocationPosition
传递 emulatedPositionData、acquisitionTime 和
options.enableHighAccuracy
。
report
"。
maximumAge
大于 0:
maximumAge
成员的值。
timestamp
的值大于
cacheTime,并且
cachedPosition.[[isHighAccuracy]]
等于
options.enableHighAccuracy
enableHighAccuracy
的值。
double
类型,表示地球表面以度为单位的经度坐标,
使用 [WGS84]
坐标系。经度测量一个点距离本初子午线向东或向西的距离。
double?
类型,表示高于 [WGS84]
椭球体的高度(以米为单位),如果不可用则为 null
。高度测量海平面以上的高度。
double
类型,表示精度值,指示 95% 置信水平(以米为单位)。精度测量测量坐标与真实位置的接近程度。
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 类型,记录了当此
GeolocationPosition 被创建时
enableHighAccuracy
成员的值。
|
本规范定义了以下任务源。
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'。
为了用户代理自动化和应用程序测试的目的,本文档定义了地理位置模拟。
每个顶级可遍历对象都有一个关联的模拟位置数据,该数据表示
GeolocationCoordinates
、GeolocationPositionError
或 null,初始为
null。
要设置模拟位置数据,给定可导航对象 navigable 和一个 emulatedPositionData:
GeolocationCoordinates
或 GeolocationPositionError
。
要获取模拟位置数据,给定 Geolocation
geolocation:
Document
的节点可导航对象。
除了标记为非规范的部分外,本规范中的所有创作指南、图表、示例和注释都是非规范的。本规范中的其他所有内容都是规范的。
本文档中的关键词 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
;
};
GeolocationCoordinates
的
accuracy
属性
§9.1
GeolocationCoordinates
的
altitude
属性
§9.2
GeolocationCoordinates
的
altitudeAccuracy
属性
§9.2
Geolocation
的
[[cachedPosition]]
内部插槽
§6.1
Geolocation
的
clearWatch()
方法
§6.4
GeolocationPositionError
的
code
属性
§10.2
GeolocationPosition
的
coords
属性
§8.1
PositionOptions
的
enableHighAccuracy
成员
§7.1
Navigator
的
geolocation
属性
§5.
Geolocation
接口
§6.
"geolocation"
§3.4
GeolocationCoordinates
接口
§9.
GeolocationPosition
接口
§8.
GeolocationPositionError
接口
§10.
Geolocation
的
getCurrentPosition
方法
§6.2
GeolocationCoordinates
的 heading
属性
§9.3
GeolocationPosition
的
[[isHighAccuracy]]
内部插槽
§8.4
GeolocationCoordinates
的
latitude
属性
§9.1
GeolocationCoordinates
的
longitude
属性
§9.1
PositionOptions
的
maximumAge
成员
§7.3
GeolocationPositionError
的
message
属性
§10.3
PERMISSION_DENIED
§10.1
POSITION_UNAVAILABLE
§10.1
PositionCallback
§6.
PositionErrorCallback
§6.
PositionOptions
字典
§7.
GeolocationCoordinates
的
speed
属性
§9.4
PositionOptions
的
timeout
成员
§7.2
TIMEOUT
§10.1
GeolocationPosition
的
timestamp
属性
§8.2
Geolocation
的 [[watchIDs]]
内部插槽
§6.1
Geolocation
的
watchPosition
方法
§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
现在可以为 null。
callbacks
不再被视为“EventHandler”对象
(即具有 .handleEvent()
方法的对象),而是现在
专门作为 IDL 回调函数处理。
[NoInterfaceObject]
,因此本规范的 Geolocation
和其他接口现在位于全局作用域中。此外,接口已从
NavigatorGeolocation*
重命名为 Geolocation*
。
有关完整的更改列表,请参阅提交历史记录。