HarmonyOS开发：设备管理使用详解

2025-06-14 05:00:47 3 阅读

前言

在当今科技发展迅速的时刻，智能设备的种类和数量不断增加，从智能手机、平板电脑到智能家居设备、智能穿戴设备等，设备之间的互联互通成为了重要的发展趋势。HarmonyOS作为面向全场景智能设备的操作系统，其核心理念之一就是实现设备之间的无缝协同和高效管理。设备管理作为HarmonyOS开发中的关键环节，不仅涉及到设备的发现、连接和控制，还涉及到设备之间的数据同步和资源共享，其重要性不言而喻。设备管理能够帮助开发者更好地理解和利用HarmonyOS的分布式特性，为用户提供更加流畅和便捷的跨设备体验，通过设备管理，开发者可以实现设备之间的无缝切换、数据同步和资源共享，从而提升应用的实用性和用户满意度。那么本文就来深入介绍HarmonyOS中设备管理的使用方法，从基础概念到高级应用，从设备发现与连接到数据同步与资源共享，全方位剖析设备管理的特性和应用场景，通过丰富的示例代码和详细的解释说明，帮助大家快速掌握设备管理的使用要点，提升开发效率和应用质量。

设备管理概述

在HarmonyOS中，设备管理是基础功能中的基础服务，它是ArkTS的常用API之一。虽然说设备管理比较基础但是比较重要，包括电量信息、设备信息、系统电源信息、Runninglock锁、热管理、USB管理等模块。

设备管理组成

上面介绍了HarmonyOS中设备管理的主要组成模块，那么接下来就来详细介绍一下对应的组成模块。

1、电量信息

关于电量信息，即@ohos.batteryInfo，该模块主要提供电池状态和充放电状态的查询接口。

（1）导入模块

import {batteryInfo} from '@kit.BasicServicesKit';

（2）属性信息

主要是描述电池信息。系统能力：SystemCapability.PowerManager.BatteryManager.Core，具体如下所示：

名称	类型	可读	可写	说明
batterySOC	number	是	否	表示当前设备剩余电池电量百分比。元服务API：从API version 12开始，该接口支持在元服务中使用。
chargingStatus	BatteryChargeState	是	否	表示当前设备电池的充电状态。元服务API：从API version 12开始，该接口支持在元服务中使用。
healthStatus	BatteryHealthState	是	否	表示当前设备电池的健康状态。
pluggedType	BatteryPluggedType	是	否	表示当前设备连接的充电器类型。
voltage	number	是	否	表示当前设备电池的电压，单位微伏。
technology	string	是	否	表示当前设备电池的技术型号。
batteryTemperature	number	是	否	表示当前设备电池的温度，单位0.1摄氏度。
isBatteryPresent 7+	boolean	是	否	表示当前设备是否支持电池或者电池是否在位。true表示支持电池或电池在位，false表示不支持电池或电池不在位，默认为false。
batteryCapacityLevel 9+	BatteryCapacityLevel	是	否	表示当前设备电池电量的等级。
nowCurrent 12+	number	是	否	表示当前设备电池的电流，单位毫安。

（3）常用属性

BatteryPluggedType ：表示连接的充电器类型的枚举。系统能力：SystemCapability.PowerManager.BatteryManager.Core
BatteryChargeState：表示电池充电状态的枚举。系统能力：SystemCapability.PowerManager.BatteryManager.Core
BatteryHealthState：表示电池健康状态的枚举。系统能力：SystemCapability.PowerManager.BatteryManager.Core
BatteryCapacityLevel（9+）：表示电池电量等级的枚举。系统能力：SystemCapability.PowerManager.BatteryManager.Core
CommonEventBatteryChangedKey（9+）：表示COMMON_EVENT_BATTERY_CHANGED通用事件附加信息的查询键。系统能力：SystemCapability.PowerManager.BatteryManager.Core

（4）使用示例

import {batteryInfo} from '@kit.BasicServicesKit';

let batterySOCInfo: number = batteryInfo.batterySOC;
console.info("The batterySOCInfo is: " + batterySOCInfo);

let chargingStatusInfo = batteryInfo.chargingStatus;
console.info("The chargingStatusInfo is: " + chargingStatusInfo);

let healthStatusInfo = batteryInfo.healthStatus;
console.info("The healthStatusInfo is: " + healthStatusInfo);

let pluggedTypeInfo = batteryInfo.pluggedType;
console.info("The pluggedTypeInfo is: " + pluggedTypeInfo);

let voltageInfo: number = batteryInfo.voltage;
console.info("The voltageInfo is: " + voltageInfo);

let technologyInfo: string = batteryInfo.technology;
console.info("The technologyInfo is: " + technologyInfo);

let batteryTemperatureInfo: number = batteryInfo.batteryTemperature;
console.info("The batteryTemperatureInfo is: " + batteryTemperatureInfo);

let isBatteryPresentInfo: boolean = batteryInfo.isBatteryPresent;
console.info("The isBatteryPresentInfo is: " + isBatteryPresentInfo);

let batteryCapacityLevelInfo = batteryInfo.batteryCapacityLevel;
console.info("The batteryCapacityLevelInfo is: " + batteryCapacityLevelInfo);

let nowCurrentInfo: number = batteryInfo.nowCurrent;
console.info("The nowCurrentInfo is: " + nowCurrentInfo);

2、设备信息

设备信息，即@ohos.deviceInfo ，本模块提供终端设备信息查询，开发者不可配置。

（1）导入模块

import { deviceInfo } from '@kit.BasicServicesKit';

（2）属性信息

未特殊说明的字段，数据长度最大值为96字节；系统能力：SystemCapability.Startup.SystemInfo；权限：以下各项所需要的权限有所不同，如下所示：

名称	类型	可读	可写	说明
deviceType	string	是	否	设备类型。详细请参考deviceTypes标签。
manufacture	string	是	否	设备厂家名称。
brand	string	是	否	设备品牌名称。
marketName	string	是	否	外部产品系列。
productSeries	string	是	否	产品系列。
productModel	string	是	否	认证型号。
productModelAlias14+	string	是	否	认证型号别名。
softwareModel	string	是	否	内部软件子型号。
hardwareModel	string	是	否	硬件版本号。
hardwareProfile(deprecated)	string	是	否	硬件Profile。从API version 6 开始支持，从API version 9 开始废弃。
serial	string	是	否	设备序列号SN(Serial Number)。可作为设备唯一识别码。需要权限：ohos.permission.sec.ACCESS_UDID(该权限只允许系统应用及企业定制应用申请)
bootloaderVersion	string	是	否	Bootloader版本号。
abiList	string	是	否	应用二进制接口（Abi）。
securityPatchTag	string	是	否	安全补丁级别。
displayVersion	string	是	否	产品版本。
incrementalVersion	string	是	否	差异版本号。
osReleaseType	string	是	否	系统的发布类型，取值为： - Canary：面向特定开发者发布的早期预览版本，不承诺API稳定性。 - Beta：面向开发者公开发布的Beta版本，不承诺API稳定性。 - Release：面向开发者公开发布的正式版本，承诺API稳定性。
osFullName	string	是	否	系统版本，版本格式OpenHarmony-x.x.x.x,x为数值。
majorVersion	number	是	否	Major版本号，随主版本更新增加，值为osFullName中的第一位数值，建议直接使用deviceInfo.majorVersion获取，可提升效率，不建议开发者解析osFullName获取。
seniorVersion	number	是	否	Senior版本号，随局部架构、重大特性增加，值为osFullName中的第二位数值，建议直接使用deviceInfo.seniorVersion获取，可提升效率，不建议开发者自主解析osFullName获取。
featureVersion	number	是	否	Feature版本号，标识规划的新特性版本，值为osFullName中的第三位数值，建议直接使用deviceInfo.featureVersion获取，可提升效率，不建议开发者自主解析osFullName获取。
buildVersion	number	是	否	Build版本号，标识编译构建的版本号，值为osFullName中的第四位数值，建议直接使用deviceInfo.buildVersion获取，可提升效率，不建议开发者自主解析osFullName获取。
sdkApiVersion	number	是	否	系统软件API版本。
firstApiVersion	number	是	否	首个版本系统软件API版本。
versionId	string	是	否	版本ID。由deviceType、manufacture、brand、productSeries、osFullName、productModel、softwareModel、sdkApiVersion、incrementalVersion、buildType拼接组成。
buildType	string	是	否	构建类型。
buildUser	string	是	否	构建用户。
buildHost	string	是	否	构建主机。
buildTime	string	是	否	构建时间。
buildRootHash	string	是	否	构建版本Hash。
udid7+	string	是	否	设备Udid。数据长度为65字节。可作为设备唯一识别码。需要权限：ohos.permission.sec.ACCESS_UDID(该权限只允许系统应用及企业定制应用申请)
distributionOSName10+	string	是	否	发行版系统名称。
distributionOSVersion10+	string	是	否	发行版系统版本号。格式为x.x.x，x是数字
distributionOSApiVersion10+	number	是	否	发行版系统api版本。
distributionOSApiName13+	string	是	否	发行版系统api版本名称。
distributionOSReleaseType10+	string	是	否	发行版系统类型。
ODID12+	string	是	否	开发者匿名设备标识符。 ODID值会在以下场景重新生成：手机恢复出厂设置。同一设备上同一个开发者(developerId相同)的应用全部卸载后重新安装时。 ODID生成规则：根据签名信息里developerId解析出的groupId生成，developerId规则为groupId.developerId，若无groupId则取整个developerId作为groupId。同一设备上运行的同一个开发者(developerId相同)的应用，ODID相同。同一个设备上不同开发者(developerId不同)的应用，ODID不同。不同设备上同一个开发者(developerId相同)的应用，ODID不同。不同设备上不同开发者(developerId不同)的应用，ODID不同。说明：数据长度为37字节。
diskSN15+	string	是	否	硬盘序列号。该字段只能在2in1上设备进行查询，其他设备查询结果为空。需要权限：ohos.permission.ACCESS_DISK_PHY_INFO

（3）使用示例

    import { deviceInfo } from '@kit.BasicServicesKit';


    let deviceTypeInfo: string = deviceInfo.deviceType;
    // 输出结果：the value of the deviceType is :wearable
    console.info('the value of the deviceType is :' + deviceTypeInfo);


    let manufactureInfo: string = deviceInfo.manufacture;
    // 输出结果：the value of the manufacture is :HUAWEI
    console.info('the value of the manufactureInfo is :' + manufactureInfo);


    let brandInfo: string = deviceInfo.brand;
    // 输出结果：the value of the brand is :HUAWEI
    console.info('the value of the device brand is :' + brandInfo);


    let marketNameInfo: string = deviceInfo.marketName;
    // 输出结果：the value of the marketName is :Mate XX
    console.info('the value of the deviceInfo marketName is :' + marketNameInfo);


    let productSeriesInfo: string = deviceInfo.productSeries;
    // 输出结果：the value of the productSeries is :TAS
    console.info('the value of the deviceInfo productSeries is :' + productSeriesInfo);


    let productModelInfo: string = deviceInfo.productModel;
    // 输出结果：the value of the productModel is :TAS-AL00
    console.info('the value of the deviceInfo productModel is :' + productModelInfo);


    let productModelAliasInfo: string = deviceInfo.productModelAlias;
    console.info('the value of the deviceInfo productModelAlias is :' + productModelAliasInfo);


    let softwareModelInfo: string = deviceInfo.softwareModel;
    // 输出结果：the value of the softwareModel is :TAS-AL00
    console.info('the value of the deviceInfo softwareModel is :' + softwareModelInfo);


    let hardwareModelInfo: string = deviceInfo.hardwareModel;
    // 输出结果：the value of the hardwareModel is :TASA00CVN1
    console.info('the value of the deviceInfo hardwareModel is :' + hardwareModelInfo);


    let serialInfo: string = deviceInfo.serial;
    // 输出结果：the value of the serial is :序列号随设备差异
    console.info('the value of the deviceInfo serial is :' + serialInfo);


    let bootloaderVersionInfo: string = deviceInfo.bootloaderVersion;
    // 输出结果：the value of the bootloaderVersion is :bootloader
    console.info('the value of the deviceInfo bootloaderVersion is :' + bootloaderVersionInfo);


    let abiListInfo: string = deviceInfo.abiList;
    // 输出结果：the value of the abiList is :arm64-v8a
    console.info('the value of the deviceInfo abiList is :' + abiListInfo);


    let securityPatchTagInfo: string = deviceInfo.securityPatchTag;
    // 输出结果：the value of the securityPatchTag is :2021/01/01
    console.info('the value of the deviceInfo securityPatchTag is :' + securityPatchTagInfo);


    let displayVersionInfo: string = deviceInfo.displayVersion;
    // 输出结果：the value of the displayVersion is :XXX X.X.X.X
    console.info('the value of the deviceInfo displayVersion is :' + displayVersionInfo);


    let incrementalVersionInfo: string = deviceInfo.incrementalVersion;
    // 输出结果：the value of the incrementalVersion is :default
    console.info('the value of the deviceInfo incrementalVersion is :' + incrementalVersionInfo);


    let osReleaseTypeInfo: string = deviceInfo.osReleaseType;
    // 输出结果：the value of the osReleaseType is :Release
    console.info('the value of the deviceInfo osReleaseType is :' + osReleaseTypeInfo);


    let osFullNameInfo: string = deviceInfo.osFullName;
    // 输出结果：the value of the osFullName is :OpenHarmony-5.0.0.1
    console.info('the value of the deviceInfo osFullName is :' + osFullNameInfo);


    let majorVersionInfo: number = deviceInfo.majorVersion;
    // 输出结果：the value of the majorVersion is :5
    console.info('the value of the deviceInfo majorVersion is :' + majorVersionInfo);


    let seniorVersionInfo: number = deviceInfo.seniorVersion;
    // 输出结果：the value of the seniorVersion is :0
    console.info('the value of the deviceInfo seniorVersion is :' + seniorVersionInfo);


    let featureVersionInfo: number = deviceInfo.featureVersion;
    // 输出结果：the value of the featureVersion is :0
    console.info('the value of the deviceInfo featureVersion is :' + featureVersionInfo);


    let buildVersionInfo: number = deviceInfo.buildVersion;
    // 输出结果：the value of the buildVersion is :1
    console.info('the value of the deviceInfo buildVersion is :' + buildVersionInfo);


    let sdkApiVersionInfo: number = deviceInfo.sdkApiVersion;
    // 输出结果：the value of the sdkApiVersion is :12
    console.info('the value of the deviceInfo sdkApiVersion is :' + sdkApiVersionInfo);


    let firstApiVersionInfo: number = deviceInfo.firstApiVersion;
    // 输出结果：the value of the firstApiVersion is :3
    console.info('the value of the deviceInfo firstApiVersion is :' + firstApiVersionInfo);


    let versionIdInfo: string = deviceInfo.versionId;
    // 输出结果：the value of the versionId is :wearable/HUAWEI/HUAWEI/TAS/OpenHarmony-5.0.0.1/TAS-AL00/TAS-AL00/12/default/release:nolog
    console.info('the value of the deviceInfo versionId is :' + versionIdInfo);


    let buildTypeInfo: string = deviceInfo.buildType;
    // 输出结果：the value of the buildType is :default
    console.info('the value of the deviceInfo buildType is :' + buildTypeInfo);


    let buildUserInfo: string = deviceInfo.buildUser;
    // 输出结果：the value of the buildUser is :default
    console.info('the value of the deviceInfo buildUser is :' + buildUserInfo);


    let buildHostInfo: string = deviceInfo.buildHost;
    // 输出结果：the value of the buildHost is :default
    console.info('the value of the deviceInfo buildHost is :' + buildHostInfo);


    let buildTimeInfo: string = deviceInfo.buildTime;
    // 输出结果：the value of the buildTime is :default
    console.info('the value of the deviceInfo buildTime is :' + buildTimeInfo);


    let buildRootHashInfo: string = deviceInfo.buildRootHash;
    // 输出结果：the value of the buildRootHash is :default
    console.info('the value of the deviceInfo buildRootHash is :' + buildRootHashInfo);


    let udid: string = deviceInfo.udid;
    // 输出结果：the value of the udid is :9D6AABD147XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXE5536412
    console.info('the value of the deviceInfo udid is :' + udid);


    let distributionOSName: string = deviceInfo.distributionOSName
    // 输出结果：the value of the distributionOSName is :OpenHarmony
    console.info('the value of the deviceInfo distributionOSName is :' + distributionOSName);


    let distributionOSVersion: string = deviceInfo.distributionOSVersion
    // 输出结果：the value of the distributionOSVersion is :5.0.0
    console.info('the value of the deviceInfo distributionOSVersion is :' + distributionOSVersion);


    let distributionOSApiVersion: number = deviceInfo.distributionOSApiVersion
    // 输出结果：the value of the distributionOSApiVersion is :500001
    console.info('the value of the deviceInfo distributionOSApiVersion is :' + distributionOSApiVersion);


    let distributionOSApiName: string = deviceInfo.distributionOSApiName
    // 输出结果：the value of the distributionOSApiName is :5.0.0
    console.info('the value of the deviceInfo distributionOSApiName is :' + distributionOSApiName);


    let distributionOSReleaseType: string = deviceInfo.distributionOSReleaseType
    // 输出结果：the value of the distributionOSReleaseType is :Release
    console.info('the value of the deviceInfo distributionOSReleaseType is :' + distributionOSReleaseType);


    let odid: string = deviceInfo.ODID;
    // 输出结果：the value of the ODID is :1234a567-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    console.info('the value of the deviceInfo odid is :' + odid);


    let diskSN: string = deviceInfo.diskSN;
    // 输出结果：the value of the deviceInfo diskSN is :2502EM400567
    console.info('the value of the deviceInfo diskSN is :' + diskSN);

3、系统电源信息

@ohos.power (系统电源管理)，该模块主要提供重启、关机、查询屏幕状态等接口。开发者可以使用该模块的接口获取设备的活动状态、电源模式、亮灭屏状态等。

（1）导入模块

import {power} from '@kit.BasicServicesKit';

（2）属性信息

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

（3）常用属性

a.power.isActive（9+）

isActive(): boolean

检测当前设备是否处于活动状态。

有屏的设备亮屏时为活动状态，熄屏时为非活动状态。
无屏的设备非休眠时为活动状态，休眠时为非活动状态。

系统能力： SystemCapability.PowerManager.PowerManager.Core

b.power.rebootDevice(deprecated)

rebootDevice(reason: string): void

重启设备。

需要权限： ohos.permission.REBOOT,该权限仅系统应用可申请。

系统能力： SystemCapability.PowerManager.PowerManager.Core

c.power.getPowerMode（9+）

getPowerMode(): DevicePowerMode

获取当前设备的电源模式。

系统能力： SystemCapability.PowerManager.PowerManager.Core

d.power.isStandby（10+）

isStandby(): boolean

检测当前设备是否进入待机低功耗续航模式。

系统能力： SystemCapability.PowerManager.PowerManager.Core

e.DevicePowerMode（9+）

表示电源模式的枚举值。

系统能力： SystemCapability.PowerManager.PowerManager.Core

（4）使用示例

try {
    let isActive = power.isActive();
    console.info('power is active: ' + isActive);
} catch(err) {

}

4、Runninglock锁

@ohos.runningLock (Runninglock锁)，该模块主要提供RunningLock锁相关操作的接口，包括创建、查询、持锁、释放锁等操作。

（1）导入模块

import {runningLock} from '@kit.BasicServicesKit';

（2）属性信息

该模块首批接口从API version 7开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。

（3）常用属性

a. runningLock.isSupported（9+）

isSupported(type: RunningLockType): boolean

查询系统是否支持该类型的锁。

系统能力： SystemCapability.PowerManager.PowerManager.Core

b. runningLock.create(9+)

create(name: string, type: RunningLockType, callback: AsyncCallback): void

创建RunningLock锁。

系统能力： SystemCapability.PowerManager.PowerManager.Core

需要权限： ohos.permission.RUNNING_LOCK

c.runningLock.create(9+)

create(name: string, type: RunningLockType): Promise

创建RunningLock锁。

系统能力： SystemCapability.PowerManager.PowerManager.Core

需要权限： ohos.permission.RUNNING_LOCK

d.RunningLock

阻止系统休眠的锁。

e.RunningLockType

RunningLock锁的类型。

系统能力： SystemCapability.PowerManager.PowerManager.Core

（4）使用示例

// RunningLockTest.ets
class RunningLockTest {
    public static recordLock: runningLock.RunningLock;


    public static holdRunningLock(): void {
        if (RunningLockTest.recordLock) {
            RunningLockTest.recordLock.hold(500);
            console.info('hold running lock success');
        } else {
            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
                if (typeof err === 'undefined') {
                    console.info('create running lock: ' + lock);
                    RunningLockTest.recordLock = lock;
                    try {
                        lock.hold(500);
                        console.info('hold running lock success');
                    } catch(err) {
                        console.error('hold running lock failed, err: ' + err);
                    }
                } else {
                    console.error('create running lock failed, err: ' + err);
                }
            });
        }
    }
}

5、热管理

@ohos.thermal (热管理)，该模块提供热管理相关的接口，包括热档位查询及注册回调等功能。

（1）导入模块

import {thermal} from '@kit.BasicServicesKit';

（2）属性信息

该模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

（3）常用属性

a.thermal.registerThermalLevelCallback(9+)

registerThermalLevelCallback(callback: Callback): void

订阅热档位变化时的回调提醒。

系统能力： SystemCapability.PowerManager.ThermalManager

b.thermal.unregisterThermalLevelCallback(9+)

unregisterThermalLevelCallback(callback?: Callback): void

取消订阅热档位变化时的回调提醒。

系统能力： SystemCapability.PowerManager.ThermalManager

c.thermal.getLevel（9+）

getLevel(): ThermalLevel

获取当前热档位信息。

系统能力： SystemCapability.PowerManager.ThermalManager

d.ThermalLevel

热档位信息。

系统能力： SystemCapability.PowerManager.ThermalManager

（4）使用示例

try {
    thermal.registerThermalLevelCallback((level: thermal.ThermalLevel) => {
        console.info('thermal level is: ' + level);
    });
    console.info('register thermal level callback success.');
} catch(err) {
    console.error('register thermal level callback failed, err: ' + err);
}

6、USB管理

@ohos.usbManager (USB管理)，本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。

（1）导入模块

import { usbManager } from '@kit.BasicServicesKit';

（2）属性信息

该模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。