洛汐文档库

外观

system.device 补充 API

约 620 字大约 2 分钟

2026-07-15

import device from '@system.device'

官网文档已经列出 getInfo()、getDeviceId()、getSerial()、getTotalStorage()、getAvailableStorage()，但目标固件还有以下差异。

device.getId(options)

内部 ID 获取接口，参数使用通用回调对象：

device.getId({
  success: data => console.log(data),
  fail: (msg, code) => console.error(code, msg)
})

success 的精确返回形态未从固件静态恢复，首次真机测试应打印完整值，不要直接假定是字符串：

device.getId({
  success: result => console.log(JSON.stringify(result)),
  fail: (message, code) => console.error(code, message),
  complete: () => console.log('getId finished')
})

固件中存在独立的 system_device_wrap_getId，不是 getDeviceId 的字符串残留。

device.getDeviceId(options?) 的同步返回

同源 JIDL 将其定义为返回 String，且回调对象可为 null。部分版本因此可直接：

const id = device.getDeviceId()

兼容写法应同时接受同步返回和回调：

function readDeviceId() {
  return new Promise((resolve, reject) => {
    let settled = false
    const done = value => {
      if (!settled && value != null) {
        settled = true
        resolve(value)
      }
    }

    try {
      const returned = device.getDeviceId({
        success: done,
        fail: (message, code) => reject({ message, code })
      })
      done(returned)
    } catch (e) {
      reject(e)
    }
  })
}

官网只描述了回调形式。此同步形式涉及稳定设备标识并受 hapjs.permission.DEVICE_INFO 约束。

系统层明确拦截

当前 openvela Feature Framework 源码在 FeatureInstance::isBlackListed() 中专门匹配 system.device + getDeviceId。命中后，requestPermissions() 直接返回 false。因此“在 manifest 中声明权限”并不足以让普通应用调用成功；只有设备厂商移除该黑名单，或系统通过预授权/白名单绕过动态申请时，接口才可能可用。

device.getInfo() 的额外字段

字段类型说明
IMEIString蜂窝设备标识；无蜂窝硬件时可能为空
miProductIdString小米产品 ID
deviceModelString小米设备型号
miDeviceAliasString设备别名
device.getInfo({
  success: info => {
    console.log('product:', info.miProductId)
    console.log('model:', info.deviceModel)
    console.log('alias:', info.miDeviceAlias)
  }
})

没有蜂窝硬件时 IMEI 可能为空或根本不存在。代码应使用字段存在性判断，不要把这些扩展字段作为必填。

隐私与稳定性

  • getId()、getDeviceId()、IMEI 都可能属于稳定标识，受 hapjs.permission.DEVICE_INFO 和系统隐私策略约束；其中上游运行时明确拦截 getDeviceId 的动态权限请求；
  • 不要把设备标识写入日志、URL 查询参数或全局 exchange；
  • miDeviceAlias 可能由用户修改，不适合作唯一键；
  • deviceModel 与产品 ID 适合做兼容性分支，但仍需同时检查 feature 能力。

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
△△

获取源代码