1# @system.brightness (Screen Brightness) 2 3The **brightness** module provides APIs for querying and adjusting the screen brightness and mode. 4 5> **NOTE** 6> - The APIs of this module are no longer maintained since API version 7. It is recommended that you use [`@ohos.brightness`](js-apis-brightness.md) instead. 7> - 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. 8 9 10## Modules to Import 11 12 13```js 14import brightness from '@system.brightness'; 15``` 16 17 18## brightness.getValue 19 20getValue(options?: GetBrightnessOptions): void 21 22Obtains the current screen brightness. 23 24**System capability**: SystemCapability.PowerManager.DisplayPowerManager 25 26**Parameters** 27 28| Name| Type| Mandatory| Description| 29| -------- | -------- | -------- | -------- | 30| options | [GetBrightnessOptions](#getbrightnessoptions) | No | Options for obtaining the screen brightness.| 31 32**Example** 33 34 ```js 35 brightness.getValue({ 36 success: function(data) { 37 console.log('success get brightness value:' + data.value); 38 }, 39 fail: function(data, code) { 40 console.error('get brightness fail, code: ' + code + ', data: ' + data); 41 } 42 }); 43 ``` 44 45 46## brightness.setValue 47 48setValue(options?: SetBrightnessOptions): void 49 50Sets the screen brightness. 51 52**System capability**: SystemCapability.PowerManager.DisplayPowerManager 53 54**Parameters** 55 56| Name| Type| Mandatory| Description| 57| -------- | -------- | -------- | -------- | 58| options | [SetBrightnessOptions](#setbrightnessoptions) | No | Options for setting the screen brightness.| 59 60**Example** 61 62 ```js 63 brightness.setValue({ 64 value: 100, 65 success: function() { 66 console.log('handling set brightness success.'); 67 }, 68 fail: function(data, code) { 69 console.error('handling set brightness value fail, code:' + code + ', data: ' + data); 70 } 71 }); 72 ``` 73 74 75## brightness.getMode 76 77getMode(options?: GetBrightnessModeOptions): void 78 79Obtains the screen brightness adjustment mode. 80 81**System capability**: SystemCapability.PowerManager.DisplayPowerManager 82 83**Parameters** 84 85| Name| Type| Mandatory| Description| 86| -------- | -------- | -------- | -------- | 87| options | [GetBrightnessModeOptions](#getbrightnessmodeoptions) | No| Options for obtaining the screen brightness mode.| 88 89**Example** 90 91 ```js 92 brightness.getMode({ 93 success: function(data) { 94 console.log('success get mode:' + data.mode); 95 }, 96 fail: function(data, code){ 97 console.error('handling get mode fail, code:' + code + ', data: ' + data); 98 } 99 }); 100 ``` 101 102 103## brightness.setMode 104 105setMode(options?: SetBrightnessModeOptions): void 106 107Sets the screen brightness adjustment mode. 108 109**System capability**: SystemCapability.PowerManager.DisplayPowerManager 110 111**Parameters** 112| Name| Type| Mandatory| Description| 113| -------- | -------- | -------- | -------- | 114| options | [SetBrightnessModeOptions](#setbrightnessmodeoptions) | No | Options for setting the screen brightness mode.| 115 116**Example** 117 118 ```js 119 brightness.setMode({ 120 mode: 1, 121 success: function() { 122 console.log('handling set mode success.'); 123 }, 124 fail: function(data, code) { 125 console.error('handling set mode fail, code:' + code + ', data: ' + data); 126 } 127 }); 128 ``` 129 130 131## brightness.setKeepScreenOn 132 133setKeepScreenOn(options?: SetKeepScreenOnOptions): void 134 135> NOTE<br> 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 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 | Called when API call is successful. | 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 API call is complete. | 185 186## BrightnessResponse 187 188Defines a response that returns the screen brightness. 189 190| Parameter| Type | Readable | Writable | Description| 191| -------- | -------- | -------- | -------- | -------- | 192| value | number | Yes | No | Screen brightness. The value ranges from 1 to 255.| 193 194## GetBrightnessModeOptions 195 196Gets the options of the screen brightness mode. 197 198**System capability**: SystemCapability.PowerManager.DisplayPowerManager 199 200| Name | Type | Mandatory| Description | 201| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 202| success | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessModeResponse](#brightnessmoderesponse) type.| 203| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. | 204| complete | () => void | No | Called when API call is complete. | 205 206## SetBrightnessModeOptions 207 208Sets the options of the screen brightness mode. 209 210**System capability**: SystemCapability.PowerManager.DisplayPowerManager 211 212| Name | Type | Mandatory| Description | 213| -------- | ------------------------------------ | ---- | ------------------------------------------------------ | 214| mode | number | Yes | The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.| 215| success | () => void | No | Called when API call is successful. | 216| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.| 217| complete | () => void | No | Called when API call is complete. | 218 219## BrightnessModeResponse 220 221Defines a response that returns the screen brightness mode. 222 223| Parameter| Type | Readable | Writable | Description| 224| -------- | -------- | -------- | -------- | -------- | 225| mode | number | Yes | No | The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.| 226 227## SetKeepScreenOnOptions 228 229Sets the options for keeping the screen steady on. 230 231**System capability**: SystemCapability.PowerManager.DisplayPowerManager 232 233| Name | Type | Mandatory| Description | 234| ------------ | ------------------------------------ | ---- | ------------------------------------------------------ | 235| keepScreenOn | boolean | Yes | The value **true** means to keep the screen steady on, and the value **false** indicates the opposite. | 236| success | () => void | No | Called when API call is successful. | 237| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.| 238| complete | () => void | No | Called when API call is complete. | 239