js-apis-system-brightness.md 9.7 KB
Newer Older
1
# @system.brightness (屏幕亮度)
Z
zengyawen 已提交
2

A
aqxyjay 已提交
3 4
该模块提供屏幕亮度和模式的查询、调节接口。

zyjhandsome's avatar
zyjhandsome 已提交
5
> **说明:**
Z
zengyawen 已提交
6 7
>
> - 从API Version 7 开始不再维护。建议使用[`@ohos.brightness`](js-apis-brightness.md)替代,替代接口能力仅对系统应用开放。
A
aqxyjay 已提交
8
> - 本模块首批接口从API version 3开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
Z
zengyawen 已提交
9 10 11 12 13


## 导入模块


A
aqxyjay 已提交
14
```js
Z
zengyawen 已提交
15 16 17 18 19 20
import brightness from '@system.brightness';
```


## brightness.getValue

A
aqxyjay 已提交
21
getValue(options?: GetBrightnessOptions): void
Z
zengyawen 已提交
22 23 24

获得设备当前的屏幕亮度值。

25
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
zengyawen 已提交
26 27

**参数:**
28

Z
zengyawen 已提交
29 30
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
liangjunhao 已提交
31
| options | [GetBrightnessOptions](#getbrightnessoptions) | 否   | 获取屏幕亮度的参数对象。可选,默认为空。 |
Z
zengyawen 已提交
32 33 34

**示例:**

A
aqxyjay 已提交
35
  ```js
A
aqxyjay 已提交
36
  brightness.getValue({
37 38
      success: (data: BrightnessResponse) => {
        console.log('success get brightness value:' + data.value);
A
aqxyjay 已提交
39
      },
40 41
      fail: (data: string, code: number) => {
        console.error('get brightness fail, code: ' + code + ', data: ' + data);
A
aqxyjay 已提交
42 43
      }
  });
Z
zengyawen 已提交
44 45 46 47 48
  ```


## brightness.setValue

Z
Zhangchunxin 已提交
49
setValue(options?: SetBrightnessOptions): void
Z
zengyawen 已提交
50 51 52

设置设备当前的屏幕亮度值。

53
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
zengyawen 已提交
54 55

**参数:**
56

Z
zengyawen 已提交
57 58
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
liangjunhao 已提交
59
| options | [SetBrightnessOptions](#setbrightnessoptions) | 否   | 设置屏幕亮度的参数对象。可选,默认为空。 |
Z
zengyawen 已提交
60 61 62

**示例:**

A
aqxyjay 已提交
63
  ```js
A
aqxyjay 已提交
64 65
  brightness.setValue({
      value: 100,
66 67
      success: () => {
        console.log('handling set brightness success.');
A
aqxyjay 已提交
68
      },
69 70
      fail: (data: string, code: number) => {
        console.error('handling set brightness value fail, code:' + code + ', data: ' + data);
A
aqxyjay 已提交
71 72
      }
  });
Z
zengyawen 已提交
73 74 75 76 77
  ```


## brightness.getMode

Z
Zhangchunxin 已提交
78
getMode(options?: GetBrightnessModeOptions): void
Z
zengyawen 已提交
79 80 81

获得当前屏幕亮度模式。

82
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
zengyawen 已提交
83 84

**参数:**
85

Z
zengyawen 已提交
86 87
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
liangjunhao 已提交
88
| options | [GetBrightnessModeOptions](#getbrightnessmodeoptions) | 否 | 获取屏幕亮度模式的参数对象。可选,默认为空。 |
89

Z
zengyawen 已提交
90 91
**示例:**

A
aqxyjay 已提交
92
  ```js
A
aqxyjay 已提交
93
  brightness.getMode({
94 95
      success: (data: BrightnessModeResponse) => {
        console.log('success get mode:' + data.mode);
A
aqxyjay 已提交
96
      },
97 98
      fail: (data: string, code: number) => {
        console.error('handling get mode fail, code:' + code + ', data: ' + data);
A
aqxyjay 已提交
99 100
      }
  });
Z
zengyawen 已提交
101 102 103 104 105
  ```


## brightness.setMode

A
aqxyjay 已提交
106
setMode(options?: SetBrightnessModeOptions): void
Z
zengyawen 已提交
107 108 109

设置设备当前的屏幕亮度模式。

110
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
zengyawen 已提交
111 112 113 114

**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
liangjunhao 已提交
115
| options | [SetBrightnessModeOptions](#setbrightnessmodeoptions) | 否   | 设置屏幕亮度模式的参数对象。可选,默认为空。 |
Z
zengyawen 已提交
116 117 118

**示例:**

A
aqxyjay 已提交
119
  ```js
A
aqxyjay 已提交
120 121
  brightness.setMode({
      mode: 1,
122 123
      success: () => {
        console.log('handling set mode success.');
A
aqxyjay 已提交
124
      },
125 126
      fail: (data: string, code: number) => {
        console.error('handling set mode fail, code:' + code + ', data: ' + data);
A
aqxyjay 已提交
127 128
      }
  });
Z
zengyawen 已提交
129 130 131 132 133
  ```


## brightness.setKeepScreenOn

A
aqxyjay 已提交
134
setKeepScreenOn(options?: SetKeepScreenOnOptions): void
A
aqxyjay 已提交
135 136

>从API version 7开始不再维护,建议使用[window.setKeepScreenOn](js-apis-window.md#setkeepscreenon)替代。
Z
zengyawen 已提交
137 138 139

设置屏幕是否保持常亮状态,开启常亮模式推荐在onShow()阶段调用。

140
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
zengyawen 已提交
141 142

**参数:**
A
aqxyjay 已提交
143

Z
zengyawen 已提交
144 145
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
liangjunhao 已提交
146
| options | [SetKeepScreenOnOptions](#setkeepscreenonoptions) | 否 | 设置屏幕常亮的参数对象。可选,默认为空。 |
Z
zengyawen 已提交
147 148 149

**示例:**

A
aqxyjay 已提交
150
  ```js
A
aqxyjay 已提交
151 152
  brightness.setKeepScreenOn({
      keepScreenOn: true,
153 154
      success: () => {
        console.log('handling set keep screen on success.');
A
aqxyjay 已提交
155
      },
156 157
      fail: (data: string, code: number) => {
        console.error('handling set keep screen on fail, code:' + code + ', data: ' + data);
A
aqxyjay 已提交
158 159
      }
  });
Z
zengyawen 已提交
160
  ```
A
aqxyjay 已提交
161 162 163 164
## GetBrightnessOptions

获取屏幕亮度的参数对象。

165
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
166

A
aqxyjay 已提交
167 168 169 170 171 172 173 174 175 176
| 名称     | 类型                                                      | 必填 | 说明                                                         |
| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| success  | (data: [BrightnessResponse](#brightnessresponse)) => void | 否   | 接口调用成功的回调函数。data为[BrightnessResponse](#brightnessresponse)类型的返回值。 |
| fail     | (data: string, code: number) => void                      | 否   | 接口调用失败的回调函数。data为错误信息,code为错误码。       |
| complete | () => void                                                | 否   | 接口调用结束的回调函数。                                     |

## SetBrightnessOptions

设置屏幕亮度的参数对象。

177
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
178

A
aqxyjay 已提交
179 180 181 182 183 184
| 名称     | 类型                                 | 必填 | 说明                                                         |
| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| value    | number                               | 是   | 屏幕亮度,值为1-255之间的整数。<br/>-&nbsp;如果值小于等于0,系统按1处理。<br/>-&nbsp;如果值大于255,系统按255处理。<br/>-&nbsp;如果值为小数,系统将处理为整数。例如设置为8.1,系统按8处理。 |
| success  | () => void                           | 否   | 接口调用成功的回调函数。                                     |
| fail     | (data: string, code: number) => void | 否   | 接口调用失败的回调函数。data为错误信息,code为错误码。       |
| complete | () => void                           | 否   | 接口调用结束的回调函数。                                     |
185 186 187

## BrightnessResponse

A
aqxyjay 已提交
188 189
包含屏幕亮度的对象。

190
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
191 192 193 194

| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| value | number | 是 | 否 | 屏幕亮度,范围:1到255。 |
A
aqxyjay 已提交
195 196 197 198 199

## GetBrightnessModeOptions

获取屏幕亮度模式的参数对象。

200
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
201

A
aqxyjay 已提交
202 203 204 205 206 207 208 209 210 211
| 名称     | 类型                                                         | 必填 | 说明                                                         |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| success  | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | 否   | 接口调用成功的回调函数。data为[BrightnessModeResponse](#brightnessmoderesponse)类型的返回值。 |
| fail     | (data: string, code: number) => void                         | 否   | 接口调用失败的回调函数。data为错误信息,code为错误码。       |
| complete | () => void                                                   | 否   | 接口调用结束的回调函数。                                     |

## SetBrightnessModeOptions

设置屏幕亮度模式的参数对象。

212
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
213

A
aqxyjay 已提交
214 215 216 217 218 219
| 名称     | 类型                                 | 必填 | 说明                                                   |
| -------- | ------------------------------------ | ---- | ------------------------------------------------------ |
| mode     | number                               | 是   | 0表示手动调节屏幕亮度模式,1表示自动调节屏幕亮度模式。 |
| success  | () => void                           | 否   | 接口调用成功的回调函数。                               |
| fail     | (data: string, code: number) => void | 否   | 接口调用失败的回调函数。data为错误信息,code为错误码。 |
| complete | () => void                           | 否   | 接口调用结束的回调函数。                               |
220

221 222
## BrightnessModeResponse

A
aqxyjay 已提交
223 224
包含屏幕亮度模式的对象。

225
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
226 227 228 229

| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| mode | number | 是 | 否 | 0表示手动调节屏幕亮度模式,1表示自动调节屏幕亮度模式。 |
A
aqxyjay 已提交
230 231 232 233 234

## SetKeepScreenOnOptions

设置屏幕常亮的参数对象。

235
**系统能力:** SystemCapability.PowerManager.DisplayPowerManager.Lite
Z
Zhangchunxin 已提交
236

A
aqxyjay 已提交
237 238 239 240 241 242
| 名称         | 类型                                 | 必填 | 说明                                                   |
| ------------ | ------------------------------------ | ---- | ------------------------------------------------------ |
| keepScreenOn | boolean                              | 是   | true表示保持屏幕常亮,false表示取消屏幕常亮。          |
| success      | () => void                           | 否   | 接口调用成功的回调函数。                               |
| fail         | (data: string, code: number) => void | 否   | 接口调用失败的回调函数。data为错误信息,code为错误码。 |
| complete     | () => void                           | 否   | 接口调用结束的回调函数。                               |
243