1# @system.brightness (屏幕亮度) 2 3该模块提供屏幕亮度和模式的查询、调节接口。 4 5> **说明：** 6> 7> - 从API Version 7 开始不再维护。建议使用[`@ohos.brightness`](js-apis-brightness.md)替代，替代接口能力仅对系统应用开放。 8> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 9 10 11## 导入模块 12 13 14```js 15import brightness from '@system.brightness'; 16``` 17 18 19## brightness.getValue 20 21getValue(options?: GetBrightnessOptions): void 22 23获得设备当前的屏幕亮度值。 24 25**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| -------- | -------- | -------- | -------- | 31| options | [GetBrightnessOptions](#getbrightnessoptions) | 否 | 获取屏幕亮度的参数对象。 | 32 33**示例：** 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 51设置设备当前的屏幕亮度值。 52 53**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 54 55**参数：** 56 57| 参数名 | 类型 | 必填 | 说明 | 58| -------- | -------- | -------- | -------- | 59| options | [SetBrightnessOptions](#setbrightnessoptions) | 否 | 设置屏幕亮度的参数对象。 | 60 61**示例：** 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 80获得当前屏幕亮度模式。 81 82**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| -------- | -------- | -------- | -------- | 88| options | [GetBrightnessModeOptions](#getbrightnessmodeoptions) | 否 | 获取屏幕亮度模式的参数对象。 | 89 90**示例：** 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 108设置设备当前的屏幕亮度模式。 109 110**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 111 112**参数：** 113| 参数名 | 类型 | 必填 | 说明 | 114| -------- | -------- | -------- | -------- | 115| options | [SetBrightnessModeOptions](#setbrightnessmodeoptions) | 否 | 设置屏幕亮度模式的参数对象。 | 116 117**示例：** 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>从API version 7开始不再维护，建议使用[window.setKeepScreenOn](js-apis-window.md#setkeepscreenon)替代。 137 138设置屏幕是否保持常亮状态，开启常亮模式推荐在onShow()阶段调用。 139 140**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| -------- | -------- | -------- | -------- | 146| options | [SetKeepScreenOnOptions](#setkeepscreenonoptions) | 否 | 设置屏幕常亮的参数对象。 | 147 148**示例：** 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 163获取屏幕亮度的参数对象。 164 165**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 166 167| 名称 | 类型 | 必填 | 说明 | 168| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 169| success | (data: [BrightnessResponse](#brightnessresponse)) => void | 否 | 接口调用成功的回调函数。data为[BrightnessResponse](#brightnessresponse)类型的返回值。 | 170| fail | (data: string, code: number) => void | 否 | 接口调用失败的回调函数。data为错误信息，code为错误码。 | 171| complete | () => void | 否 | 接口调用结束的回调函数。 | 172 173## SetBrightnessOptions 174 175设置屏幕亮度的参数对象。 176 177**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 178 179| 名称 | 类型 | 必填 | 说明 | 180| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 181| value | number | 是 | 屏幕亮度，值为1-255之间的整数。<br/>- 如果值小于等于0，系统按1处理。<br/>- 如果值大于255，系统按255处理。<br/>- 如果值为小数，系统将处理为整数。例如设置为8.1，系统按8处理。 | 182| success | () => void | 否 | 接口调用成功的回调函数。 | 183| fail | (data: string, code: number) => void | 否 | 接口调用失败的回调函数。data为错误信息，code为错误码。 | 184| complete | () => void | 否 | 接口调用结束的回调函数。 | 185 186## BrightnessResponse 187 188包含屏幕亮度的对象。 189 190**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 191 192| 名称 | 类型 | 可读 | 可写 | 说明 | 193| -------- | -------- | -------- | -------- | -------- | 194| value | number | 是 | 否 | 屏幕亮度，范围：1到255。 | 195 196## GetBrightnessModeOptions 197 198获取屏幕亮度模式的参数对象。 199 200**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 201 202| 名称 | 类型 | 必填 | 说明 | 203| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 204| success | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | 否 | 接口调用成功的回调函数。data为[BrightnessModeResponse](#brightnessmoderesponse)类型的返回值。 | 205| fail | (data: string, code: number) => void | 否 | 接口调用失败的回调函数。data为错误信息，code为错误码。 | 206| complete | () => void | 否 | 接口调用结束的回调函数。 | 207 208## SetBrightnessModeOptions 209 210设置屏幕亮度模式的参数对象。 211 212**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 213 214| 名称 | 类型 | 必填 | 说明 | 215| -------- | ------------------------------------ | ---- | ------------------------------------------------------ | 216| mode | number | 是 | 0表示手动调节屏幕亮度模式，1表示自动调节屏幕亮度模式。 | 217| success | () => void | 否 | 接口调用成功的回调函数。 | 218| fail | (data: string, code: number) => void | 否 | 接口调用失败的回调函数。data为错误信息，code为错误码。 | 219| complete | () => void | 否 | 接口调用结束的回调函数。 | 220 221## BrightnessModeResponse 222 223包含屏幕亮度模式的对象。 224 225**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 226 227| 名称 | 类型 | 可读 | 可写 | 说明 | 228| -------- | -------- | -------- | -------- | -------- | 229| mode | number | 是 | 否 | 0表示手动调节屏幕亮度模式，1表示自动调节屏幕亮度模式。 | 230 231## SetKeepScreenOnOptions 232 233设置屏幕常亮的参数对象。 234 235**系统能力：** SystemCapability.PowerManager.DisplayPowerManager 236 237| 名称 | 类型 | 必填 | 说明 | 238| ------------ | ------------------------------------ | ---- | ------------------------------------------------------ | 239| keepScreenOn | boolean | 是 | true表示保持屏幕常亮，false表示取消屏幕常亮。 | 240| success | () => void | 否 | 接口调用成功的回调函数。 | 241| fail | (data: string, code: number) => void | 否 | 接口调用失败的回调函数。data为错误信息，code为错误码。 | 242| complete | () => void | 否 | 接口调用结束的回调函数。 | 243 244