更新记录

1.0.0（2026-08-26）

• 设备信息、电量信息，字段对齐 HarmonyOS
• App 端支持蓝牙状态查询与开关
• 覆盖 Android / iOS / HarmonyOS / 小程序 / 元服务
• 按 API 拆分模块，支持摇树

平台兼容性

uni-app(4.83)

uni-app x(4.83)

umi-device-kit

基于 UTS 的多端设备与电量信息插件，字段分别对齐：

• HarmonyOS @ohos.deviceInfo
• HarmonyOS @ohos.batteryInfo

支持平台

ASCF 元服务不支持 UTS 原生鸿蒙 API，请通过 mp-harmony 目录下的 uni API 实现。

使用方法

导入

import {
  getDeviceInfo,
  getDeviceInfoSync,
  getBatteryInfo,
  getBatteryInfoSync,
  GetDeviceInfoOptions,
  GetBatteryInfoOptions
} from '@/uni_modules/umi-device-kit'

获取设备信息

同步

const deviceInfo = getDeviceInfoSync()

console.log(deviceInfo.platform)       // android | ios | harmony | mp-weixin ...
console.log(deviceInfo.brand)          // 品牌
console.log(deviceInfo.productModel)   // 认证型号
console.log(deviceInfo.osFullName)     // 系统版本全称
console.log(deviceInfo.deviceType)     // phone | pad | pc ...

异步

getDeviceInfo({
  success(res) {
    console.log(res.errMsg)            // getDeviceInfo:ok
    console.log(res.deviceInfo)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9010001
  },
  complete(res) {
    console.log('complete', res)
  }
} as GetDeviceInfoOptions)

获取电量信息

同步

const batteryInfo = getBatteryInfoSync()

console.log(batteryInfo.level)              // 0-100
console.log(batteryInfo.isCharging)           // true | false
console.log(batteryInfo.chargingStatus)       // none | enable | disable | full
console.log(batteryInfo.voltage)              // 微伏，无法获取为 -1
console.log(batteryInfo.batteryTemperature)   // 摄氏度，无法获取为 -1

异步

getBatteryInfo({
  success(res) {
    console.log(res.errMsg)            // getBatteryInfo:ok
    console.log(res.batteryInfo.level, res.batteryInfo.isCharging)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9010002
  },
  complete(res) {
    console.log('complete', res)
  }
} as GetBatteryInfoOptions)

uni-app x 页面示例

<template>
  <view class="page">
    <text>品牌：{{ device.brand }}</text>
    <text>型号：{{ device.productModel }}</text>
    <text>系统：{{ device.osFullName }}</text>
    <text>电量：{{ battery.level }}%</text>
    <text>充电：{{ battery.isCharging ? '是' : '否' }}</text>
    <button @click="refresh">刷新</button>
  </view>
</template>

<script setup lang="uts">
  import {
    getDeviceInfoSync,
    getBatteryInfoSync,
    DeviceInfo,
    BatteryInfo
  } from '@/uni_modules/umi-device-kit'

  const device = ref<DeviceInfo>(getDeviceInfoSync())
  const battery = ref<BatteryInfo>(getBatteryInfoSync())

  function refresh() {
    device.value = getDeviceInfoSync()
    battery.value = getBatteryInfoSync()
  }
</script>

错误码

DeviceInfo 字段说明

GetDeviceInfoSuccess（异步成功回调）

BatteryInfo 字段说明

GetBatteryInfoSuccess（异步成功回调）

平台字段支持差异

无法获取的字符串字段返回 ''，数值字段返回 -1，布尔字段返回 false。

摇树优化（Tree Shaking）

本插件支持摇树优化：业务代码中实际 import 的 API 及其依赖才会被打包，未使用的 API 不会增加包体积。

原理

1. 按 API 拆分模块：设备信息与电量信息分别独立文件，互不引用

utssdk/
├── app-android/
│   ├── device-info.uts    # getDeviceInfo / getDeviceInfoSync
│   ├── battery-info.uts   # getBatteryInfo / getBatteryInfoSync
│   └── index.uts          # 聚合导出
├── common/
│   ├── device-info-mp.uts
│   └── battery-info-mp.uts
└── ...

2. 按需 import：使用具名导入，只引入需要的 API

// ✅ 仅打包设备信息相关代码（不含 BatteryManager 等电量依赖）
import { getDeviceInfoSync } from '@/uni_modules/umi-device-kit'

// ✅ 仅打包电量信息相关代码
import { getBatteryInfoSync } from '@/uni_modules/umi-device-kit'

// ⚠️ 同时 import 两个 API 则两者均会打包
import { getDeviceInfoSync, getBatteryInfoSync } from '@/uni_modules/umi-device-kit'

3. package.json 配置：已开启各平台摇树

"treeShaking": {
  "app": { "android": true, "ios": true, "harmony": true },
  "mp-weixin": true,
  "mp-alipay": true
}

注意事项

• 打自定义基座时，若代码中尚未 import 或调用插件 API，编译时会被摇掉，导致基座不包含该插件。请先在业务代码中引用后再打包。
• 修改 import 后建议清理 unpackage/cache 再重新编译。
• 请勿使用 import * as Kit from '@/uni_modules/umi-device-kit' 方式导入，会导致全部 API 被打包。

注意事项

1. 字段对齐：所有平台统一返回 DeviceInfo / BatteryInfo 结构，HarmonyOS App 端字段最完整。
2. 隐私合规：未暴露 serial、udid 等需系统权限的敏感字段。
3. ASCF 元服务：不可直接调用 @kit.BasicServicesKit，请使用 mp-harmony 实现。
4. 导入规范：请从插件根目录 @/uni_modules/umi-device-kit 导入，不要直接导入 utssdk 子目录文件。
5. 类型提示：可在 .uvue 中导入 DeviceInfo、BatteryInfo、GetDeviceInfoOptions、GetBatteryInfoOptions 获得类型提示。