Network Information API 允许获取网络信息和监听网络信息更改，以及 Save Data API 提供了侦测用户流量使用倾向的方法

通过 navigator.connection 暴露 NetworkInformation 实例使用

获取网络信息

NetworkInformation 接口的 type 属性表示当前的网络连接的类型

NetworkInformation 接口的 effectiveType 属性表示当前的网络连接的状态

NetworkInformation 接口的 downlink 属性表示当前的 downlink 速度

NetworkInformation 接口的 downlinkMax 属性表示当前最大的 downlink 速度

NetworkInformation 接口的 rtt 属性表示当前的 RTT 参数

1
2
3
4
5

const type = navigator.connection.type
const effectiveType = navigator.connection.effectiveType
const downlink = navigator.connection.downlink
const downlinkMax = navigator.connection.downlinkMax
const rtt = navigator.connection.rtt

监听网络信息

NetworkInformation 接口的 change 事件在网络信息更新时触发

1

navigator.connection.addEventListener('change', () => { /* to do something */ })

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

interface Navigator {
  readonly connection: NetworkInformation
}

interface WorkerNavigator {
  readonly connection: NetworkInformation
}

interface NetworkInformation extends EventTarget {
  readonly type: ConnectionType
  readonly effectiveType: EffectiveConnectionType
  readonly downlinkMax: number
  readonly downlink: number
  readonly rtt: number
  readonly saveData: boolean
  onchange: ((this: NetworkInformation, ev: Event) => any) | null
}

interface NetworkInformationEventMap {
  change: Event
}

type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown'

type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g'

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API
• https://wicg.github.io/netinfo/

Picture-in-Picture API 允许某个特定的视频元素管理画中画模式

启用画中画模式

通过调用 HTMLVideoElement 接口上的 requestPictureInPicture() 方法以启用画中画模式

方法返回一个 Promise 的 PictureInPictureWindow

方法可能抛出 SecurityError 异常，如当前特性被 Permission Policy 拒绝

1

element.requestPictureInPicture()

停止画中画模式

通过调用 Document 接口上的 exitPictureInPicture() 方法以停止画中画模式

方法返回一个 Promise

1

document.exitPictureInPicture()

画中画模式信息

HTMLVideoElement 接口上的 disablePictureInPicture 属性反映了当前视频元素的画中画模式是否可用，返回 boolean 值

Document 接口上的 pictureInPictureEnabled 只读属性反映了当前文档的画中画模式是否可用，返回 boolean 值

Document 接口或 ShadowRoot 接口上的 pictureInPictureElement 只读属性反映了当前处于画中画模式的元素，返回 Element 值或 null 值

HTMLVideoElement 接口上的 enterpictureinpicture 事件在当前元素成功启用画中画模式时触发，返回一个 PictureInPictureEvent 事件

HTMLVideoElement 接口上的 leavepictureinpicture 事件在当前元素成功停止画中画模式时触发，返回一个 PictureInPictureEvent 事件

PictureInPictureEvent 事件继承自 Event 事件，其唯一额外 pictureInPictureWindow 只读属性代表当前事件相关的 PictureInPictureWindow 实例

PictureInPictureWindow 接口反映了当前的画中画模式窗口，其 width 只读属性和 height 只读属性反映了窗口的宽高，其 resize 事件在窗口尺寸改变时触发并返回一个 PictureInPictureEvent 事件

权限策略

该 API 调用受到 picture-in-picture 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认值是 *，即允许任意源的浏览上下文使用该 API

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

interface Document {
  readonly pictureInPictureElement: Element | null
  readonly pictureInPictureEnabled: boolean
  exitPictureInPicture(): Promise<void>
}

interface ShadowRoot {
  readonly pictureInPictureElement: Element | null
}

interface HTMLVideoElement {
  disablePictureInPicture: boolean
  requestPictureInPicture(): Promise<PictureInPictureWindow>
  onenterpictureinpicture: ((this: HTMLVideoElement, ev: PictureInPictureEvent) => any) | null
  onleavepictureinpicture: ((this: HTMLVideoElement, ev: PictureInPictureEvent) => any) | null
}

interface PictureInPictureEvent extends Event {
  readonly pictureInPictureWindow: PictureInPictureWindow
}

interface PictureInPictureWindow extends EventTarget {
  readonly width: number
  readonly height: number
  onresize: ((this: PictureInPictureWindow, ev: PictureInPictureEvent) => any) | null
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
• https://w3c.github.io/picture-in-picture/

Fullscreen API 允许某个特定的元素管理全屏模式

启用全屏模式

通过调用 Element 接口上的 requestFullscreen() 方法以启用全屏模式

方法传入一个可选的配置项，其唯一 navigationUI 可选参数控制是否展示 navigation UI，值为 "auto" "show" "hide" 之一，默认值为 "auto"

方法返回一个 Promise

方法可能抛出 TypeError 异常，如当前文档并非处于活跃状态、当前元素未处于文档中、当前元素不允许使用全屏模式、当前元素是一个激活的 popover 元素、当前元素是 <dialog> 元素、当前元素不是 HTML SVG MathML 元素等等

1

element.requestFullscreen()

停止全屏模式

通过调用 Document 接口上的 exitFullscreen() 方法以停止全屏模式

方法返回一个 Promise

1

document.exitFullscreen()

全屏模式信息

Document 接口上的 fullscreenEnabled 属性反映了全屏模式是否可用，返回 boolean 值

Document 接口或 ShadowRoot 接口上的 fullscreenElement 属性反映了当前处于全屏模式的元素，返回 Element 值或 null 值

Document 接口或 Element 接口上的 fullscreenchange 事件在文档或元素的全屏状态改变时触发，返回一个 Event 事件

Document 接口或 Element 接口上的 fullscreenerror 事件在文档或元素的全屏状态改变失败时触发，返回一个 Event 事件

通常，监听 Web 程序内的全屏状态改变，通过监听 Document 接口上的即可，文档内元素的相应事件会冒泡至文档

权限策略

该 API 调用受到 fullscreen 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

interface Document {
  readonly fullscreenElement: Element | null
  readonly fullscreenEnabled: boolean
  exitFullscreen(): Promise<void>
  onfullscreenchange: ((this: Document, ev: Event) => any) | null
  onfullscreenerror: ((this: Document, ev: Event) => any) | null
}

interface ShadowRoot {
  readonly fullscreenElement: Element | null
}

interface Element {
  requestFullscreen(options?: FullscreenOptions): Promise<void>
  onfullscreenchange: ((this: Element, ev: Event) => any) | null
  onfullscreenerror: ((this: Element, ev: Event) => any) | null
}

interface FullscreenOptions {
  navigationUI?: FullscreenNavigationUI
}

type FullscreenNavigationUI = 'auto' | 'hide' | 'show'

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API
• https://fullscreen.spec.whatwg.org/

Keyboard Lock API 允许控制键盘的输入形式，捕获键盘的输入从而进行自定义的处理（特别是针对一些特殊按键）

通过 navigator.keyboard 暴露的 Keyboard 接口实例使用

该 API 的使用要求有用户交互的发生

启用键盘锁定

使用 Keyboard 接口的 lock() 方法启用键盘锁定

方法可以传递一个可选的 keyCodes 字符串数组参数，代表要锁定的键值码；不传递则代表锁定所有的按键

方法返回一个 Promise

方法可能抛出 AbortError，若在该方法完成前又重新调用了该方法

方法可能抛出 InvalidAccessError，若任一 keyCodes 中的项非法

方法可能抛出 InvalidStateError，若方法未在活跃浏览器上下文中调用

1
2

navigator.keyboard.lock()
navigator.keyboard.lock(['KeyW', 'KeyA', 'KeyS', 'KeyD'])

若调用多次调用 lock() 方法且中途未调用 unlock() 方法，则只有最后一次指定的 keyCodes 有效

停止键盘锁定

使用 Keyboard 接口的 unlock() 方法停止键盘锁定

1

navigator.keyboard.unlock()

类型

1
2
3
4
5
6
7
8

interface Keyboard extends EventTarget {
  lock(keyCodes?: string[]): Promise<void>
  unlock(): void
}

interface Navigator {
  readonly keyboard: Keyboard
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API
• https://wicg.github.io/keyboard-lock/

Pointer Lock API 允许控制鼠标的输入形式，将鼠标的移动从光标位置移动转换为自定义的形式（同时隐藏光标）

指针锁定与鼠标捕获比较类似，但其是持久的，即不会自动释放鼠标；并且其不受浏览器边界的限制；最大特点是，其会隐藏光标

启用指针锁定

通过调用对应 Element 接口上的 requestPointerLock() 方法以启用指针锁定

方法默认无参数，新提案支持传入一组配置项，唯一参数 unadjustedMovement 指定是否启用操作系统级别的鼠标位置适配，目前为部分浏览器支持

方法默认无返回值，但新提案支持返回 Promise，目前为部分浏览器支持

方法调用要求存在用户交互且为活跃文档，并且不允许连续调用该方法，并且 <iframe> 标签中的调用需要设置允许 allow-pointer-lock 沙箱策略并且除 该<iframe> 标签之外的其他 <iframe> 标签必须未处于指针调用状态，否则调用会失败

1

el.requestPointerLock()

停止指针锁定

通过调用 Document 接口上的 exitPointerLock() 方法以停止指针锁定

1

document.exitPointerLock()

指针锁定信息

Document 接口或 ShadowRoot 接口的 pointerLockElement 属性返回当前启用指针锁定的元素，若不存在则返回 null

Document 接口的 pointerlockchange 事件在指针锁定状态改变时触发，返回一个 Event 事件

Document 接口的 pointerlockerror 事件在指针锁定状态改变失败时触发，返回一个 Event 事件’

MouseEvent 接口的 movementX 属性与 movementY 属性仅在 mousemove 事件中可用，反映了前后两个 mousemove 事件的鼠标移动的坐标

沙箱策略

该 API 在 <iframe> 标签中的调用受到 allow-pointer-lock 沙箱策略的控制，需要将 sandbox 的属性指定为允许

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

interface Document {
  exitPointerLock(): void
  onpointerlockchange: ((this: Document, ev: Event) => any) | null
  onpointerlockerror: ((this: Document, ev: Event) => any) | null
}

interface DocumentOrShadowRoot {
  readonly pointerLockElement: Element | null
}

interface Element {
  requestPointerLock(): void
}

interface MouseEvent {
  readonly movementX: number
  readonly movementY: number
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API
• https://w3c.github.io/pointerlock/

Screen Wake Lock API 允许控制设备的屏幕变暗、休眠或锁定的策略

通过 navigator.wakeLock 暴露的 WakeLock 接口实例使用

启用屏幕管理策略

通过 WakeLock 接口的 request() 方法来请求启用屏幕管理策略

方法传入一个可选的 type 字符串参数，唯一允许值为 'screen'

方法返回一个 Promise 的 WakeLockSentinel 实例

方法可能抛出一个 NotAllowedError 异常，例如被 Permissions Policy 拒绝、当前网页未处于活跃状态、当前网页处于隐藏状态或用户代理无法获取到系统的屏幕管理策略

1

const sentinel = await navigator.wakeLock.request()

释放屏幕管理策略

通过 WakeLockSentinel 接口的 release() 方法来手动关闭屏幕管理策略

方法返回一个 Promise

1

sentinel.release()

同时，操作系统可能会在网页失去焦点或隐藏时自动关闭屏幕管理策略

屏幕管理策略信息

WakeLockSentinel 接口的 released 属性返回一个 boolean，表示当前 WakeLockSentinel 是否已被释放

WakeLockSentinel 接口的 type 属性返回一个 string，表示当前 WakeLockSentinel 的类型

WakeLockSentinel 接口的 release 事件，在 WakeLockSentinel 被释放时触发，返回一个 Event 事件

权限策略

该 API 调用受到 screen-wake-lock 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12

interface WakeLock {
  request(type?: WakeLockType): Promise<WakeLockSentinel>
}

interface WakeLockSentinel extends EventTarget {
  onrelease: ((this: WakeLockSentinel, ev: Event) => any) | null
  readonly released: boolean
  readonly type: WakeLockType
  release(): Promise<void>
}

type WakeLockType = 'screen'

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API
• https://w3c.github.io/screen-wake-lock/

Battery Status API 提供了访问设备电源信息和监听电源信息变化的功能，可以用于动态根据用户设备的电源情况调整一些功能的策略

获取电源管理实例

使用 Navigator 接口的 getBattery() 方法获取到电源管理实例，方法返回一个 Promise 的 BatteryManager 实例

1

const batteryManager = await navigator.getBattery()

获取设备电源信息

BatteryManager 接口提供了访问设备电源信息的属性

BatteryManager 接口的 charging 属性返回一个 boolean，表示当前设备是否处于充电状态

BatteryManager 接口的 chargingTime 属性返回一个 number，表示当前设备充电完成所需的充电时间，若设备已充满或无法获取电源信息则返回 0，若设备未处于充电状态则返回 +Infinity

BatteryManager 接口的 dischargingTime 属性返回一个 number，表示当前设备至完全耗尽电量的时间，若设备处于充电状态或无法获取电源信息则返回 +Infinity

BatteryManager 接口的 level 属性返回一个范围从 0.0 到 1.0 之间的 number，表示当前设备电源的电量百分比，若无法获取电源信息则返回 1.0

1
2
3
4

batteryManager.charging
batteryManager.chargingTime
batteryManager.dischargingTime
batteryManager.level

监听设备电源信息更新

BatteryManager 接口提供了监听设备电源信息变化的事件

BatteryManager 接口的 chargingchange 事件在电源充电状态改变时触发，即 charging 属性改变时触发

BatteryManager 接口的 chargingtimechange 事件在电源充电完成时间改变时触发，即 chargingTime 属性改变时触发

BatteryManager 接口的 dischargingtimechange 事件在电源电量耗尽时间改变时触发，即 dischargingTime 属性改变时触发

BatteryManager 接口的 levelchange 事件在电源电量改变时触发，即 level 属性改变时触发

1
2
3
4
5
6
7
8
9
10
11
12

batteryManager.addEventListener('chargingchange', () => {
  console.log(batteryManager.charging)
})
batteryManager.addEventListener('chargingtimechange', () => {
    console.log(batteryManager.chargingTime)
})
batteryManager.addEventListener('dischargingtimechange', () => {
    console.log(batteryManager.dischargingTime)
})
batteryManager.addEventListener('levelchange', () => {
    console.log(batteryManager.level)
})

权限策略

该 API 受 battery 权限策略的限制（无论是通过 Permissions-Policy 响应头指定抑或是通过 iframe 元素的 allow 属性指定）

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14

interface Navigator {
  getBattery: () => Promise<BatteryManager>
}

interface BatteryManager extends EventTarget {
  readonly charging: boolean
  readonly chargingTime: number
  readonly dischargingTime: number
  readonly level: number
  onchargingchange: ((this: BatteryManager, ev: Event) => any) | null
  onchargingtimechange: ((this: BatteryManager, ev: Event) => any) | null
  ondischargingtimechange: ((this: BatteryManager, ev: Event) => any) | null
  onlevelchange: ((this: BatteryManager, ev: Event) => any) | null
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API
• https://w3c.github.io/battery/

Web Storage API 可用于保存键值对形式的数据，包括 localStorage 和 sessionStorage 两种，键值对均要求为字符串（非字符串类型数据会隐式转换为字符串）

sessionStorage 会话存储的数据仅在当前会话中有效，若关闭标签页或浏览器则会失效

localStorage 本地存储的数据长期有效

Web Storage API 同样受同源策略限制，不同源的 Storage 无法共享

Storage 的获取

通过 window.sessionStorage 访问会话存储对应的 Storage 实例

通过 window.localStorage 访问本地存储对应的 Storage 实例

Storage 的操作

Storage 接口提供了一些对会话存储或本地存储的操作方法

读取键值对

Storage 接口的 getItem() 方法用于获取指定键名对应的键值，若数据不存在则返回 null

1

window.localStorage.getItem('k')

设置键值对

Storage 接口的 setItem() 方法用于设置键值对

1

window.localStorage.setItem('k', 'v')

清除键值对

Storage 接口的 removeItem() 方法用于移除指定键名对应的键值

1

window.localStorage.removeItem('k')

清空存储

Storage 接口的 clear() 方法用于清除整个存储

1

window.localStorage.clear()

其他

Storage 接口的 length 属性返回存储的长度

Storage 接口支持直接使用键名索引来获取或设置对应的键值，支持直接使用 delete 关键字移除对应的键值

Storage 接口的 key() 方法用于获取指定索引的值，索引的顺序是由浏览器决定的，因此该顺序是不可靠的，若数据不存在则返回 null

1
2
3
4
5
6
7
8

window.localStorage.length
window.localStorage.k
window.localStorage['k']
window.localStorage.k = 'v'
window.localStorage['k'] = 'v'
delete window.localStorage.k
delete window.localStorage['k']
window.localStorage.key(0)

存储更改

会话存储或本地存储的更改会在与之同域的会话中触发全局 Window 的 storage 事件，并返回一个 StorageEvent 事件

StorageEvent 事件的 storageArea 属性返回存储变化的 Storage 实例

StorageEvent 事件的 url 属性返回存储变化的文档的 URL

StorageEvent 事件的 key 属性返回存储变化的键名

StorageEvent 事件的 oldValue 属性返回存储变化的原键值或 null

StorageEvent 事件的 newValue 属性返回存储变化的现键值或 null

1
2
3
4
5
6
7

window.addEventListener('storage', (e) => {
  console.log(e.key)
  console.log(e.oldValue)
  console.log(e.newValue)
  console.log(e.url)
  console.log(e.storageArea)
})

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

interface Window {
  readonly localStorage: Storage
  readonly sessionStorage: Storage
  onstorage: ((this: WindowEventHandlers, ev: StorageEvent) => any) | null
}

interface Storage {
  readonly length: number
  clear(): void
  getItem(key: string): string | null
  key(index: number): string | null
  removeItem(key: string): void
  setItem(key: string, value: string): void
  [name: string]: any
}

interface StorageEvent extends Event {
  readonly key: string | null
  readonly newValue: string | null
  readonly oldValue: string | null
  readonly storageArea: Storage | null
  readonly url: string
  initStorageEvent(type: string, bubbles?: boolean, cancelable?: boolean, key?: string | null, oldValue?: string | null, newValue?: string | null, url?: string | URL, storageArea?: Storage | null): void
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
• https://html.spec.whatwg.org/multipage/webstorage.html

Cookie 是一小段保存在用户端的信息，用于改善用户的网络浏览体验，通常包括用户的选项或识别信息，用户可以选择网站使用 Cookie 的方式

可用使用 navigator.cookieEnabled 判断页面是否允许使用 Cookie

Cookie 的设置

可以通过 Set-Cookie 响应头设置 Cookie 或使用 JS 脚本 document.cookie 设置 Cookie

1
2

HTTP/2.0 200 OK
Set-Cookie: cookie_a=a

1

document.cookie = 'cookie_b=b';

Cookie 的读取

执行请求时可以通过 Cookie 请求头自动带上 Cookie

JS 脚本中可以通过 document.cookie 读取 Cookie

1

const cookies = document.cookie;

Cookie 的选项

• Expires 属性

  指定 Cookie 在给定时间后失效

• Max-Age 属性

  指定 Cookie 在超出给定时长后失效

• Secure 属性

  指定 Cookie 仅在 Secure Context 下才发送；并且非 Secure Context 下无法设置该属性

• HttpOnly 属性

  指定 Cookie 无法通过 document.cookie 读取和修改

  常用于防御 XSS 攻击

• Domain 属性

  指定 Cookie 可用的域名（及子域名），默认会包含当前的域名

• Path 属性

  指定 Cookie 可用的路径（及子路径）

• SameSite 属性

  指定 Cookie 是否在跨域请求中发送

  常用于防御 CSRF 攻击

  Strict 值指定仅在同域请求中发送

  Lax 值允许在用户导航至 Cookie 的域名时发送，该值是默认的行为

  None 值指定允许在跨域请求中发送，但需同时指定 Secure 属性

1

Set-Cookie: cookie_b=b; Expires=Thu, 31 Oct 2021 07:28:00 GMT; Secure; HttpOnly; Domain=example.com; Path=/; SameSite=Strict

• __Host- 前缀

  指定对应的 Cookie 需指定 Secure 属性（即需要在 Secure Context 发送），不得指定 Domain 属性，Path 属性需指定为 /

• __Secure- 前缀

  指定对应的 Cookie 需指定 Secure 属性（即需要在 Secure Context 发送）

链接

• https://html.spec.whatwg.org/multipage/dom.html#dom-document-cookie
• https://httpwg.org/specs/rfc6265.html#cookie
• https://httpwg.org/specs/rfc6265.html#sane-set-cookie

Geolocation API 提供了访问用户地理位置的方法

通过 navigator.geolocation 暴露的 Geolocation 接口实例访问

使用 API 需要向用户请求授权并获得允许，并且仅在 Secure Context 环境下启用

获取地理位置

使用 Geolocation 接口的 getCurrentPosition() 方法获取地理位置

方法需要传入一个在获取地理位置成功时调用的回调函数，该回调函数会被传递一个 GeolocationPosition 参数

方法可以传入一个在获取地理位置失败时调用的回调函数，该回调函数会被传递一个 GeolocationPositionError 参数

方法同样可以传入一个可选的配置项：

maximumAge 可选选项接收一个正数值，指定使用缓存的地理位置的允许的最长的期限，默认为 0

timeout 可选选项接收一个正数值，指定获取地理位置等待的超时时间，默认为 Infinity

enableHighAccuracy 可选选项接收一个布尔值，指定是否尝试获取最精确的可能值，默认值 false

权限策略

该 API 调用受到 geolocation 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认值是 *，即允许任意源的浏览上下文使用该 API

权限 API

该 API 调用需要获得用户 geolocation 权限的允许，可以调用 Permission.query() 方法检查用户是否已授予了该权限

1
2
3
4
5
6
7
8
9
10
11
12
13

navigator.geolocation.getCurrentPosition(
  (position) => {
    // todo something with the position data
  },
  (error) => {
    // todo something when getting position failed
  },
  {
    maximumAge: 0,
    timeout: Infinity,
    enableHighAccuracy: false,
  }
)

监听地理位置

使用 Geolocation 接口的 watchPosition() 方法注册监听地理位置的更新

方法的参数类似于 getCurrentPosition() 方法

方法返回一个数字，代表注册回调的 ID，可用于 clearWatch() 方法取消监听

使用 Geolocation 接口的 clearWatch() 方法取消注册监听地理位置的更新

地理位置信息

GeolocationPosition 接口用于表示一组地址位置信息记录

其 coords 只读属性代表一个 GeolocationCoordinates 实例，表示地址位置信息的具体内容

而 timestamp 只读属性返回一个时间戳，代表获取地址位置信息的时间点

GeolocationCoordinates 接口用于表示一个地址位置信息详情

latitude 只读属性代表纬度

longitude 只读属性代表经度

accuracy 只读属性代表经纬度精度

altitude 只读属性代表海平面高度，设备不支持时返回 null

altitudeAccuracy 只读属性代表海平面高度精度，设备不支持时返回 null

heading 只读属性代表设备方向，设备不支持时返回 null

speed 只读属性代表设备移动速度，设备不支持时返回 null

异常处理

GeolocationPositionError 接口表示获取地理位置失败的异常

code 只读属性代表错误状态码，可能为常量枚举 PERMISSION_DENIED、POSITION_UNAVAILABLE 或 TIMEOUT 之一，常量枚举可以通过 GeolocationPositionError 本身或其实例访问

message 只读属性代表错误信息，通常是用于调试目的而非直接向用户展示

权限策略

该 API 调用受到 geolocation 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

权限 API

该 API 调用需要用户授予 geolocation 权限，可以调用 Permission.query() 方法检查用户是否已授予了该权限

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

interface Navigator {
  readonly geolocation: Geolocation
}

interface Geolocation {
  clearWatch(watchId: number): void
  getCurrentPosition(successCallback: PositionCallback, errorCallback?: PositionErrorCallback | null, options?: PositionOptions): void
  watchPosition(successCallback: PositionCallback, errorCallback?: PositionErrorCallback | null, options?: PositionOptions): number
}

interface PositionCallback {
  (position: GeolocationPosition): void
}

interface PositionErrorCallback {
  (positionError: GeolocationPositionError): void
}

interface PositionOptions {
  enableHighAccuracy?: boolean
  maximumAge?: number
  timeout?: number
}

interface GeolocationPosition {
  readonly coords: GeolocationCoordinates
  readonly timestamp: EpochTimeStamp
}

interface GeolocationPositionError {
  readonly code: number
  readonly message: string
  readonly PERMISSION_DENIED: 1
  readonly POSITION_UNAVAILABLE: 2
  readonly TIMEOUT: 3
}

interface GeolocationCoordinates {
  readonly accuracy: number
  readonly altitude: number | null
  readonly altitudeAccuracy: number | null
  readonly heading: number | null
  readonly latitude: number
  readonly longitude: number
  readonly speed: number | null
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API
• https://w3c.github.io/geolocation-api/