@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. This parameter is optional and is left blank by default.

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. This parameter is optional and is left blank by default.

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. This parameter is optional and is left blank by default.

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. This parameter is optional and is left blank by default.

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. This parameter is optional and is left blank by default.

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 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

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	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

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 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

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	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

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	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.