1# @system.brightness (Screen Brightness) 2 3The **brightness** module provides APIs for querying and adjusting the screen brightness and mode. 4 5> **NOTE** 6> 7> - The APIs of this module are no longer maintained since API version 7. You are advised to use APIs of [`@ohos.brightness`](js-apis-brightness.md). The substitute APIs are available only for system applications. 8> - 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. 9 10 11## Modules to Import 12 13 14```js 15import brightness from '@system.brightness'; 16``` 17 18 19## brightness.getValue 20 21getValue(options?: GetBrightnessOptions): void 22 23Obtains the current screen brightness. 24 25**System capability**: SystemCapability.PowerManager.DisplayPowerManager 26 27**Parameters** 28 29| Name| Type| Mandatory| Description| 30| -------- | -------- | -------- | -------- | 31| options | [GetBrightnessOptions](#getbrightnessoptions) | No | Options for obtaining the screen brightness.| 32 33**Example** 34 35 ```js 36 brightness.getValue({ 37 success: function(data) { 38 console.log('success get brightness value:' + data.value); 39 }, 40 fail: function(data, code) { 41 console.error('get brightness fail, code: ' + code + ', data: ' + data); 42 } 43 }); 44 ``` 45 46 47## brightness.setValue 48 49setValue(options?: SetBrightnessOptions): void 50 51Sets the screen brightness. 52 53**System capability**: SystemCapability.PowerManager.DisplayPowerManager 54 55**Parameters** 56 57| Name| Type| Mandatory| Description| 58| -------- | -------- | -------- | -------- | 59| options | [SetBrightnessOptions](#setbrightnessoptions) | No | Options for setting the screen brightness.| 60 61**Example** 62 63 ```js 64 brightness.setValue({ 65 value: 100, 66 success: function() { 67 console.log('handling set brightness success.'); 68 }, 69 fail: function(data, code) { 70 console.error('handling set brightness value fail, code:' + code + ', data: ' + data); 71 } 72 }); 73 ``` 74 75 76## brightness.getMode 77 78getMode(options?: GetBrightnessModeOptions): void 79 80Obtains the screen brightness adjustment mode. 81 82**System capability**: SystemCapability.PowerManager.DisplayPowerManager 83 84**Parameters** 85 86| Name| Type| Mandatory| Description| 87| -------- | -------- | -------- | -------- | 88| options | [GetBrightnessModeOptions](#getbrightnessmodeoptions) | No| Options for obtaining the screen brightness mode.| 89 90**Example** 91 92 ```js 93 brightness.getMode({ 94 success: function(data) { 95 console.log('success get mode:' + data.mode); 96 }, 97 fail: function(data, code){ 98 console.error('handling get mode fail, code:' + code + ', data: ' + data); 99 } 100 }); 101 ``` 102 103 104## brightness.setMode 105 106setMode(options?: SetBrightnessModeOptions): void 107 108Sets the screen brightness adjustment mode. 109 110**System capability**: SystemCapability.PowerManager.DisplayPowerManager 111 112**Parameters** 113| Name| Type| Mandatory| Description| 114| -------- | -------- | -------- | -------- | 115| options | [SetBrightnessModeOptions](#setbrightnessmodeoptions) | No | Options for setting the screen brightness mode.| 116 117**Example** 118 119 ```js 120 brightness.setMode({ 121 mode: 1, 122 success: function() { 123 console.log('handling set mode success.'); 124 }, 125 fail: function(data, code) { 126 console.error('handling set mode fail, code:' + code + ', data: ' + data); 127 } 128 }); 129 ``` 130 131 132## brightness.setKeepScreenOn 133 134setKeepScreenOn(options?: SetKeepScreenOnOptions): void 135 136>This API is no longer maintained since API version 7. It is recommended that you use [window.setKeepScreenOn](js-apis-window.md#setkeepscreenon) instead. 137 138Sets whether to always keep the screen on. Call this API in **onShow()**. 139 140**System capability**: SystemCapability.PowerManager.DisplayPowerManager 141 142**Parameters** 143 144| Name| Type| Mandatory| Description| 145| -------- | -------- | -------- | -------- | 146| options | [SetKeepScreenOnOptions](#setkeepscreenonoptions) | No| Options for setting the screen to be steady on.| 147 148**Example** 149 150 ```js 151 brightness.setKeepScreenOn({ 152 keepScreenOn: true, 153 success: function () { 154 console.log('handling set keep screen on success.'); 155 }, 156 fail: function (data, code) { 157 console.error('handling set keep screen on fail, code:' + code + ', data: ' + data); 158 } 159 }); 160 ``` 161## GetBrightnessOptions 162 163Defines the options for obtaining the screen brightness. 164 165**System capability**: SystemCapability.PowerManager.DisplayPowerManager 166 167| Name | Type | Mandatory| Description | 168| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 169| success | (data: [BrightnessResponse](#brightnessresponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessResponse](#brightnessresponse) type.| 170| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. | 171| complete | () => void | No | Called when the API call is complete. | 172 173## SetBrightnessOptions 174 175Defines the options for setting the screen brightness. 176 177**System capability**: SystemCapability.PowerManager.DisplayPowerManager 178 179| Name | Type | Mandatory| Description | 180| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 181| value | number | Yes | Screen brightness. The value is an integer ranging from **1** to **255**.<br>- If the value is less than or equal to **0**, value **1** will be used.<br>- If the value is greater than **255**, value **255** will be used.<br>- 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.| 182| success | () => void | No | Callback upon a successful API call. | 183| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. | 184| complete | () => void | No | Called when the API call is complete. | 185 186## BrightnessResponse 187 188Defines a response that returns the screen brightness. 189 190**System capability**: SystemCapability.PowerManager.DisplayPowerManager 191 192| Name| Type| Readable| Writable| Description| 193| -------- | -------- | -------- | -------- | -------- | 194| value | number | Yes| No| Screen brightness. The value ranges from **1** to **255**.| 195 196## GetBrightnessModeOptions 197 198Defines the options for obtaining the screen brightness mode. 199 200**System capability**: SystemCapability.PowerManager.DisplayPowerManager 201 202| Name | Type | Mandatory| Description | 203| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 204| success | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessModeResponse](#brightnessmoderesponse) type.| 205| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. | 206| complete | () => void | No | Called when the API call is complete. | 207 208## SetBrightnessModeOptions 209 210Defines the options for setting the screen brightness mode. 211 212**System capability**: SystemCapability.PowerManager.DisplayPowerManager 213 214| Name | Type | Mandatory| Description | 215| -------- | ------------------------------------ | ---- | ------------------------------------------------------ | 216| mode | number | Yes | The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.| 217| success | () => void | No | Callback upon a successful API call. | 218| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.| 219| complete | () => void | No | Called when the API call is complete. | 220 221## BrightnessModeResponse 222 223Defines a response that returns the screen brightness mode. 224 225**System capability**: SystemCapability.PowerManager.DisplayPowerManager 226 227| Name| Type| Readable| Writable| Description| 228| -------- | -------- | -------- | -------- | -------- | 229| mode | number | Yes| No| The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.| 230 231## SetKeepScreenOnOptions 232 233Defines the options for setting the screen to be steady on. 234 235**System capability**: SystemCapability.PowerManager.DisplayPowerManager 236 237| Name | Type | Mandatory| Description | 238| ------------ | ------------------------------------ | ---- | ------------------------------------------------------ | 239| keepScreenOn | boolean | Yes | The value **true** means to keep the screen steady on, and the value **false** indicates the opposite. | 240| success | () => void | No | Callback upon a successful API call. | 241| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.| 242| complete | () => void | No | Called when the API call is complete. | 243