diff --git a/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md b/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md index d2467a45aeeb4c184864cc197de88466606d2a5a..adc8024bf8ba6bf4729df7906375a3e4ea74ae32 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md +++ b/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md @@ -20,17 +20,17 @@ import screenlock from '@ohos.screenLock'; | 事件类型 | 说明 | | ------------------ | ------------------------ | -| beginWakeUp | 表示事件开始时开始唤醒。 | -| endWakeUp | 表示事件结束时结束唤醒。 | -| beginScreenOn | 表示事件开始时开始亮屏。 | -| endScreenOn | 表示事件结束时结束亮屏。 | -| beginScreenOff | 表示事件开始时开始灭屏。 | -| endScreenOff | 表示事件结束时结束灭屏。 | -| unlockScreen | 表示请求解锁屏幕。 | -| lockScreen | 表示请求锁定屏幕。 | -| beginExitAnimation | 表示动画开始退场。 | -| beginSleep | 表示开始休眠。 | -| endSleep | 表示结束休眠。 | +| beginWakeUp | 表示设备开始唤醒。 | +| endWakeUp | 表示设备结束唤醒。 | +| beginScreenOn | 表示设备开始亮屏。 | +| endScreenOn | 表示设备结束亮屏。 | +| beginScreenOff | 表示设备开始灭屏。 | +| endScreenOff | 表示设备结束灭屏。 | +| unlockScreen | 表示请求屏幕解锁。 | +| lockScreen | 表示请求屏幕锁定。 | +| beginExitAnimation | 表示开始退场动画。 | +| beginSleep | 表示设备开始休眠。 | +| endSleep | 表示设备结束休眠。 | | changeUser | 表示切换用户。 | | screenlockEnabled | 表示锁屏是否启用。 | | serviceRestart | 表示锁屏服务进行重启。 | @@ -44,7 +44,7 @@ import screenlock from '@ohos.screenLock'; | 名称 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ------------- | | eventType | [EventType](#eventtype) | 是 | 系统事件类型。 | -| params | string | 是 | 系统事件的事件参数。 | +| params | string | 是 | 系统事件参数。 | ## screenlock.isLocked9+ @@ -58,7 +58,7 @@ isLocked(): boolean | 类型 | 说明 | | ------- | ------------------------------------------------- | -| boolean | 返回true表示屏幕已锁屏，返回false表示屏幕未锁屏。 | +| boolean | 返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | **示例：** @@ -70,7 +70,7 @@ let isLocked = screenlock.isLocked(); isSecure(): boolean -判断设备是否处于安全模式下。 +判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -78,7 +78,7 @@ isSecure(): boolean | 类型 | 说明 | | ------- | ------------------------------------------------------------ | -| boolean | 返回true表示屏幕处于安全模式下，返回false表示屏幕当前不在安全模式下。 | +| boolean | 返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | **示例：** @@ -90,7 +90,7 @@ let isSecure = screenlock.isSecure(); unlock(callback: AsyncCallback<boolean>): void -解锁屏幕，使用callback异步回调。 +解锁屏幕。使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -98,17 +98,25 @@ unlock(callback: AsyncCallback<boolean>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------- | ---- | ------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕解锁成功，返回false表示屏幕解锁失败。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕解锁成功；返回false表示屏幕解锁失败。 | + +**错误码**： + +以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 13200002 | The screenlock management service is abnormal. | **示例：** ```js -screenlock.unlock((err,data) => { +screenlock.unlock((err, data) => { if (err) { - console.error('unlock error -> ${JSON.stringify(err)}'); + console.error(`Failed to unlock the screen, because: ${err.message}`); return; } - console.info('unlock success data -> ${JSON.stringify(data)}'); + console.info(`unlock the screen successfully. result: ${data}`); }); ``` @@ -116,7 +124,7 @@ screenlock.unlock((err,data) => { unlock(): Promise<boolean> -解锁屏幕，使用Promise异步回调。 +解锁屏幕。使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -124,15 +132,23 @@ unlock(): Promise<boolean> | 类型 | 说明 | | ------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Promise对象。返回true表示屏幕解锁成功，返回false表示屏幕解锁失败。 | +| Promise<boolean> | Promise对象。返回true表示屏幕解锁成功；返回false表示屏幕解锁失败。 | + +**错误码**： + +以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 13200002 | The screenlock management service is abnormal. | **示例：** ```js screenlock.unlock().then((data) => { - console.log('unlock success'); + console.info(`unlock the screen successfully. result: ${data}`); }).catch((err) => { - console.error('unlock fail, : err->${JSON.stringify(err)}'); + console.error(`Failed to unlock the screen, because: ${err.message}`); }); ``` @@ -140,7 +156,7 @@ screenlock.unlock().then((data) => { lock(callback: AsyncCallback<boolean>): void -锁定屏幕，使用callback异步回调。 +锁定屏幕。使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -150,17 +166,25 @@ lock(callback: AsyncCallback<boolean>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------- | ---- | ---------------- | -| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕锁定成功，返回false表示屏幕锁定失败。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | + +**错误码**： + +以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 13200002 | The screenlock management service is abnormal. | **示例：** ```js -screenlock.lock((err,data) => { +screenlock.lock((err, data) => { if (err) { - console.error('lock callback error -> ${JSON.stringify(err)}'); + console.error(`Failed to lock the screen, because: ${err.message}`); return; } - console.info('lock callback success'); + console.info(`lock the screen successfully. result: ${data}`); }); ``` @@ -168,7 +192,7 @@ screenlock.lock((err,data) => { lock(): Promise<boolean> -锁定屏幕，使用Promise异步回调。 +锁定屏幕。使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -178,21 +202,29 @@ lock(): Promise<boolean> | 类型 | 说明 | | ---------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Promise对象。返回true表示屏幕锁定成功，返回false表示屏幕锁定失败。 | +| Promise<boolean> | Promise对象。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | + +**错误码**： + +以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 13200002 | The screenlock management service is abnormal. | **示例：** ```js screenlock.lock().then((data) => { - console.log('lock success'); + console.info(`lock the screen successfully. result: ${data}`); }).catch((err) => { - console.error('lock fail, promise: err->${JSON.stringify(err)}'); + console.error(`Failed to lock the screen, because: ${err.message}`); }); ``` ## screenlock.onSystemEvent9+ -onSystemEvent(callback: Callback\): boolean +onSystemEvent(callback: Callback<SystemEvent>): boolean 注册锁屏相关的系统事件。 @@ -210,24 +242,33 @@ onSystemEvent(callback: Callback\): boolean | 类型 | 说明 | | ------- | ------------------------------------------------- | -| boolean | 返回true表示锁屏系统事件注册成功，否则返回false。 | +| boolean | 返回true表示锁屏相关系统事件注册成功；返回false表示锁屏相关系统事件注册失败。 | + +**错误码**： + +以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 13200002 | The screenlock management service is abnormal. | **示例：** ```js -let isSuccess = screenlock.onSystemEvent((event)=>{ - console.log(`onSystemEvent:callback:${event.eventType}`) -}); -if (!isSuccess) { - console.log(`onSystemEvent result is false`) +try { + let isSuccess = screenLock.onSystemEvent((event) => { + console.log(`Register the system event which related to screenlock successfully. eventType: ${event.eventType}`) + }); +} catch (err) { + console.error(`Failed to register the system event which related to screenlock, because: ${err.message}`) } ``` ## screenlock.sendScreenLockEvent9+ -sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback\): void +sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void -应用发送事件到锁屏服务，使用callback异步回调。 +应用发送事件到锁屏服务。使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -237,23 +278,35 @@ sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback\- "unlockScreenResult"，表示解锁结果。
- "screenDrawDone"，表示屏幕绘制完成。 | -| parameter | number | 是 | 解锁状态。
- parameter为0，表示解锁成功。
- parameter为1，表示解锁失败。
- parameter为2，表示解锁取消。 | -| callback | AsyncCallback\ | 是 | 回调函数，返回执行的结果。true表示执行成功，false表示执行失败。 | +| event | String | 是 | 事件类型，支持如下取值:
- "unlockScreenResult"，表示解锁结果。
- "lockScreenResult"，表示锁屏结果。
- "screenDrawDone"，表示屏幕绘制完成。 | +| parameter | number | 是 | 事件结果。
- parameter为0，表示成功。例如解锁成功或锁屏成功。
- parameter为1，表示失败。例如解锁失败或锁屏失败。
- parameter为2，表示取消。例如锁屏取消或解锁取消。 | +| callback | AsyncCallback\ | 是 | 回调函数。返回true表示发送事件成功；返回false表示发送事件失败。 | + +**错误码**： + +以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 13200002 | The screenlock management service is abnormal. | **示例：** ```js screenlock.sendScreenLockEvent('unlockScreenResult', 0, (err, result) => { - console.log('sending result:' + result); + if (err) { + console.error(`Failed to send screenlock event, because: ${err.message}`); + return; + } + console.info(`Send screenlock event successfully. result: ${result}`); }); ``` ## screenlock.sendScreenLockEvent9+ -sendScreenLockEvent(event: String, parameter: number): Promise\ +sendScreenLockEvent(event: String, parameter: number): Promise<boolean> -应用发送事件到锁屏服务，使用Promise异步回调。 +应用发送事件到锁屏服务。使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -263,20 +316,22 @@ sendScreenLockEvent(event: String, parameter: number): Promise\ | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | --------------------------------------- | -| event | String | 是 | 事件类型，支持如下取值:
- "unlockScreenResult"，表示解锁结果。
- "screenDrawDone"，表示屏幕绘制完成。 | -| parameter | number | 是 | 解锁状态。
- parameter为0，表示解锁成功。
- parameter为1，表示解锁失败。
- parameter为2，表示解锁取消。 | +| event | String | 是 | 事件类型，支持如下取值:
- "unlockScreenResult"，表示解锁结果。
- "lockScreenResult"，表示锁屏结果。
- "screenDrawDone"，表示屏幕绘制完成。 | +| parameter | number | 是 | 事件结果。
- parameter为0，表示成功。例如解锁成功或锁屏成功。
- parameter为1，表示失败。例如解锁失败或锁屏失败。
- parameter为2，表示取消。例如锁屏取消或解锁取消。 | **返回值：** | 类型 | 说明 | | ----------------- | ---------------------------------------------- | -| Promise\ | Promise对象，返回执行的结果。true表示执行成功，false表示执行失败。 | +| Promise\ | Promise对象。返回true表示发送事件成功；返回false表示发送事件失败。 | **示例：** ```js screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { - console.log('sending result:' + result); + console.info(`Send screenlock event successfully. result: ${result}`); +}).catch((err) => { + console.error(`Failed to send screenlock event, because: ${err.message}`); }); ``` @@ -284,11 +339,11 @@ screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { isScreenLocked(callback: AsyncCallback<boolean>): void -判断屏幕是否锁屏，使用callback异步回调。 +判断屏幕是否锁屏。使用callback异步回调。 > **说明：** > ->从 API version 7开始支持，从API version 9开始废弃。建议使用[screenlock.isLocked9+](#screenlockislocked9)代替。 +> 从API version 7开始支持，从API version 9开始不再维护。建议使用[screenlock.isLocked9+](#screenlockislocked9)代替。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -296,17 +351,17 @@ isScreenLocked(callback: AsyncCallback<boolean>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ----------------------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调函数，返回true表示屏幕已锁屏，返回false表示屏幕未锁屏。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | **示例：** ```js screenlock.isScreenLocked((err, data)=>{ if (err) { - console.error('isScreenLocked callback error -> ${JSON.stringify(err)}'); + console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); return; } - console.info('isScreenLocked callback success data -> ${JSON.stringify(data)}'); + console.info(`Obtain whether the screen is locked successfully. result: ${data}`); }); ``` @@ -314,11 +369,11 @@ screenlock.isScreenLocked((err, data)=>{ isScreenLocked(): Promise<boolean> -判断屏幕是否锁屏，使用Promise异步回调。 +判断屏幕是否锁屏。使用Promise异步回调。 > **说明：** > -> 从API version 7开始支持，从API version 9开始废弃。建议使用[screenlock.isLocked9+](#screenlockislocked9)代替。 +> 从API version 7开始支持，从API version 9开始不再维护。建议使用[screenlock.isLocked9+](#screenlockislocked9)代替。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -326,15 +381,15 @@ isScreenLocked(): Promise<boolean> | 类型 | 说明 | | ---------------------- | ------------------------------------------- | -| Promise<boolean> | Promise对象，返回判断结果。返回true表示屏幕已锁屏，返回false表示屏幕未锁屏。 | +| Promise<boolean> | Promise对象。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | **示例：** ```js screenlock.isScreenLocked().then((data) => { - console.log('isScreenLocked success: data -> ${JSON.stringify(data)}'); + console.info(`Obtain whether the screen is locked successfully. result: ${data}`); }).catch((err) => { - console.error('isScreenLocked fail, promise: err -> ${JSON.stringify(err)}'); + console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); }); ``` @@ -342,11 +397,11 @@ screenlock.isScreenLocked().then((data) => { isSecureMode(callback: AsyncCallback<boolean>): void -判断设备是否处于安全模式下，使用callback异步回调。 +判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用callback异步回调。 > **说明：** > -> 从 API version 7开始支持，从API version 9开始废弃。建议使用[screenlock.isSecure9+](#screenlockissecure9)代替。 +> 从API version 7开始支持，从API version 9开始不再维护。建议使用[screenlock.isSecure9+](#screenlockissecure9)代替。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -354,17 +409,17 @@ isSecureMode(callback: AsyncCallback<boolean>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------- | ---- | ------------------------ | -| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕处于安全模式下，返回false表示屏幕当前不在安全模式下。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | **示例：** ```js -screenlock.isSecureMode((err, data)=>{ +screenlock.isSecureMode((err, data)=>{ if (err) { - console.error('isSecureMode callback error -> ${JSON.stringify(err)}'); - return; + console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); + return; } - console.info('isSecureMode callback success data -> ${JSON.stringify(err)}'); + console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); }); ``` @@ -372,11 +427,11 @@ screenlock.isSecureMode((err, data)=>{ isSecureMode(): Promise<boolean> -判断设备是否处于安全模式下，使用Promise异步回调。 +判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用Promise异步回调。 > **说明：** > -> 从 API version 7开始支持，从API version 9开始废弃。建议使用[screenlock.isSecure9+](#screenlockissecure9)代替。 +> 从API version 7开始支持，从API version 9开始不再维护。建议使用[screenlock.isSecure9+](#screenlockissecure9)代替。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -384,26 +439,26 @@ isSecureMode(): Promise<boolean> | 类型 | 说明 | | ---------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Promise对象。返回true表示屏幕处于安全模式下，返回false表示屏幕当前不在安全模式下。 | +| Promise<boolean> | Promise对象。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | **示例：** ```js screenlock.isSecureMode().then((data) => { - console.log('isSecureMode success: data->${JSON.stringify(data)}'); + console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); }).catch((err) => { - console.error('isSecureMode fail, promise: err->${JSON.stringify(err)}'); + console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); }); ``` ## screenlock.unlockScreen(deprecated) unlockScreen(callback: AsyncCallback<void>): void -解锁屏幕，使用callback异步回调。 +解锁屏幕。使用callback异步回调。 > **说明：** > -> 从 API version 7开始支持，从API version 9开始废弃。建议使用[screenlock.unlock9+](#screenlockunlock9)代替。 +> 从API version 7开始支持，从API version 9开始不再维护。建议使用[screenlock.unlock9+](#screenlockunlock9)代替。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -411,17 +466,17 @@ unlockScreen(callback: AsyncCallback<void>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------- | ---- | --------------- | -| callback | AsyncCallback<void> | 是 | 回调函数，失败时返回错误信息。 | +| callback | AsyncCallback<void> | 是 | 回调函数。解锁屏幕成功，err为undefined，否则为错误对象。 | **示例：** ```js screenlock.unlockScreen((err) => { if (err) { - console.error('unlockScreen callback error -> ${JSON.stringify(err)}'); + console.error(`Failed to unlock the screen, because: ${err.message}`); return; } - console.info('unlockScreen callback success'); + console.info('unlock the screen successfully.'); }); ``` @@ -429,11 +484,11 @@ screenlock.unlockScreen((err) => { unlockScreen(): Promise<void> -解锁屏幕，使用Promise异步回调。 +解锁屏幕。使用Promise异步回调。 > **说明：** > -> 从 API version 7开始支持，从API version 9开始废弃。建议使用[screenlock.unlock9+](#screenlockunlock9)代替。 +> 从API version 7开始支持，从API version 9开始不再维护。建议使用[screenlock.unlock9+](#screenlockunlock9)代替。 **系统能力：** SystemCapability.MiscServices.ScreenLock @@ -441,14 +496,14 @@ unlockScreen(): Promise<void> | 类型 | 说明 | | ------------------- | ------------------------- | -| Promise<void> | 无返回结果的Promise对象。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js screenlock.unlockScreen().then(() => { - console.log('unlockScreen success'); + console.info('unlock the screen successfully.'); }).catch((err) => { - console.error('unlockScreen fail, promise: err->${JSON.stringify(err)}'); + console.error(`Failed to unlock the screen, because: ${err.message}`); }); ```