@system.brightness (Screen Brightness)
The brightness module provides APIs for querying and adjusting the screen brightness and mode.
NOTE
Module maintenance policy:
- For lite wearables, this module is constantly maintained and available.
- For other device types, this module is no longer maintained since API version 7. You are advised to use APIs of @ohos.brightness. The substitute APIs are available only for system applications.
The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import brightness, { BrightnessModeResponse, BrightnessResponse } from '@system.brightness';
Brightness
Provides APIs for querying and adjusting the screen brightness and mode.
getValue(deprecated)
getValue(options?: GetBrightnessOptions): void
Obtains the current screen brightness.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | GetBrightnessOptions | No | Options for obtaining the screen brightness. This parameter is optional and is left blank by default. |
Example
ArkTS example:
brightness.getValue({
success: (data: BrightnessResponse) => {
console.info('success get brightness value:' + data.value);
},
fail: (data: string, code: number) => {
console.error('get brightness fail, code: ' + code + ', data: ' + data);
}
});
JS example:
<!-- xxx.hml -->
<div class="container">
<input type="button" value="Get Value" style="width: 240px; height: 50px; margin: 5px;" onclick="getValue"></input>
<text class="title">getValue: {{ value }}</text>
</div>
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.title {
width: 200px;
font-size: 30px;
text-align: center;
}
// xxx.js
import brightness from '@system.brightness';
export default {
data: {
value: ''
},
getValue() {
let TAG = 'get_value_success_test';
brightness.getValue({
success: (brightnessResponse) => {
this.value = brightnessResponse.value;
console.info(`${TAG} brightnessResponse.value: ${brightnessResponse.value}`);
},
fail: (data, code) => {
console.error(`${TAG} fail data: ${data}, code: ${code}`);
},
complete: () => {
console.info(`${TAG} getValue complete`);
}
});
},
}
setValue(deprecated)
setValue(options?: SetBrightnessOptions): void
Sets the screen brightness.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SetBrightnessOptions | No | Options for setting the screen brightness. This parameter is optional and is left blank by default. |
Example
ArkTS example:
brightness.setValue({
value: 100,
success: () => {
console.info('handling set brightness success.');
},
fail: (data: string, code: number) => {
console.error('handling set brightness value fail, code:' + code + ', data: ' + data);
}
});
JS example:
<!-- xxx.hml -->
<div class="container">
<input type="button" value="Set Value" style="width: 240px; height: 50px; margin: 5px;" onclick="setValue"></input>
<text class="title">setValue: {{ value }}</text>
</div>
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.title {
width: 200px;
font-size: 30px;
text-align: center;
}
// xxx.js
import brightness from '@system.brightness';
export default {
data: {
value: 100
},
setValue() {
let TAG = 'set_value_success_test';
brightness.setValue({
value: this.value,
success: () => {
console.info(`${TAG} setValue success!`);
},
fail: (data, code) => {
console.error(`${TAG} fail data: ${data}, code: ${code}`);
},
complete: () => {
console.info(`${TAG} setValue complete`);
}
});
},
}
getMode(deprecated)
getMode(options?: GetBrightnessModeOptions): void
Obtains the screen brightness adjustment mode.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | GetBrightnessModeOptions | No | Options for obtaining the screen brightness mode. This parameter is optional and is left blank by default. |
Example
ArkTS example:
brightness.getMode({
success: (data: BrightnessModeResponse) => {
console.info('success get mode:' + data.mode);
},
fail: (data: string, code: number) => {
console.error('handling get mode fail, code:' + code + ', data: ' + data);
}
});
JS example:
<!-- xxx.hml -->
<div class="container">
<input type="button" value="Get Mode" style="width: 240px; height: 50px; margin: 5px;" onclick="getMode"></input>
<text class="title">getMode: {{ mode }}</text>
</div>
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.title {
width: 200px;
font-size: 30px;
text-align: center;
}
// xxx.js
import brightness from '@system.brightness';
export default {
data: {
mode: ''
},
getMode() {
let TAG = 'get_mode_success_test';
brightness.getMode({
success: (brightnessModeResponse) => {
this.mode = brightnessModeResponse.mode;
console.info(`${TAG} brightnessModeResponse mode: ${brightnessModeResponse.mode}`);
},
fail: (data, code) => {
console.error(`${TAG} fail data: ${data}, code: ${code}`);
},
complete: () => {
console.info(`${TAG} getMode complete`);
}
});
},
}
setMode(deprecated)
setMode(options?: SetBrightnessModeOptions): void
Sets the screen brightness adjustment mode.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SetBrightnessModeOptions | No | Options for setting the screen brightness mode. This parameter is optional and is left blank by default. |
Example
ArkTS example:
brightness.setMode({
mode: 1,
success: () => {
console.info('handling set mode success.');
},
fail: (data: string, code: number) => {
console.error('handling set mode fail, code:' + code + ', data: ' + data);
}
});
JS example:
<!-- xxx.hml -->
<div class="container">
<input type="button" value="Set Mode" style="width: 240px; height: 50px; margin: 5px;" onclick="setMode"></input>
<text class="title">setMode: {{ mode }}</text>
</div>
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.title {
width: 200px;
font-size: 30px;
text-align: center;
}
// xxx.js
import brightness from '@system.brightness';
export default {
data: {
mode: 1
},
setMode() {
let TAG = 'set_mode_success_test';
brightness.setMode({
mode: this.mode,
success: () => {
console.info(`${TAG} setMode success`);
},
fail: (data, code) => {
console.error(`${TAG} fail data: ${data}, code: ${code}`);
},
complete: () => {
console.info(`${TAG} setMode complete`);
}
});
},
}
setKeepScreenOn(deprecated)
setKeepScreenOn(options?: SetKeepScreenOnOptions): void
Sets whether to always keep the screen on. Call this API in onShow().
NOTE
- This API is no longer maintained since API version 7 except for lite wearables. You are advised to use window.setWindowKeepScreenOn() instead.
- On Lite Wearables, this API can only prevent the system from turning off the screen due to inactivity timeout (automatic). It cannot prevent screen-off caused by user actions (such as covering the screen) or the end of the keep-screen-on period.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | SetKeepScreenOnOptions | No | Options for setting the screen to be steady on. This parameter is optional and is left blank by default. |
Example
ArkTS example:
brightness.setKeepScreenOn({
keepScreenOn: true,
success: () => {
console.info('handling set keep screen on success.');
},
fail: (data: string, code: number) => {
console.error('handling set keep screen on fail, code:' + code + ', data: ' + data);
}
});
JS example:
<!-- xxx.hml -->
<div class="container">
<input type="button" value="SetKeepScreenOn" style="width: 240px; height: 50px; margin: 5px;" onclick="setKeepScreenOn"></input>
<text class="title">setKeepScreenOn: {{ keepScreenOn }}</text>
</div>
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.title {
width: 200px;
font-size: 30px;
text-align: center;
}
// xxx.js
import brightness from '@system.brightness';
export default {
data: {
keepScreenOn: true
},
setKeepScreenOn() {
let TAG = 'set_keep_screen_on_success_test';
brightness.setKeepScreenOn({
keepScreenOn: this.keepScreenOn,
success: () => {
console.info(`${TAG} setKeepScreenOn success`);
},
fail: (data, code) => {
console.error(`${TAG} fail data: ${data}, code: ${code}`);
},
complete: () => {
console.info(`${TAG} setKeepScreenOn complete`);
}
});
},
}
GetBrightnessOptions(deprecated)
Options for obtaining the screen brightness.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | (data: BrightnessResponse) => void | No | Called when an API call is successful. data is a return value of the BrightnessResponse type. |
| fail | (data: string, code: number) => void | No | Called when an API call has failed. data indicates the error information, and code indicates the error code. |
| complete | () => void | No | Called when an API call is complete. |
SetBrightnessOptions(deprecated)
Options for setting the screen brightness.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | number | Yes | Screen brightness. The value is an integer ranging from 1 to 255. - If the value is less than or equal to 0, value 1 will be used. - If the value is greater than 255, value 255 will be used. - If the value contains decimals, the integral part of the value will be used. For example, if value 8.1 is set, value 8 will be used. |
| success | () => void | No | Called when an API call is successful. |
| fail | (data: string, code: number) => void | No | Called when an API call has failed. data indicates the error information, and code indicates the error code. |
| complete | () => void | No | Called when an API call is complete. |
BrightnessResponse(deprecated)
Defines a response that returns the screen brightness.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Readable | Writable | Description |
|---|---|---|---|---|
| value | number | Yes | No | Screen brightness. The value ranges from 1 to 255. |
GetBrightnessModeOptions(deprecated)
Options for obtaining the screen brightness mode.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Mandatory | Description |
|---|---|---|---|
| success | (data: BrightnessModeResponse) => void | No | Called when an API call is successful. data is a return value of the BrightnessModeResponse type. |
| fail | (data: string, code: number) => void | No | Called when an API call has failed. data indicates the error information, and code indicates the error code. |
| complete | () => void | No | Called when an API call is complete. |
SetBrightnessModeOptions(deprecated)
Options for setting the screen brightness mode.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Mandatory | Description |
|---|---|---|---|
| mode | number | Yes | The value 0 indicates the manual adjustment mode, and the value 1 indicates the automatic adjustment mode. |
| success | () => void | No | Called when an API call is successful. |
| fail | (data: string, code: number) => void | No | Called when an API call has failed. data indicates the error information, and code indicates the error code. |
| complete | () => void | No | Called when an API call is complete. |
BrightnessModeResponse(deprecated)
Defines a response that returns the screen brightness mode.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Readable | Writable | Description |
|---|---|---|---|---|
| mode | number | Yes | No | The value 0 indicates the manual adjustment mode, and the value 1 indicates the automatic adjustment mode. |
SetKeepScreenOnOptions(deprecated)
Options for setting the screen to be steady on.
System capability: SystemCapability.PowerManager.DisplayPowerManager.Lite
| Name | Type | Mandatory | Description |
|---|---|---|---|
| keepScreenOn | boolean | Yes | The value true means to keep the screen steady on, and the value false indicates the opposite. |
| success | () => void | No | Called when an API call is successful. |
| fail | (data: string, code: number) => void | No | Called when an API call has failed. data indicates the error information, and code indicates the error code. |
| complete | () => void | No | Called when an API call is complete. |