Navigator | AIUI | Rokid

提供运行环境中的 navigator 相关能力,作为宿主标识、语言偏好、运行时版本与设备邻接能力的统一入口。

Navigator

提供运行环境中的 navigator 相关能力,作为宿主标识、语言偏好、运行时版本与设备邻接能力的统一入口。

读取运行环境与语言信息

在启动时读取语言、区域和运行时版本,用于选择本地化配置并记录诊断信息:

const environment = {
  language: navigator.language,
  languages: navigator.languages,
  region: navigator.region,
  inkVersion: navigator.versions.ink,
  skiaVersion: navigator.versions.skia,
};

console.log(environment);

读取电池并访问持久化文件

const battery = await navigator.getBattery();
const root = await navigator.storage.getDirectory();

console.log('battery:', battery.level);
console.log('storage root:', root.name);

注意事项

  • navigator.getDeviceSerialNumber() 返回的是宿主提供的设备序列号,若宿主未实现则返回空字符串;使用时应注意隐私与数据安全。
  • navigator.userAgent 适合用于识别运行时与平台信息,不建议依赖字符串解析实现强耦合逻辑。
  • navigator.language、navigator.languages 与 navigator.region 都来自宿主环境,不同平台的具体值格式可能不同。
  • navigator.bluetooth、navigator.geolocation、navigator.mediaDevices、navigator.storage 与电池状态都依赖设备能力和 Agent 权限。

观察网络连接

function updateNetworkState() {
  const connection = navigator.connection;
  console.log(navigator.onLine, connection.type, connection.effectiveType);
}
updateNetworkState();
navigator.connection.addEventListener('change', updateNetworkState);

onLine 表示当前在线状态,connection 提供连接类型与质量元数据。在线状态不保证某个地址可达;请求和连接仍需处理错误。质量未知时应回退到应用自己的超时与重试策略。

网络请求通过蓝牙链路转发时,连接类型可以为 'bluetooth'。

读取权限状态

使用 navigator.permissions.query({ name: 'microphone' }) 读取当前权限,不开始采集或弹出授权界面。支持的名称、实时变化通知及声明与授权的区别,详见权限状态。

API Reference

属性

navigator.permissions

只读权限查询对象。query(descriptor) 返回定位、相机或麦克风的实时状态,不发起授权申请;详见权限状态。

navigator.onLine

只读的 boolean,表示当前运行环境的在线状态。

navigator.connection

持久化的 NetworkInformation / EventTarget 对象,反复读取返回同一对象。

navigator.userAgent

  • 类型:string,只读。
  • 说明:返回 AIUI 运行时使用的 User-Agent,包含运行时及可用的平台信息;不要将具体字符串格式作为兼容性契约。
  • 行为:该值也用于网络层发送的 HTTP User-Agent 请求头。应将其用于能力识别和诊断,不要依赖字符串解析来实现强耦合逻辑。
const userAgent = navigator.userAgent;
console.log('UA:', userAgent);

navigator.id

  • 类型:string,只读。
  • 说明:返回当前 Agent 在当前设备上的不透明标识。它的作用域由 Agent 与设备共同决定:同一个 Agent 在同一设备上通常得到相同的值;同一设备上的不同 Agent,或不同设备上的同一 Agent,得到不同的值。
const agentDeviceId = navigator.id;
console.log('Agent device ID:', agentDeviceId);

该值通常以 cid_ 开头,由运行时根据 Agent 身份与设备侧身份材料派生。它不是 Agent URL、文件路径、设备序列号、MAC 地址或其他原始硬件标识,也不应解析其内容或依赖其具体格式。

在设备侧身份材料未被清除的情况下,navigator.id 会在应用正常重启和升级后保持稳定。恢复出厂设置、清除或丢失宿主身份数据,或宿主更换用于派生标识的设备身份材料时,该值可能变化。没有当前应用实例时返回空字符串 ''。

建议仅将它用于同一 Agent 范围内的本地数据关联、设备侧状态恢复或诊断。不要将其用作认证凭据,也不要假设它永久不变;如需上传或跨服务保存,应按设备标识信息采取适当的隐私与安全保护。

navigator.language

  • 类型:string,只读。
  • 说明:返回 navigator.languages 的第一个有效值,即宿主当前首选语言。宿主没有配置语言时返回 ''。
const language = navigator.language;
console.log('Language:', language);

navigator.languages

  • 类型:string[],只读。
  • 说明:返回宿主提供的按优先级排列的语言偏好列表。运行时会去除首尾空白和空值;宿主没有配置语言时返回空数组 []。应用可按该顺序实现本地化兜底。
  • 多语言匹配:语言标签遵循 IETF BCP 47 标准(如 zh-CN、zh-TW、zh-HK)。做多语言文案匹配时,建议按 BCP 47 / RFC 4647 Lookup 语义处理:从完整标签开始逐步截断末尾子标签进行匹配(如 zh-Hant-TW → zh-Hant → zh),并结合文字系统与地区子标签区分简繁体(zh-Hans*、zh-SG 等归入简体,zh-Hant*、zh-TW、zh-HK、zh-MO 归入繁体),全部未命中时回退默认语言。
const languages = navigator.languages;
console.log('Languages:', languages);

完整的 BCP 47 语言匹配实现可参考示例 samples/navigator-info:它按 navigator.languages 优先级解析界面语言,自动切换简体中文 / 繁体中文 / 英文三套文案。

navigator.region

  • 类型:string,只读。
  • 说明:返回宿主提供的区域字符串,运行时会去除首尾空白;宿主没有配置区域时返回 ''。具体格式由宿主决定,可用于地区化配置或服务分流。
const region = navigator.region;
console.log('Region:', region);

navigator.versions.ink

  • 类型:string,只读。
  • 说明:返回当前 AIUI 运行时版本字符串。构建时可由宿主覆盖,用于日志、问题排查和兼容性判断;不应将其当作业务版本号。
const inkVersion = navigator.versions.ink;
console.log('Runtime:', inkVersion);

navigator.versions.skia

  • 类型:string,只读。
  • 说明:返回当前 Skia 图形引擎 milestone 字符串,例如 m126。适合用于图形渲染问题排查,不代表 AIUI 应用或运行时的版本号。

navigator.renderingEnabled

  • 类型:boolean,只读。
  • 说明:表示当前实例是否具备模板、布局和渲染能力。普通窗口实例与离屏渲染实例通常为 true;无显示实例为 false。该值在实例生命周期内保持不变。
const skiaVersion = navigator.versions.skia;
console.log('Skia:', skiaVersion);

navigator.bluetooth

  • 类型:Bluetooth。
  • 说明:蓝牙能力入口,用于发现设备、建立连接和访问 GATT 服务。对象会挂载在 navigator 上,但具体操作仍取决于宿主能力、权限和设备状态;完整接口见蓝牙。
const bluetooth = navigator.bluetooth;
console.log('Bluetooth mounted:', !!bluetooth);

navigator.geolocation

  • 类型:Geolocation。
  • 说明:地理位置能力入口,用于读取当前位置、监听位置变化和清理监听。使用前需要获得定位权限;完整接口见 Geolocation。
const geolocation = navigator.geolocation;
console.log('Geolocation mounted:', !!geolocation);

navigator.mediaDevices

  • 类型:MediaDevices。
  • 说明:媒体采集入口,提供 getUserMedia()、enumerateDevices() 与 getSupportedConstraints()。摄像头和麦克风访问取决于宿主权限及设备能力;完整用法见媒体采集。

navigator.storage

  • 类型:StorageManager。
  • 说明:当前 Agent 私有 OPFS 的存储入口。宿主未提供 OPFS 后端时,相关方法会以 NotSupportedError 失败;完整用法见 OPFS。

方法

navigator.getDeviceSerialNumber()

  • 返回值:string。
  • 说明:返回宿主提供的当前设备序列号。该能力仅对系统 Agent 返回宿主值,其他 Agent 或宿主未提供时返回空字符串 ''。这是敏感设备信息,应限制使用范围。
const serialNumber = navigator.getDeviceSerialNumber();
console.log('SN:', serialNumber);

navigator.getBattery()

  • 返回值:Promise<BatteryManager>。
  • 说明:异步获取宿主电池管理器,用于读取电量、充电状态和预计剩余时长,并监听变化。宿主未注册电池能力时 Promise 会拒绝;完整行为见 BatteryManager。
  • 相关文档:BatteryManager。

NetworkInformation

connection.type

类型: string. 连接类型:none、wifi、ethernet、cellular、bluetooth、other、unknown。

connection.effectiveType

类型: string. 有效连接质量:slow-2g、2g、3g、4g 或 unknown,不是蜂窝制式标识。

connection.downlink

类型: number. 估算下行速率,单位 Mbps,未知时为 0;不应用于精确测速。

connection.rtt

类型: number. 估算往返时延,单位毫秒,未知时为 0;不是对当前请求的实时测量。

connection.saveData

类型: boolean. 是否启用节省流量偏好,默认 false。

change

类型: Event. 连接状态更新时触发。使用 addEventListener('change', listener) 监听,并在结束时移除监听。