更新记录

1.0.1（2026-07-22）

首个版本，已支持：

• 设备 ID 获取
• 音量获取
• 亮度获取
• 电量获取
• WiFi 信息获取
• Android AAR + UTS 封装接入

平台兼容性

uni-app x(5.07)

fzd-device-info

一个基于 UTS + Android AAR 封装的设备信息读取插件，适用于 uni-app x 的 Android 端。

当前插件主要用于读取设备基础状态信息，并提供一个统一的 getDeviceInfo() 方法给页面直接调用。

功能简介

插件当前支持获取以下信息：

• 设备 ID
• 当前媒体音量
• 最大媒体音量
• 屏幕亮度
• 当前电量百分比
• 是否处于充电状态
• 当前连接 WiFi 的名称
• WiFi 信号等级
• WiFi 的 RSSI 值

该插件底层通过 Android 原生代码实现，原生能力已封装在 AAR 中，UTS 侧仅负责做能力暴露和数据转换。

适用平台

• Android
• uni-app x

当前版本未实现 iOS 端能力。

插件对外 API

getDeviceInfo()

同步获取设备信息。

调用方式

import { getDeviceInfo } from '@/uni_modules/fzd-device-info'

const info = getDeviceInfo()
console.log(info)

返回值

返回一个对象，结构如下：

type DeviceInfoResult = {
  deviceId: string | null
  currentVolume: number
  maxVolume: number
  brightness: number
  batteryLevel: number
  charging: boolean
  wifiSsid: string | null
  wifiSignalLevel: number
  wifiRssi: number
}

字段说明

实现原理

插件通过 UTSAndroid.getAppContext() 获取 Android 应用上下文，然后调用 AAR 中的原生类：

com.fengzd.deviceinfo.DeviceInfoHelper

核心方法为：

getAllDeviceInfo()

该方法会一次性返回设备信息对象，UTS 层再将原生对象转换为页面可直接使用的普通对象。

原生 AAR 依赖

当前插件已经接入以下 AAR：

uni_modules/fzd-device-info/utssdk/app-android/libs/deviceinfo-v1.0.1.aar

AAR 中至少需要包含以下类：

• com.fengzd.deviceinfo.DeviceInfoHelper
• DeviceInfoHelper#getAllDeviceInfo() 依赖的 DeviceInfo

如果后续你替换了新的 AAR，只要包名、类名、方法名不变，插件代码通常不需要改动。

如果 AAR 中的包名或类名发生变化，需要同步修改：

• utssdk/app-android/index.uts

权限说明

插件在 Android 端声明了以下权限：

• android.permission.ACCESS_WIFI_STATE
• android.permission.ACCESS_NETWORK_STATE
• android.permission.ACCESS_FINE_LOCATION
• android.permission.READ_PHONE_STATE

对应配置文件：

• utssdk/app-android/AndroidManifest.xml

为什么需要这些权限

• ACCESS_WIFI_STATE：读取 WiFi 连接状态、SSID、RSSI
• ACCESS_NETWORK_STATE：读取网络连接状态
• ACCESS_FINE_LOCATION：部分 Android 版本读取 WiFi 名称时必须具备定位权限
• READ_PHONE_STATE：低版本 Android 获取设备标识时可能会使用到

使用示例

页面中直接调用

import { getDeviceInfo } from '@/uni_modules/fzd-device-info'

const loadDeviceInfo = () => {
  const result = getDeviceInfo()
  console.log('设备信息', result)
}

onLoad(() => {
  loadDeviceInfo()
})

典型返回示例

{
  "deviceId": "7b1f4c9a12xx89ab",
  "currentVolume": 8,
  "maxVolume": 15,
  "brightness": 134,
  "batteryLevel": 82,
  "charging": false,
  "wifiSsid": "Office-WiFi",
  "wifiSignalLevel": 3,
  "wifiRssi": -58
}

目录结构说明

uni_modules/fzd-device-info
├─ package.json
├─ readme.md
└─ utssdk
   ├─ interface.uts
   ├─ index.uts
   └─ app-android
      ├─ AndroidManifest.xml
      ├─ config.json
      ├─ index.uts
      └─ libs
         └─ deviceinfo-v1.0.1.aar

目录用途

• package.json：插件基础描述信息
• readme.md：插件使用说明文档
• utssdk/interface.uts：声明插件对外暴露的数据类型和方法类型
• utssdk/index.uts：跨平台默认入口，当前用于兜底返回
• utssdk/app-android/index.uts：Android 平台的具体实现
• utssdk/app-android/AndroidManifest.xml：Android 权限声明
• utssdk/app-android/config.json：Android 构建配置
• utssdk/app-android/libs：原生 AAR 依赖目录

注意事项

1. WiFi 名称不一定能取到

在部分 Android 版本上，即使已经声明权限，以下情况仍可能导致 wifiSsid 为空：

• 用户未授权定位权限
• 系统定位开关未开启
• 当前未连接 WiFi
• 系统 ROM 对 WiFi 信息做了额外限制

2. 设备 ID 会受 Android 版本影响

插件底层逻辑如下：

• Android 10 及以上：优先使用 Settings.Secure.ANDROID_ID
• Android 10 以下：尝试读取 TelephonyManager#getDeviceId()
• 若读取失败：回退为 ANDROID_ID

因此不同设备、不同系统版本下，deviceId 的值和可用性会有差异。

3. 亮度为系统当前亮度值

这里返回的是系统亮度整数值，不是百分比。常见范围为 0-255。

4. 当前仅支持 Android

如果页面需要跨平台运行，建议调用前先判断平台，或者在非 Android 平台做兼容提示。

常见问题

Q1：编译时报找不到 DeviceInfoHelper

请检查：

• AAR 是否存在于 utssdk/app-android/libs/
• AAR 内的包名和类名是否为 com.fengzd.deviceinfo.DeviceInfoHelper
• AAR 内是否包含依赖的 DeviceInfo 类

Q2：页面能打开，但 WiFi 名称为空

请检查：

• App 是否已获得定位权限
• 手机系统定位开关是否打开
• 设备是否真的连接了 WiFi

Q3：电量、亮度、音量能获取，但设备 ID 为空

这是系统版本、权限策略或 ROM 差异导致的正常现象，建议以 ANDROID_ID 作为主要设备标识方案。

更新建议

如果后续要继续扩展插件，建议增加以下能力：

• 单独导出各字段的获取方法，如 getBatteryLevel()、getWifiInfo()
• 增加权限申请辅助方法
• 增加监听能力，如电量变化监听、WiFi 状态监听
• 增加 iOS 端实现，统一跨平台返回结构

版本说明

1.0.0

首个版本，已支持：

• 设备 ID 获取
• 音量获取
• 亮度获取
• 电量获取
• WiFi 信息获取
• Android AAR + UTS 封装接入