@ohos.screenLock (锁屏管理)

锁屏管理服务是OpenHarmony中的系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。

说明：

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

导入模块

import screenLock from '@ohos.screenLock';

EventType9+

定义系统事件类型。

系统能力： SystemCapability.MiscServices.ScreenLock

系统接口：此接口为系统接口。

事件类型 说明
beginWakeUp 表示设备开始唤醒。
endWakeUp 表示设备结束唤醒。
beginScreenOn 表示设备开始亮屏。
endScreenOn 表示设备结束亮屏。
beginScreenOff 表示设备开始灭屏。
endScreenOff 表示设备结束灭屏。
unlockScreen 表示请求屏幕解锁。
lockScreen 表示请求屏幕锁定。
beginExitAnimation 表示开始退场动画。
beginSleep 表示设备开始休眠。
endSleep 表示设备结束休眠。
changeUser 表示切换用户。
screenlockEnabled 表示锁屏是否启用。
serviceRestart 表示锁屏服务进行重启。

SystemEvent9+

定义系统事件回调参数结构。

系统能力： SystemCapability.MiscServices.ScreenLock

系统接口：此接口为系统接口

名称 类型 必填 说明
eventType EventType 是 系统事件类型。
params string 是 系统事件参数。

screenLock.isLocked9+

isLocked(): boolean

判断屏幕是否锁屏。

系统能力： SystemCapability.MiscServices.ScreenLock

系统接口：此接口为系统接口

返回值：

类型 说明
boolean 返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。

示例：

let isLocked = screenLock.isLocked();

screenLock.unlock9+

unlock(callback: AsyncCallback<boolean>): void

解锁屏幕。使用callback异步回调。

系统能力： SystemCapability.MiscServices.ScreenLock

系统接口：此接口为系统接口

参数：

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示屏幕解锁成功；返回false表示取消解锁。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

import { BusinessError } from '@ohos.base';

screenLock.unlock((err: BusinessError, data: Boolean) => {
  if (err) {
    console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in unlocking the screen. result: ${data}`);
});

screenLock.unlock9+

unlock(): Promise<boolean>

解锁屏幕。使用Promise异步回调。

系统能力： SystemCapability.MiscServices.ScreenLock

系统接口：此接口为系统接口

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示屏幕解锁成功；返回false表示取消解锁。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

import { BusinessError } from '@ohos.base';

screenLock.unlock().then((data: Boolean) => {
  console.info(`Succeeded in unlocking the screen. result: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`);
});

screenLock.lock9+

lock(callback: AsyncCallback<boolean>): void

锁定屏幕。使用callback异步回调。

系统能力： SystemCapability.MiscServices.ScreenLock

需要权限： ohos.permission.ACCESS_SCREEN_LOCK_INNER

系统接口：此接口为系统接口

参数：

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

import { BusinessError } from '@ohos.base';

screenLock.lock((err: BusinessError, data: Boolean) => {
  if (err) {
    console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in locking the screen. result: ${data}`);
});

screenLock.lock9+

lock(): Promise<boolean>

锁定屏幕。使用Promise异步回调。

系统能力： SystemCapability.MiscServices.ScreenLock

需要权限： ohos.permission.ACCESS_SCREEN_LOCK_INNER

系统接口：此接口为系统接口

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

import { BusinessError } from '@ohos.base';

screenLock.lock().then((data: Boolean) => {
  console.info(`Succeeded in locking the screen. result: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`);
});

screenLock.onSystemEvent9+

onSystemEvent(callback: Callback<SystemEvent>): boolean

注册锁屏相关的系统事件，仅支持锁屏应用使用。

系统能力： SystemCapability.MiscServices.ScreenLock

需要权限： ohos.permission.ACCESS_SCREEN_LOCK_INNER

系统接口：此接口为系统接口

参数：

参数名 类型 必填 说明
callback Callback<SystemEvent> 是 锁屏相关的系统事件回调函数。

返回值：

类型 说明
boolean 返回true表示锁屏相关系统事件注册成功；返回false表示锁屏相关系统事件注册失败。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

try {
  let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => {
    console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`)
  });
} catch (err) {
  let error = err as BusinessError;
  console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`)
}

screenLock.sendScreenLockEvent9+

sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void

应用发送事件到锁屏服务，仅支持锁屏应用使用。使用callback异步回调。

系统能力： SystemCapability.MiscServices.ScreenLock

需要权限： ohos.permission.ACCESS_SCREEN_LOCK_INNER

系统接口：此接口为系统接口

参数：

参数名 类型 必填 说明
event String 是 事件类型，支持如下取值:
- "unlockScreenResult"，表示解锁结果。
- "lockScreenResult"，表示锁屏结果。
- "screenDrawDone"，表示屏幕绘制完成。
parameter number 是 事件结果。
- parameter为0，表示成功。例如解锁成功或锁屏成功。
- parameter为1，表示失败。例如解锁失败或锁屏失败。
- parameter为2，表示取消。例如锁屏取消或解锁取消。
callback AsyncCallback<boolean> 是 回调函数。返回true表示发送事件成功；返回false表示发送事件失败。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

import { BusinessError } from '@ohos.base';

screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => {
  if (err) {
    console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in Sending screenlock event. result: ${result}`);
});

screenLock.sendScreenLockEvent9+

sendScreenLockEvent(event: String, parameter: number): Promise<boolean>

应用发送事件到锁屏服务，仅支持锁屏应用使用。使用Promise异步回调。

系统能力： SystemCapability.MiscServices.ScreenLock

需要权限： ohos.permission.ACCESS_SCREEN_LOCK_INNER

系统接口：此接口为系统接口

参数：

参数名 类型 必填 说明
event String 是 事件类型，支持如下取值:
- "unlockScreenResult"，表示解锁结果。
- "lockScreenResult"，表示锁屏结果。
- "screenDrawDone"，表示屏幕绘制完成。
parameter number 是 事件结果。
- parameter为0，表示成功。例如解锁成功或锁屏成功。
- parameter为1，表示失败。例如解锁失败或锁屏失败。
- parameter为2，表示取消。例如锁屏取消或解锁取消。

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示发送事件成功；返回false表示发送事件失败。

错误码：

以下错误码的详细介绍请参见锁屏服务错误码。

错误码ID 错误信息
13200002 the screenlock management service is abnormal.

示例：

import { BusinessError } from '@ohos.base';

screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => {
  console.info(`Succeeded in Sending screenlock event. result: ${result}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`);
});

screenLock.isScreenLocked(deprecated)

isScreenLocked(callback: AsyncCallback<boolean>): void

判断屏幕是否锁屏。使用callback异步回调。

说明：

从API version 7开始支持，从API version 9开始废弃。

系统能力： SystemCapability.MiscServices.ScreenLock

参数：

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。

示例：

import { BusinessError } from '@ohos.base';

screenLock.isScreenLocked((err: BusinessError, data: Boolean)=>{      
  if (err) {
    console.error(`Failed to obtain whether the screen is locked, Code: ${err.code}, message: ${err.message}`);
    return;    
  }
  console.info(`Succeeded in Obtaining whether the screen is locked. result: ${data}`);
});

screenLock.isScreenLocked(deprecated)

isScreenLocked(): Promise<boolean>

判断屏幕是否锁屏。使用Promise异步回调。

说明：

从API version 7开始支持，从API version 9开始废弃。

系统能力： SystemCapability.MiscServices.ScreenLock

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。

示例：

import { BusinessError } from '@ohos.base';

screenLock.isScreenLocked().then((data: Boolean) => {
  console.info(`Succeeded in Obtaining whether the screen is locked. result: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to obtain whether the screen is locked, Code: ${err.code}, message: ${err.message}`);
});

screenLock.isSecureMode(deprecated)

isSecureMode(callback: AsyncCallback<boolean>): void

判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用callback异步回调。

说明：

从API version 7开始支持，从API version 9开始废弃。

系统能力： SystemCapability.MiscServices.ScreenLock

参数：

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。

示例：

import { BusinessError } from '@ohos.base';

screenLock.isSecureMode((err: BusinessError, data: Boolean)=>{
  if (err) {
    console.error(`Failed to obtain whether the device is in secure mode, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in Obtaining whether the device is in secure mode. result: ${data}`);
});

screenLock.isSecureMode(deprecated)

isSecureMode(): Promise<boolean>

判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用Promise异步回调。

说明：

从API version 7开始支持，从API version 9开始废弃。

系统能力： SystemCapability.MiscServices.ScreenLock

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。

示例：

import { BusinessError } from '@ohos.base';

screenLock.isSecureMode().then((data: Boolean) => {
  console.info(`Succeeded in Obtaining whether the device is in secure mode. result: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to obtain whether the device is in secure mode, Code: ${err.code}, message: ${err.message}`);
});

screenLock.unlockScreen(deprecated)

unlockScreen(callback: AsyncCallback<void>): void

解锁屏幕。使用callback异步回调。

说明：

从API version 7开始支持，从API version 9开始废弃。

系统能力： SystemCapability.MiscServices.ScreenLock

参数：

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。解锁屏幕成功，err为undefined，否则为错误对象。

示例：

import { BusinessError } from '@ohos.base';

screenLock.unlockScreen((err: BusinessError) => {      
  if (err) {
    console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`);
    return;    
  }
  console.info(`Succeeded unlocking the screen.`);
});

screenLock.unlockScreen(deprecated)

unlockScreen(): Promise<void>

解锁屏幕。使用Promise异步回调。

说明：

从API version 7开始支持，从API version 9开始废弃。

系统能力： SystemCapability.MiscServices.ScreenLock

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

import { BusinessError } from '@ohos.base';

screenLock.unlockScreen().then(() => {
  console.info('Succeeded unlocking the screen.');
}).catch((err: BusinessError) => {
  console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`);
});