快速入门

兼容性

@capgo/capacitor-device-info 需要 Capacitor 8 或更高版本 (@capacitor/core >=8.0.0).

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-device-info` plugin in my project.

如需手动设置，请安装该 package 并同步原生项目：

npm install @capgo/capacitor-device-info
npx cap sync

导入

import { DeviceInfo } from '@capgo/capacitor-device-info';

快速入门

import { DeviceInfo } from '@capgo/capacitor-device-info';

const result = await DeviceInfo.getInfo();
console.log(result);

示例：startMonitoring

import { DeviceInfo } from '@capgo/capacitor-device-info';

const result = await DeviceInfo.startMonitoring();
console.log(result);

示例：stopMonitoring

import { DeviceInfo } from '@capgo/capacitor-device-info';

const result = await DeviceInfo.stopMonitoring();
console.log(result);

常见坑点

• 监听器: 在页面卸载时移除句柄。
• 原生同步：运行 npx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

读取单个快照

const snapshot = await DeviceInfo.getInfo();

console.log(snapshot.cpu.cores);
console.log(snapshot.memory.usedPercent);
console.log(snapshot.storage.freeBytes);
console.log(snapshot.sensors?.pressureHpa);

cpu.usagePercent 是基于增量的。第一个原生采样可以省略它；稍后再次调用 getInfo() 或使用监控功能，在第二次采样后获取有值的 CPU 使用率。

流式更新

const handle = await DeviceInfo.addListener('deviceInfoUpdate', (sample) => {
  console.log(sample.sequence, sample.elapsedMs);
  console.log(sample.cpu.usagePercent);
  console.log(sample.sensors?.readings);
});

const session = await DeviceInfo.startMonitoring({
  intervalMs: 1000,
  emitImmediately: true,
});

console.log(session.intervalMs, session.startedAt);

监控行为

• intervalMs 默认为 1000 毫秒。低于 250 毫秒的值会被限制为 250.
• emitImmediately 默认为 true.
• 设置 durationMs 或 sampleCount 以自动停止监控。
• 正在调用 startMonitoring() 在监控激活期间，使用新选项重启会话。
• 每次 deviceInfoUpdate 包含一个基于 1 的 sequence，该会话的 startedAt 时间戳，以及 elapsedMs.

停止更新并移除监听器

await DeviceInfo.stopMonitoring();
await handle.remove();

// Or remove every listener registered on this plugin:
await DeviceInfo.removeAllListeners();

检查监控状态

const state = await DeviceInfo.isMonitoring();

if (state.monitoring) {
  console.log(state.samplesEmitted);
}

接入传感器字段

const { sensors, cpu, gpu } = await DeviceInfo.getInfo();

console.log(cpu.temperatureCelsius);
console.log(gpu?.temperatureCelsius);
console.log(sensors?.batteryTemperatureCelsius);
console.log(sensors?.ambientTemperatureCelsius);
console.log(sensors?.relativeHumidityPercent);
console.log(sensors?.pressureHpa);
console.log(sensors?.illuminanceLux);
console.log(sensors?.proximityDistanceCm);
console.log(sensors?.availableSensors);

传感器字段是可选的。仅当设备、操作系统和应用沙箱暴露该指标时，才会存在这些字段。

平台说明

• iOS 无需权限即可获取已暴露的指标。它会报告 CoreMotion 传感器的可用性，但不报告原始 CPU 或 GPU 温度。
• Android 无需权限即可获取已暴露的指标。CPU 和 GPU 温度是通过热区读取的最佳努力值。
• Web 端支持为尽力而为，会返回空的板载传感器数组，因为浏览器无法一致地暴露原生设备传感器。

API 参考文档

方法	返回	备注
getInfo()	Promise<DeviceInfoSnapshot>	读取一次快照。
startMonitoring(options?)	Promise<StartMonitoringResult>	启动周期性快照，或用新选项重启当前会话。
stopMonitoring()	Promise<StopMonitoringResult>	停止当前会话。
isMonitoring()	Promise<MonitoringState>	返回当前会话状态。
addListener('deviceInfoUpdate', listener)	Promise<PluginListenerHandle>	注册周期性快照监听器。
removeAllListeners()	Promise<void>	移除插件上注册的所有监听器。
getPluginVersion()	Promise<PluginVersionResult>	读取原生插件版本。

PluginListenerHandle 由 Capacitor 提供，并且具有 remove() 用于移除该特定监听器。

快照类型

interface CpuInfo {
  cores: number;
  activeCores?: number;
  architecture?: string;
  model?: string;
  usagePercent?: number | null;
  maxFrequencyHz?: number;
  temperatureCelsius?: number;
}

interface MemoryInfo {
  totalBytes?: number;
  freeBytes?: number;
  usedBytes?: number;
  usedPercent?: number;
  appUsedBytes?: number;
  appLimitBytes?: number;
  lowMemory?: boolean;
  pressure?: 'normal' | 'warning' | 'critical' | 'unknown';
}

interface StorageInfo {
  totalBytes?: number;
  freeBytes?: number;
  usedBytes?: number;
  usedPercent?: number;
}

interface GpuInfo {
  api?: 'metal' | 'opengl' | 'webgl' | 'unknown';
  vendor?: string;
  renderer?: string;
  version?: string;
  maxTextureSize?: number;
  temperatureCelsius?: number;
}

type ThermalState = 'nominal' | 'fair' | 'serious' | 'critical' | 'unknown';

interface DeviceInfoSnapshot {
  timestamp: number;
  platform: 'ios' | 'android' | 'web';
  cpu: CpuInfo;
  memory: MemoryInfo;
  storage: StorageInfo;
  gpu?: GpuInfo;
  thermalState?: ThermalState;
  lowPowerMode?: boolean;
  sensors?: OnboardSensorsInfo;
}

大小单位为字节， maxFrequencyHz 频率单位为赫兹，温度值为摄氏度。 usagePercent 可以 null 直到平台收集到足够样本以进行计算。

传感器类型

interface OnboardSensorDescriptor {
  type: string;
  name?: string;
  vendor?: string;
  platformType?: number;
  maximumRange?: number;
  resolution?: number;
  powerMilliamp?: number;
  minDelayMicroseconds?: number;
  wakeUp?: boolean;
}

interface OnboardSensorReading {
  type: string;
  unit: string;
  value: number;
  name?: string;
  timestamp?: number;
}

interface OnboardSensorsInfo {
  availableSensors?: OnboardSensorDescriptor[];
  readings?: OnboardSensorReading[];
  batteryTemperatureCelsius?: number;
  ambientTemperatureCelsius?: number;
  relativeHumidityPercent?: number;
  pressureHpa?: number;
  illuminanceLux?: number;
  proximityDistanceCm?: number;
}

传感器读数时间戳为 Unix 纪元毫秒。常用单位包括摄氏度、百分比、hPa、勒克斯和厘米。

监控类型

interface MonitoringOptions {
  intervalMs?: number;
  durationMs?: number;
  sampleCount?: number;
  emitImmediately?: boolean;
}

interface StartMonitoringResult {
  monitoring: boolean;
  intervalMs: number;
  startedAt: number;
}

interface StopMonitoringResult {
  monitoring: boolean;
}

interface MonitoringState {
  monitoring: boolean;
  intervalMs?: number;
  startedAt?: number;
  samplesEmitted?: number;
}

interface DeviceInfoUpdate extends DeviceInfoSnapshot {
  sequence: number;
  startedAt: number;
  elapsedMs: number;
}

interface PluginVersionResult {
  version: string;
}

startedAt, timestamp，以及 elapsedMs 是毫秒。 sequence 从 1 开始，针对每个监控会话。

唯一可信来源

本参考文档遵循该插件中的公开 API src/definitions.ts。当该来源变更时，请更新此页面。

从入门指南继续

如果你正在使用 快速入门 用于设备诊断，请将其与 @capgo/capacitor-device-info 查看概览， 使用 @capgo/capacitor-device-info 用于教程页面， @capgo/capacitor-barometer 用于精确的压力读数，以及 @capgo/capacitor-light-sensor 用于获取专注的光传感器读数。