Navigator

[TOC]

索引

Navigator

属性：

浏览器标识：

navigator.userAgent：string，返回浏览器的完整用户代理字符串（包含浏览器名称、版本、操作系统等信息）。

平台与操作系统：

navigator.platform：string，返回操作系统平台（如 "Win32"、"MacIntel"、"Linux x86_64"）。
navigator.oscpu：string，返回操作系统详细版本（仅 Firefox 支持）。
navigator.language：string，返回浏览器首选语言（如 "zh-CN"）。
navigator.languages：string，返回用户偏好语言列表（按优先级排序）。

硬件与设备：

navigator.hardwareConcurrency：number，返回 CPU 核心数（用于优化多线程任务）。
navigator.deviceMemory：number，返回设备内存大小（以 GB 为单位，如 8，需 HTTPS）。
navigator.maxTouchPoints：number，返回设备支持的最大触控点数（检测触屏设备）。

网络与连接：

navigator.onLine：boolean，返回布尔值，表示浏览器是否联网。
navigator.connection：NetworkInformation，返回网络连接信息对象 NetworkInformation（如类型、速度、流量节省模式等，需 HTTPS）。

功能检测与权限：

navigator.cookieEnabled：boolean，返回布尔值，表示是否启用 Cookie。
navigator.permissions：Permissions，提供权限查询接口的 Permissions 对象（如地理位置、摄像头权限）。

地理位置：

navigator.geolocation：Geolocation，返回一个用于访问设备的地理位置的 Geolocation 对象。

剪切板：

navigator.clipboard：Clipboard，返回一个用于读写访问系统剪贴板内容的 Clipboard 对象。

Geolocation

方法：

navigator.geolocation.getCurrentPosition()：(successCallback,errorCallback?,options?)，用于获取用户设备当前位置的异步方法。
navigator.geolocation.watchPosition()：(successCallback,errorCallback?,options?)，用于持续监听用户设备位置变化的异步方法，当位置更新时会重复触发回调函数。
navigator.geolocation.clearWatch()：(watchID)，用于停止通过 watchPosition() 启动的持续位置监听。

Clipboard

方法：

navigator.clipboard.read()：()，用于异步读取剪贴板内容的现代 API，支持读取多种数据类型（如文本、图片等）。
navigator.clipboard.readText()：(text)，用于异步读取剪贴板中的纯文本内容。
navigator.clipboard.write()：(data)，用于异步向剪贴板写入多种数据类型（如文本、图片、HTML 等）的现代 API。

Navigator

属性

浏览器标识：

navigator.userAgent：string，返回浏览器的完整用户代理字符串（包含浏览器名称、版本、操作系统等信息）。

平台与操作系统：

navigator.platform：string，返回操作系统平台（如 "Win32"、"MacIntel"、"Linux x86_64"）。
navigator.oscpu：string，返回操作系统详细版本（仅 Firefox 支持）。
navigator.language：string，返回浏览器首选语言（如 "zh-CN"）。
navigator.languages：string，返回用户偏好语言列表（按优先级排序）。

硬件与设备：

navigator.hardwareConcurrency：number，返回 CPU 核心数（用于优化多线程任务）。
navigator.deviceMemory：number，返回设备内存大小（以 GB 为单位，如 8，需 HTTPS）。
navigator.maxTouchPoints：number，返回设备支持的最大触控点数（检测触屏设备）。

网络与连接：

navigator.onLine：boolean，返回布尔值，表示浏览器是否联网。
navigator.connection：NetworkInformation，返回网络连接信息对象 NetworkInformation（如类型、速度、流量节省模式等，需 HTTPS）。

功能检测与权限：

navigator.cookieEnabled：boolean，返回布尔值，表示是否启用 Cookie。
navigator.permissions：Permissions，提供权限查询接口的 Permissions 对象（如地理位置、摄像头权限）。

地理位置：

navigator.geolocation：Geolocation，返回一个用于访问设备的地理位置的 Geolocation 对象。

剪切板：

navigator.clipboard：Clipboard，返回一个用于读写访问系统剪贴板内容的 Clipboard 对象。

userAgent

navigator.userAgent：string，返回浏览器的完整用户代理字符串（包含浏览器名称、版本、操作系统等信息）。

示例：

console.log(navigator.userAgent); 
// 输出示例：Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36

connection

navigator.connection：NetworkInformation，返回网络连接信息对象 NetworkInformation（如类型、速度、流量节省模式等，需 HTTPS）。

示例：

const connection = navigator.connection;
console.log(connection.effectiveType); // "4g", "3g", "2g", "slow-2g"
console.log(connection.downlink); // 下载速度（Mbps）

permissions

navigator.permissions：Permissions，提供权限查询接口的 Permissions 对象（如地理位置、摄像头权限）。

示例：

navigator.permissions.query({ name: 'geolocation' })
  .then(permissionStatus => {
    console.log(permissionStatus.state); // "granted", "denied", "prompt"
  });

Geolocation

方法

getCurrentPosition()

navigator.geolocation.getCurrentPosition()：(successCallback,errorCallback?,options?)，用于获取用户设备当前位置的异步方法。

successCallback：(position)=>void，定位成功的回调函数。
- position：Position，接收一个 Position 对象作为参数。
errorCallback?：(errPosition)=>void，定位失败的回调函数。
- errPosition：{code,message}，定位设备位置时发生错误的原因。
options?：{enableHighAccuracy,timeout,maximumAge}，配置选项对象。
- enableHighAccuracy：boolean，默认：false，是否启用高精度定位（可能更耗电或更慢）。
- timeout：number，默认：Infinity，等待定位的最长时间（毫秒），超时后触发 errorCallback。
- maximumAge：number，默认：0，允许使用缓存位置的最大时间（毫秒）。若为 0，则强制获取实时位置。

特性：

Position 对象结构：

{
  coords: {
    latitude: number,          // 纬度（十进制）
    longitude: number,        // 经度（十进制）
    altitude: number | null,   // 海拔（米，设备不支持时为 `null`）
        
    accuracy: number,          // 经纬度精度（米，值越小越精确）
    altitudeAccuracy: number | null, // 海拔精度（米，设备不支持时为 `null`）
        
    speed: number | null,      // 速度（米/秒，设备不支持时为 `null`）
    heading: number | null     // 行进方向（相对于正北的度数，0~360，设备不支持时为 `null`）
  },
  timestamp: number           // 时间戳（Unix 毫秒数）
}

用户授权：首次调用会触发浏览器权限弹窗，用户必须同意后才能获取位置。
安全上下文：需在 HTTPS 协议下使用（本地 localhost 开发环境除外）。
兼容性：支持现代浏览器（IE9+ 部分支持，需 Polyfill）。
隐私保护：用户可随时在浏览器设置中撤销定位权限。

示例：

完整示例：

navigator.geolocation.getCurrentPosition(
  (position) => {
    const { latitude, longitude, accuracy } = position.coords;
    console.log(`纬度: ${latitude}, 经度: ${longitude}, 精度: ${accuracy} 米`);
  },
  (error) => {
    switch (error.code) {
      case error.PERMISSION_DENIED:
        console.error("用户拒绝授权或非安全环境（需 HTTPS）");
        break;
      case error.POSITION_UNAVAILABLE:
        console.error("无法获取位置信息");
        break;
      case error.TIMEOUT:
        console.error("定位超时");
        break;
    }
  },
  {
    enableHighAccuracy: true,
    timeout: 10000,
    maximumAge: 0
  }
);

watchPosition()

navigator.geolocation.watchPosition()：(successCallback,errorCallback?,options?)，用于持续监听用户设备位置变化的异步方法，当位置更新时会重复触发回调函数。

successCallback：(position)=>void，位置更新时的回调函数。
- position：Position，接收一个 Position 对象作为参数。
errorCallback?：(errPosition)=>void，定位失败的回调函数。
- errPosition：{code,message}，定位设备位置时发生错误的原因。
options?：{enableHighAccuracy,timeout,maximumAge}，配置选项对象。
- enableHighAccuracy：boolean，默认：false，是否启用高精度定位（可能更耗电或更慢）。
- timeout：number，默认：Infinity，等待定位的最长时间（毫秒），超时后触发 errorCallback。
- maximumAge：number，默认：0，允许使用缓存位置的最大时间（毫秒）。若为 0，则强制获取实时位置。
返回：
watchID：number，返回一个唯一标识符，用于后续通过 navigator.geolocation.clearWatch(watchID) 停止监听。

特性：

等价于 getCurrentPosition() 的特性

对比 getCurrentPosition()：

特性	`watchPosition()`	`getCurrentPosition()`
触发次数	持续触发（直到调用 `clearWatch()`）	仅触发一次
适用场景	实时追踪（如导航、运动记录）	单次定位（如获取初始位置）
返回值	返回 `watchID`（用于停止监听）	无返回值

超时错误：超时（timeout）仅针对单次定位尝试，监听会继续等待后续更新。

示例：

完整示例：

// 开始监听位置变化
const watchID = navigator.geolocation.watchPosition(
  (position) => {
    const { latitude, longitude } = position.coords;
    console.log(`当前位置：纬度 ${latitude}, 经度 ${longitude}`);
  },
  (error) => {
    console.error(`定位失败（错误码 ${error.code}）: ${error.message}`);
  },
  {
    enableHighAccuracy: true,
    timeout: 5000,
    maximumAge: 30000
  }
);

// 停止监听（如用户离开页面或手动取消）
// navigator.geolocation.clearWatch(watchID);

clearWatch()

navigator.geolocation.clearWatch()：(watchID)，用于停止通过 watchPosition() 启动的持续位置监听。

watchID：number，由 watchPosition() 返回的唯一标识符，用于指定要停止的监听任务。
特性：
1. 必需参数：必须传入有效的 watchID，否则无法停止监听。若未正确保存 watchID，将无法终止任务。
2. 与 watchPosition() 的关联：
  - 每个 watchPosition() 调用会生成唯一的 watchID，需保存以便后续清理。
  - 未调用 clearWatch() 的监听会持续占用资源，可能导致性能问题。
3. 错误处理：
  - 如果用户未授权定位权限或环境不安全（非 HTTPS），watchPosition() 会直接触发错误回调，无需调用 clearWatch()。
  - 监听停止后，successCallback 和 errorCallback 将不再触发。
4. 兼容性：
  - 支持所有实现了 watchPosition() 的浏览器（现代浏览器及 IE11+）。
  - 在已废弃的浏览器（如旧版 IE）中可能不可用，需检测 navigator.geolocation 是否存在。

示例：

基本用法：

// 启动位置监听，获取 watchID
const watchID = navigator.geolocation.watchPosition(
  (position) => {
    console.log("位置更新：", position.coords);
  },
  (error) => {
    console.error("定位失败：", error.message);
  }
);

// 在需要时停止监听（如按钮点击事件）
document.getElementById("stopButton").addEventListener("click", () => {
  navigator.geolocation.clearWatch(watchID);
  console.log("已停止位置监听");
});

Clipboard

方法

read()

navigator.clipboard.read()：()，用于异步读取剪贴板内容的现代 API，支持读取多种数据类型（如文本、图片等）。

返回：
clipboardItems：Promise<ClipboardItem[]>，返回一个 Promise，解析为包含剪贴板内容的 ClipboardItem 对象数组。
特性：
1. ClipboardItem 对象结构：
  js
```
{
  types: Array<string>,          // 支持的 MIME 类型列表，如 ["text/plain", "image/png"]
  getType(type: string): Promise<Blob>  // 根据 MIME 类型获取数据（返回 Blob）
}
```
  1
  2
  3
  4
2. 用户授权：需用户主动授予剪贴板读取权限（浏览器会弹出权限请求）。
3. 权限策略：可通过 Permissions API 查询剪贴板权限状态：
  js
```
const status = await navigator.permissions.query({ name: "clipboard-read" });
console.log(status.state); // "granted", "denied", "prompt"
```
  1
  2
4. 安全上下文：必须在 HTTPS 或本地环境（localhost）中运行。
5. 用户交互触发：必须在用户主动操作（如点击按钮）中调用，否则浏览器可能拒绝。
6. 对比 readText()：
  方法功能返回值
  read() 读取所有类型数据（文本、图片） ClipboardItem[]
  readText() 仅读取文本 string

方法	功能	返回值
`read()`	读取所有类型数据（文本、图片）	`ClipboardItem[]`
`readText()`	仅读取文本	`string`

示例：

读取剪贴板中的文本：

async function readClipboardText() {
  try {
    const clipboardItems = await navigator.clipboard.read();
    for (const item of clipboardItems) {
      // 检查是否包含文本类型
      if (item.types.includes("text/plain")) {
        const textBlob = await item.getType("text/plain");
        const text = await textBlob.text();
        console.log("剪贴板文本内容:", text);
      }
    }
  } catch (error) {
    console.error("读取剪贴板失败:", error);
  }
}

读取剪贴板中的图片：

URL.createObjectURL()：(object)，用于为 Blob 或 File 对象生成临时 URL 的方法，允许在浏览器中直接引用本地文件或内存中的数据（如图片、视频、二进制流等）。

async function readClipboardImage() {
  try {
    const clipboardItems = await navigator.clipboard.read();
    for (const item of clipboardItems) {
      // 检查是否包含 PNG 图片
      if (item.types.includes("image/png")) {
        const imageBlob = await item.getType("image/png");
        const imageUrl = URL.createObjectURL(imageBlob);
        const img = document.createElement("img");
        img.src = imageUrl;
        document.body.appendChild(img);
      }
    }
  } catch (error) {
    console.error("读取剪贴板图片失败:", error);
  }
}

readText()

navigator.clipboard.readText()：(text)，用于异步读取剪贴板中的纯文本内容。

返回：
text：Promise<string>，返回一个 Promise，解析为剪贴板中的文本字符串。若剪贴板内容为非文本（如图片）或剪贴板为空，则返回空字符串 ""。
特性：与 read() 一致。

示例：

基础读取：

async function readClipboardText() {
  try {
    const text = await navigator.clipboard.readText();
    console.log("剪贴板内容:", text);
  } catch (error) {
    console.error("读取失败:", error);
  }
}

// 在按钮点击事件中触发
document.querySelector("#pasteButton").addEventListener("click", readClipboardText);

错误处理：

async function readTextSafely() {
  try {
    const text = await navigator.clipboard.readText();
    if (text === "") {
      console.log("剪贴板为空或内容非文本");
    } else {
      console.log("成功读取文本:", text);
    }
  } catch (error) {
    if (error.name === "NotAllowedError") {
      console.error("用户拒绝授权或非安全环境");
    } else {
      console.error("未知错误:", error);
    }
  }
}

write()

navigator.clipboard.write()：(data)，用于异步向剪贴板写入多种数据类型（如文本、图片、HTML 等）的现代 API。

data：ClipboardItem[]，要写入的包含剪贴板数据项的数组。
返回：
result：Promise<void>，写入成功时 Promise 完成，失败时抛出错误（需捕获处理）。
特性：与 read() 一致。

示例：

写入纯文本：

async function writeTextToClipboard() {
  const text = "这是要复制的文本";
  const clipboardItem = new ClipboardItem({
    "text/plain": new Blob([text], { type: "text/plain" })
  });
  try {
    await navigator.clipboard.write([clipboardItem]);
    console.log("文本已复制到剪贴板");
  } catch (error) {
    console.error("复制失败:", error);
  }
}

写入图片（PNG）：

async function writeImageToClipboard() {
  // 从 URL 获取图片 Blob
  const response = await fetch("image.png");
  const imageBlob = await response.blob();
  
  const clipboardItem = new ClipboardItem({
    "image/png": imageBlob
  });
  
  try {
    await navigator.clipboard.write([clipboardItem]);
    console.log("图片已复制到剪贴板");
  } catch (error) {
    console.error("复制图片失败:", error);
  }
}

写入混合内容（文本 + HTML）：

async function writeRichContent() {
  const textBlob = new Blob(["纯文本内容"], { type: "text/plain" });
  const htmlBlob = new Blob(["<b>富文本内容</b>"], { type: "text/html" });
  
  const clipboardItem = new ClipboardItem({
    "text/plain": textBlob,
    "text/html": htmlBlob
  });
  
  try {
    await navigator.clipboard.write([clipboardItem]);
    console.log("富文本已复制");
  } catch (error) {
    console.error("复制失败:", error);
  }
}

writeText()

navigator.clipboard.writeText()：(text)，用于异步将纯文本内容写入剪贴板的 API，适用于简单的文本复制场景。

text：string，要写入剪贴板的文本内容。若传入非字符串值（如数字、对象），会尝试自动转换为字符串。
返回：
result：Promise<void>，写入成功时 Promise 完成，失败时抛出错误（需捕获处理）。
特性：
1. 与 read() 一致。
2. 自动类型转换
  - 非字符串参数（如数字、布尔值）会自动调用 toString() 转换为字符串。
  - 复杂对象（如数组、对象）可能转换为无用字符串（如 "[object Object]"），需手动处理。

示例：

基础写入：

async function copyTextToClipboard() {
  const text = "这是要复制的文本";
  try {
    await navigator.clipboard.writeText(text);
    console.log("文本已复制到剪贴板");
  } catch (error) {
    console.error("复制失败:", error);
  }
}

// 在按钮点击事件中触发
document.querySelector("#copyButton").addEventListener("click", copyTextToClipboard);

错误处理：

async function safeCopyText() {
  try {
    await navigator.clipboard.writeText(12345); // 数字会被转为字符串 "12345"
    console.log("复制成功");
  } catch (error) {
    if (error.name === "NotAllowedError") {
      console.error("权限被拒绝或非安全环境");
    } else if (error.name === "TypeError") {
      console.error("参数类型错误");
    } else {
      console.error("未知错误:", error);
    }
  }
}

Navigator ​

索引 ​

Navigator ​

Geolocation ​

Clipboard ​

Navigator ​

属性 ​

userAgent ​

connection ​

permissions ​

Geolocation ​

方法 ​

getCurrentPosition() ​

watchPosition() ​

clearWatch() ​

Clipboard ​

方法 ​

read() ​

readText() ​

write() ​

writeText() ​

Navigator

索引

Navigator

Geolocation

Clipboard

Navigator

属性

userAgent

connection

permissions

Geolocation

方法

getCurrentPosition()

watchPosition()

clearWatch()

Clipboard

方法

read()

readText()

write()

writeText()