更新记录

1.2.7（2026-09-22）

• 修复已知问题。

1.2.6（2026-09-21）

• 更新插件文档。

1.2.5（2026-09-21）

• 修复加密插件在鸿蒙无法编译问题。

平台兼容性

uni-app(4.83)

uni-app x(4.83)

其他

umi-device-kit

重要提示（请先阅读）

1. 鸿蒙端：使用 HBuilderX 5.26 编译加密插件会报错，请使用 HBuilderX 5.24。
2. Android / iOS：使用加密插件必须打 自定义基座，标准基座无法加载本插件。

特性

• 一套 API 多端可用：Android / iOS / HarmonyOS App、微信等主流小程序、鸿蒙元服务（ASCF）统一导出，返回同一套 DeviceInfo / BatteryInfo / BluetoothStateInfo 结构。
• 字段对齐鸿蒙：设备信息、电量信息以 HarmonyOS 原生接口为基准；App 端走原生 API，小程序 / 元服务走 uni API 并尽量映射到相同字段。
• 同步 + 异步：getXxxSync 与 getXxx({ success, fail, complete }) 成对提供，错误码与 errMsg 风格与 uni API 一致。
• 设备信息：品牌、认证型号、系统全称、设备类型、ABI、安全补丁、发行版系统信息等；HarmonyOS App 字段最完整，其它端无法获取的字符串为 ''、数值为 -1。
• 自定义设备名称（仅 App）：读取用户在系统设置中修改的本机显示名（不是出厂 marketName）。Android 优先蓝牙名称，HarmonyOS 读「关于本机」，iOS 16+ 需宿主 entitlement。
• 电量信息：剩余电量、充电状态、健康、充电器类型、电压（微伏）、温度、电流（毫安）、电池是否在位等。
• 蓝牙：App 端查询并请求开关系统蓝牙；小程序 / 元服务按官方 API 条件编译查询状态。微信 Android 可跳转系统蓝牙设置；抖音官方无蓝牙接口。小程序不能像 App 一样直接开关系统蓝牙。
• 按需摇树：设备信息、自定义名称、电量、蓝牙拆成独立模块；具名导入时未使用的实现和原生依赖不会打进包。
• 隐私与权限：不暴露 serial、udid 等敏感标识；插件不声明任何权限，Android / iOS / HarmonyOS 所需权限由宿主项目配置。
• 蒸汽模式：已适配 uni-app x 蒸汽模式编译。

文档

在线文档：umi-device-kit.html

如果在线地址访问不了，示例项目中有 docs/umi-device-kit.html 网页文档可查阅。

支持平台

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

使用方法

导入

import {
  getDeviceInfo,
  getDeviceInfoSync,
  getCustomDeviceName,
  getCustomDeviceNameSync,
  getBatteryInfo,
  getBatteryInfoSync,
  getBluetoothState,
  getBluetoothStateSync,
  openBluetooth,
  closeBluetooth,
  GetDeviceInfoOptions,
  GetCustomDeviceNameOptions,
  GetBatteryInfoOptions,
  GetBluetoothStateOptions,
  OpenBluetoothOptions,
  CloseBluetoothOptions
} 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)

获取自定义设备名称（仅 App）

读取用户在系统设置里修改的本机显示名，与 marketName（出厂市场名）不是同一字段。仅 Android / iOS / HarmonyOS App 支持；小程序 / 元服务会失败或返回空字符串。

HarmonyOS 对应 设置 → 关于本机 → 设备名称。权限一律由宿主项目声明，插件不写入任何权限。

同步

HarmonyOS 会先弹权，等授权成功或失败后再返回，请使用 await。Android / iOS 立即返回；Android 12+ 读蓝牙名请先调下方异步接口完成 BLUETOOTH_CONNECT 授权。

const info = await getCustomDeviceNameSync()
console.log(info.customDeviceName)

异步

getCustomDeviceName({
  success(res) {
    console.log(res.customDeviceNameInfo.customDeviceName)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9010006
  }
} as GetCustomDeviceNameOptions)

宿主项目权限（插件不声明）

Android（项目 manifest.json 的 app-android.distribute.permissions，需 HBuilderX 4.54+；4.71+ 也可在可视化界面「安卓 App 配置 → 权限配置」添加）：

"app-android": {
  "distribute": {
    "permissions": [
      "<uses-permission android:name=\"android.permission.BLUETOOTH\" android:maxSdkVersion=\"30\"/>",
      "<uses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" android:maxSdkVersion=\"30\"/>",
      "<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>"
    ]
  }
}

BLUETOOTH_CONNECT 用于 Android 12+ 读取用户自定义设备名（蓝牙名称）以及蓝牙开关。不要写进插件。

iOS（项目 nativeResources/ios/UniApp.entitlements）：

iOS 16+ 读取「设置 → 通用 → 关于本机 → 名称」需 Apple 批准的 entitlement。获批后由宿主写入，插件不包含该文件：

<key>com.apple.developer.device-information.user-assigned-device-name</key>
<true/>

申请入口：User-Assigned Device Name Entitlement。未获批请勿加入，否则无法签名安装。无 entitlement 时本 API 返回空字符串。

HarmonyOS（项目 harmony-configs/entry/src/main/module.json5 的 requestPermissions）：

{
  "name": "ohos.permission.DISTRIBUTED_DATASYNC",
  "reason": "$string:permission_distributed_reason",
  "usedScene": {
    "abilities": ["EntryAbility"],
    "when": "inuse"
  }
},
{
  "name": "ohos.permission.ACCESS_BLUETOOTH",
  "reason": "$string:permission_bluetooth_reason",
  "usedScene": {
    "abilities": ["EntryAbility"],
    "when": "inuse"
  }
}

并在 harmony-configs/entry/src/main/resources/*/element/string.json 中增加 permission_distributed_reason、permission_bluetooth_reason（须小于 36 个中文字符）。

若宿主工程已由 HBuilderX 生成完整 module.json5 / string.json，请把上述权限和字符串合并进现有文件，不要整文件覆盖丢失其它配置。

部分签名证书仍要求 ACL：在调试 / 发布 profile 的 acls.allowed-acls 中加入 ohos.permission.DISTRIBUTED_DATASYNC，或在 AGC 开通「多设备协同」。

读取顺序：distributedDeviceManager.getLocalDeviceName() → settings.general.DEVICE_NAME → ''。用户拒绝授权时仍返回结果，名称可能为空或仅为系统默认名。

Android 优先蓝牙名称（BluetoothAdapter.getName()），并忽略等于 Build.MODEL 等出厂名的 Settings.Global.DEVICE_NAME。iOS 读取 UIDevice.current.name。

获取电量信息

同步

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)

蓝牙状态与开关

查询蓝牙是否可用、是否已开启。App 端打开 / 关闭会触发系统确认框或跳转设置，不会静默改开关。

小程序 / 元服务受官方能力限制：一般只能查询状态；不能直接打开或关闭系统蓝牙。微信 Android 可通过 openSystemBluetoothSetting 跳转系统蓝牙设置（须由用户点击触发）。抖音小程序官方 API 列表无蓝牙接口，查询返回 unsupported，打开 / 关闭失败。

宿主权限（插件不声明）

• Android / HarmonyOS App：与自定义设备名称相同，需宿主声明蓝牙权限。
• iOS App：读取开关或跳转设置，无需额外蓝牙权限。
• 微信小程序：查询系统开关无需权限；跳转设置仅 Android。若走适配器探测，需 scope.bluetooth。
• 支付宝 / 飞书 / 京东 / QQ / 百度：openBluetoothAdapter 可能弹出蓝牙授权。
• 鸿蒙元服务：宿主 module.json5 声明 ohos.permission.ACCESS_BLUETOOTH，并用 has.authorize({ scope: 'scope.bluetooth' }) 申请授权。
• 快手：可从系统信息读取 bluetoothEnabled，无系统蓝牙开关 API。

同步查询

const state = getBluetoothStateSync()

console.log(state.available)  // 设备是否支持蓝牙
console.log(state.enabled)    // 是否已开启
console.log(state.state)      // off | on | turningOn | turningOff | unknown | unsupported

异步查询

getBluetoothState({
  success(res) {
    console.log(res.errMsg)            // getBluetoothState:ok
    console.log(res.bluetoothState)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9010003
  }
} as GetBluetoothStateOptions)

打开 / 关闭

Android / HarmonyOS App 弹出系统确认框（Android 13 以下关闭蓝牙会跳转系统蓝牙设置页）。Android / HarmonyOS App 会等用户点击系统确认框后再回调：确认走 success，取消/禁止走 fail（9010004 / 9010005）。iOS App 无法由应用直接开关，已开启或已关闭时直接返回；否则跳转系统设置，由用户手动操作。微信小程序仅 Android 可跳转系统蓝牙设置；其它小程序在已开启时返回 triggered: false，未开启时失败并提示到系统设置中操作。

openBluetooth({
  success(res) {
    console.log(res.actionResult.triggered, res.actionResult.message)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9010004
  }
} as OpenBluetoothOptions)

closeBluetooth({
  success(res) {
    console.log(res.actionResult.triggered, res.actionResult.message)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9010005
  }
} as CloseBluetoothOptions)

triggered 为 true 表示用户已确认开关，或已跳转设置。Android / HarmonyOS App 在用户确认后才返回，仍建议再调 getBluetoothState 确认最终开关状态。已处于目标状态时 triggered 为 false。

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（异步成功回调）

BluetoothStateInfo 字段说明

GetBluetoothStateSuccess（异步成功回调）

BluetoothActionResult（打开 / 关闭成功回调中的 actionResult）

平台字段支持差异

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

* iOS 16+ 无 com.apple.developer.device-information.user-assigned-device-name 时 UIDevice.name 仅为泛化名（如 iPhone），本 API 返回空字符串。该 entitlement 须由宿主向 Apple 申请后写入项目 nativeResources/ios/UniApp.entitlements，插件不包含此文件。

摇树优化（Tree Shaking）

当前已支持。 App（Android / iOS / HarmonyOS）以及微信、支付宝、百度、抖音、QQ、飞书、快手、京东小程序和鸿蒙元服务均已在 package.json 中开启摇树。

好处

只用到部分 API 时，未引用的实现和原生依赖不会打进包：

• 减小包体积：例如只 import { getDeviceInfoSync } 时，电量、蓝牙、自定义设备名相关代码不会打包。
• 减少原生依赖：未使用的系统 API（如 BatteryManager、蓝牙适配器）不会进入编译产物。
• 按需编译：业务改 import 后，只编译实际用到的模块，避免整插件全量带上。

原理

1. 按 API 拆分模块：设备信息、自定义设备名、电量、蓝牙分别独立文件，互不引用。

utssdk/
├── app-android/
│   ├── device-info.uts           # getDeviceInfo / getDeviceInfoSync
│   ├── custom-device-name.uts    # getCustomDeviceName / getCustomDeviceNameSync
│   ├── battery-info.uts          # getBatteryInfo / getBatteryInfoSync
│   ├── bluetooth.uts             # getBluetoothState / openBluetooth / closeBluetooth
│   └── index.uts
├── app-harmony/
│   └── ...
├── common/
│   ├── bluetooth-info-mp.uts     # 小程序 / 元服务蓝牙（条件编译）
│   ├── device-info-mp.uts
│   └── battery-info-mp.uts
└── ...

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

// ✅ 仅打包设备信息（不含电量、蓝牙）
import { getDeviceInfoSync } from '@/uni_modules/umi-device-kit'

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

// ✅ 仅打包蓝牙相关
import { getBluetoothStateSync } from '@/uni_modules/umi-device-kit'

// ⚠️ 同时 import 多个 API 则对应模块都会打包
import { getDeviceInfoSync, getBatteryInfoSync } from '@/uni_modules/umi-device-kit'

3. package.json 配置：Android / iOS / HarmonyOS App 以及各小程序、鸿蒙元服务均已开启摇树。

"treeShaking": {
  "app": { "android": true, "ios": true, "harmony": true },
  "mp-weixin": true,
  "mp-alipay": true,
  "mp-baidu": true,
  "mp-toutiao": true,
  "mp-qq": true,
  "mp-lark": true,
  "mp-kuaishou": true,
  "mp-jd": true,
  "mp-harmony": true
}

注意事项

• 打自定义基座时，若代码中尚未 import 或调用插件 API，编译时会被摇掉，导致基座不包含该插件。请先在业务代码中引用后再打包。
• 修改 import 后建议清理 unpackage/cache 再重新编译。

• 请勿使用 import * as Kit from '@/uni_modules/umi-device-kit' 方式导入，会导致全部 API 被打包。

注意事项

1. 字段对齐：所有平台统一返回 DeviceInfo / BatteryInfo 结构，HarmonyOS App 端字段最完整。
2. 隐私合规：未暴露 serial、udid 等需系统权限的敏感字段。插件不声明任何权限；Android / iOS / HarmonyOS 所需权限由宿主项目配置。
3. 导入规范：请从插件根目录 @/uni_modules/umi-device-kit 导入，不要直接导入 utssdk 子目录文件。
4. 类型提示：可在 .uvue 中导入 DeviceInfo、CustomDeviceNameInfo、BatteryInfo、BluetoothStateInfo、BluetoothActionResult 以及对应的 Options 类型获得类型提示。
5. 蓝牙开关：openBluetooth / closeBluetooth 会拉起系统 UI。Android / HarmonyOS App 等用户点击确认框后再回调（取消/禁止为失败）；请再调 getBluetoothState 确认最终状态。已处于目标状态时 triggered 为 false。小程序不能直接开关系统蓝牙（微信 Android 除外，仅跳转设置）。
6. iOS 自定义设备名：iOS 16+ 要读「设置 → 通用 → 关于本机 → 名称」，必须先向 Apple 申请 User-Assigned Device Name Entitlement，批准后再加进描述文件，并由宿主写入 nativeResources/ios/UniApp.entitlements（插件不包含该文件）。未获批请勿加入，否则无法签名安装。无 entitlement 时本 API 返回空字符串。