@system.brightness (Screen Brightness)

The brightness module provides APIs for querying and adjusting the screen brightness and mode.

NOTE

  • The APIs of this module are 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 from '@system.brightness';

brightness.getValue

getValue(options?: GetBrightnessOptions): void

Obtains the current screen brightness.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Parameters

Name Type Mandatory Description
options GetBrightnessOptions No Options for obtaining the screen brightness.

Example

brightness.getValue({
    success: function(data) {
        console.log('success get brightness value:' + data.value);
    },
    fail: function(data, code) {
        console.error('get brightness fail, code: ' + code + ', data: ' + data);
    }
});

brightness.setValue

setValue(options?: SetBrightnessOptions): void

Sets the screen brightness.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Parameters

Name Type Mandatory Description
options SetBrightnessOptions No Options for setting the screen brightness.

Example

brightness.setValue({
    value: 100,
    success: function() {
        console.log('handling set brightness success.');
    },
    fail: function(data, code) {
        console.error('handling set brightness value fail, code:' + code + ', data: ' + data);
    }
});

brightness.getMode

getMode(options?: GetBrightnessModeOptions): void

Obtains the screen brightness adjustment mode.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Parameters

Name Type Mandatory Description
options GetBrightnessModeOptions No Options for obtaining the screen brightness mode.

Example

brightness.getMode({
    success: function(data) {
        console.log('success get mode:' + data.mode);
    },
    fail: function(data, code){
        console.error('handling get mode fail, code:' + code + ', data: ' + data);
    }
});

brightness.setMode

setMode(options?: SetBrightnessModeOptions): void

Sets the screen brightness adjustment mode.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Parameters

Name Type Mandatory Description
options SetBrightnessModeOptions No Options for setting the screen brightness mode.

Example

brightness.setMode({
    mode: 1,
    success: function() {
        console.log('handling set mode success.');
    },
    fail: function(data, code) {
        console.error('handling set mode fail, code:' + code + ', data: ' + data);
    }
});

brightness.setKeepScreenOn

setKeepScreenOn(options?: SetKeepScreenOnOptions): void

This API is no longer maintained since API version 7. It is recommended that you use window.setKeepScreenOn instead.

Sets whether to always keep the screen on. Call this API in onShow().

System capability: SystemCapability.PowerManager.DisplayPowerManager

Parameters

Name Type Mandatory Description
options SetKeepScreenOnOptions No Options for setting the screen to be steady on.

Example

brightness.setKeepScreenOn({
    keepScreenOn: true,
    success: function () {
        console.log('handling set keep screen on success.');
    },
    fail: function (data, code) {
        console.error('handling set keep screen on fail, code:' + code + ', data: ' + data);
    }
});

GetBrightnessOptions

Defines the options for obtaining the screen brightness.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Name Type Mandatory Description
success (data: BrightnessResponse) => void No Called when API call is successful. data is a return value of the BrightnessResponse type.
fail (data: string, code: number) => void No Called when API call has failed. data indicates the error information, and code indicates the error code.
complete () => void No Called when the API call is complete.

SetBrightnessOptions

Defines the options for setting the screen brightness.

System capability: SystemCapability.PowerManager.DisplayPowerManager

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 Callback upon a successful API call.
fail (data: string, code: number) => void No Called when API call has failed. data indicates the error information, and code indicates the error code.
complete () => void No Called when the API call is complete.

BrightnessResponse

Defines a response that returns the screen brightness.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Name Type Readable Writable Description
value number Yes No Screen brightness. The value ranges from 1 to 255.

GetBrightnessModeOptions

Defines the options for obtaining the screen brightness mode.

System capability: SystemCapability.PowerManager.DisplayPowerManager

Name Type Mandatory Description
success (data: BrightnessModeResponse) => void No Called when API call is successful. data is a return value of the BrightnessModeResponse type.
fail (data: string, code: number) => void No Called when API call has failed. data indicates the error information, and code indicates the error code.
complete () => void No Called when the API call is complete.

SetBrightnessModeOptions

Defines the options for setting the screen brightness mode.

System capability: SystemCapability.PowerManager.DisplayPowerManager

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 Callback upon a successful API call.
fail (data: string, code: number) => void No Called when API call has failed. data indicates the error information, and code indicates the error code.
complete () => void No Called when the API call is complete.

BrightnessModeResponse

Defines a response that returns the screen brightness mode.

System capability: SystemCapability.PowerManager.DisplayPowerManager

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

Defines the options for setting the screen to be steady on.

System capability: SystemCapability.PowerManager.DisplayPowerManager

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 Callback upon a successful API call.
fail (data: string, code: number) => void No Called when API call has failed. data indicates the error information, and code indicates the error code.
complete () => void No Called when the API call is complete.