Expo 亮度

一个提供用于获取和设置屏幕亮度 API 访问的库。

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

Bundled version:

~55.0.0

一种用于获取和设置屏幕亮度的 API。

在 Android 上，有一个全局的系统级亮度设置，并且每个应用都有自己的亮度设置，可以选择性地覆盖全局设置。使用此 API 可以设置这两个值中的任意一个。在 iOS 上，系统亮度设置不能通过程序方式更改；相反，对屏幕亮度所做的任何更改都会一直保留，直到设备锁定或断电。

安装

Terminal

- npx expo install expo-brightness

If you are installing this in an existing React Native app, make sure to install expo in your project.

配置

Are you using this library in an existing React Native app?

如果你没有使用 Continuous Native Generation (CNG)，或者你正在手动使用原生 android 项目，那么你需要将 android.permission.WRITE_SETTINGS 权限添加到 AndroidManifest.xml 文件中：

android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.WRITE_SETTINGS" />

使用

基础亮度用法

import { useEffect } from 'react';
import { StyleSheet, View, Text } from 'react-native';
import * as Brightness from 'expo-brightness';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await Brightness.requestPermissionsAsync();
      if (status === 'granted') {
        Brightness.setSystemBrightnessAsync(1);
      }
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>亮度模块示例</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

API

import * as Brightness from 'expo-brightness';

Hooks

`usePermissions(options)`

Android

iOS

Parameter	Type
options(optional)	`PermissionHookOptions<object>`

Check or request permissions to modify the system brightness. This uses both requestPermissionAsync and getPermissionsAsync to interact with the permissions.

Returns:

[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Example

const [permissionResponse, requestPermission] = Brightness.usePermissions();

Methods

`Brightness.getBrightnessAsync()`

Android

iOS

Gets the current brightness level of the device's main screen.

Returns:

Promise<number>

A Promise that fulfils with a number between 0 and 1, inclusive, representing the current screen brightness.

`Brightness.getPermissionsAsync()`

Android

iOS

Checks user's permissions for accessing system brightness.

Returns:

Promise<PermissionResponse>

A promise that fulfils with an object of type PermissionResponse.

`Brightness.getSystemBrightnessAsync()`

Android

Gets the global system screen brightness.

Returns:

Promise<number>

A Promise that is resolved with a number between 0 and 1, inclusive, representing the current system screen brightness.

`Brightness.getSystemBrightnessModeAsync()`

Android

Gets the system brightness mode (e.g. whether or not the OS will automatically adjust the screen brightness depending on ambient light).

Returns:

Promise<BrightnessMode>

A Promise that fulfils with a BrightnessMode. Requires SYSTEM_BRIGHTNESS permissions.

`Brightness.isAvailableAsync()`

Android

iOS

Returns whether the Brightness API is enabled on the current device. This does not check the app permissions.

Returns:

Promise<boolean>

Async boolean, indicating whether the Brightness API is available on the current device. Currently this resolves true on iOS and Android only.

`Brightness.isUsingSystemBrightnessAsync()`

Android

Returns a boolean specifying whether or not the current activity is using the system-wide brightness value.

Returns:

Promise<boolean>

A Promise that fulfils with true when the current activity is using the system-wide brightness value, and false otherwise.

`Brightness.requestPermissionsAsync()`

Android

iOS

Asks the user to grant permissions for accessing system brightness.

Returns:

Promise<PermissionResponse>

A promise that fulfils with an object of type PermissionResponse.

`Brightness.restoreSystemBrightnessAsync()`

Android

Resets the brightness setting of the current activity to use the system-wide brightness value rather than overriding it.

Returns:

Promise<void>

A Promise that fulfils when the setting has been successfully changed.

`Brightness.setBrightnessAsync(brightnessValue)`

Android

iOS

Parameter	Type	Description
brightnessValue	`number`	A number between `0` and `1`, inclusive, representing the desired screen brightness.

Sets the current screen brightness. On iOS, this setting will persist until the device is locked, after which the screen brightness will revert to the user's default setting. On Android, this setting only applies to the current activity; it will override the system brightness value whenever your app is in the foreground.

Returns:

Promise<void>

A Promise that fulfils when the brightness has been successfully set.

`Brightness.setSystemBrightnessAsync(brightnessValue)`

Experimental

•

Android

Parameter	Type	Description
brightnessValue	`number`	A number between `0` and `1`, inclusive, representing the desired screen brightness.

Sets the global system screen brightness and changes the brightness mode to MANUAL. Requires SYSTEM_BRIGHTNESS permissions.

Returns:

Promise<void>

A Promise that fulfils when the brightness has been successfully set.

`Brightness.setSystemBrightnessModeAsync(brightnessMode)`

Android

Parameter	Type	Description
brightnessMode	`BrightnessMode`	One of `BrightnessMode.MANUAL` or `BrightnessMode.AUTOMATIC`. The system brightness mode cannot be set to `BrightnessMode.UNKNOWN`.

Sets the system brightness mode.

Returns:

Promise<void>

Event Subscriptions

`Brightness.addBrightnessListener(listener)`

iOS

Parameter	Type	Description
listener	`(event: BrightnessEvent) => void`	A callback that is invoked when brightness (iOS) changes. The callback is provided a single argument that is an object with a `brightness` key.

Subscribe to brightness (iOS) updates. The event fires whenever the power mode is toggled.

On web and android the event never fires.

Returns:

EventSubscription

A Subscription object on which you can call remove() to unsubscribe from the listener.

Types

`BrightnessEvent`

Android

iOS

Property	Type	Description
brightness	`number`	A number between `0` and `1`, inclusive, representing the current screen brightness.

`PermissionExpiration`

Android

iOS

Literal Type: union

Permission expiration time. Currently, all permissions are granted permanently.

Acceptable values are: 'never' | number

`PermissionHookOptions`

Android

iOS

Literal Type: union

Acceptable values are: PermissionHookBehavior | Options

`PermissionResponse`

Android

iOS

An object obtained by permissions get and request functions.

Property	Type	Description
canAskAgain	`boolean`	Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission.
expires	`PermissionExpiration`	Determines time when the permission expires.
granted	`boolean`	A convenience boolean that indicates if the permission is granted.
status	`PermissionStatus`	Determines the status of the permission.

Enums

`BrightnessMode`

Android

iOS

`UNKNOWN`

BrightnessMode.UNKNOWN ＝ 0

Means that the current brightness mode cannot be determined.

`AUTOMATIC`

BrightnessMode.AUTOMATIC ＝ 1

Mode in which the device OS will automatically adjust the screen brightness depending on the ambient light.

`MANUAL`

BrightnessMode.MANUAL ＝ 2

Mode in which the screen brightness will remain constant and will not be adjusted by the OS.

`PermissionStatus`

Android

iOS

`DENIED`

PermissionStatus.DENIED ＝ "denied"

User has denied the permission.

`GRANTED`

PermissionStatus.GRANTED ＝ "granted"

User has granted the permission.

`UNDETERMINED`

PermissionStatus.UNDETERMINED ＝ "undetermined"

User hasn't granted or denied the permission yet.

错误代码

`ERR_BRIGHTNESS`

在获取或设置应用亮度时发生错误。

`ERR_BRIGHTNESS_MODE`

在获取或设置系统亮度模式时发生错误。有关更多信息，请查看抛出错误的 nativeError 属性。

`ERR_BRIGHTNESS_PERMISSIONS_DENIED`

在没有用户适当权限的情况下尝试设置系统亮度。用户未授予 SYSTEM_BRIGHTNESS 权限。

`ERR_BRIGHTNESS_SYSTEM`

在获取或设置系统亮度时发生错误。

`ERR_INVALID_ARGUMENT`

传入了无效参数。只允许 BrightnessMode.MANUAL 或 BrightnessMode.AUTOMATIC。

权限

Android

你必须将以下权限添加到 app.json 中 expo.android.permissions 数组内的 expo.android.permissions。

Android Permission	Description
`WRITE_SETTINGS`	Allows an application to read or write the system settings.

iOS

无需权限。