Expo 亮度

提供对 API 的访问以获取和设置屏幕亮度的库。

Android

iOS

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

¥An API to get and set screen brightness.

在 Android 上，有一个全局系统范围的亮度设置，每个应用都有自己的亮度设置，可以选择覆盖全局设置。可以使用此 API 设置这些值中的任何一个。在 iOS 上，无法以编程方式更改系统亮度设置；相反，对屏幕亮度的任何更改都会持续存在，直到设备锁定或关闭。

¥On Android, there is a global system-wide brightness setting, and each app has its own brightness setting that can optionally override the global setting. It is possible to set either of these values with this API. On iOS, the system brightness setting cannot be changed programmatically; instead, any changes to the screen brightness will persist until the device is locked or powered off.

安装

¥Installation

Terminal

- npx expo install expo-brightness

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

配置

¥Configuration

Are you using this library in a bare React Native app?

了解如何在 expo-brightness 存储库中的安装说明文件中配置原生项目。

¥Learn how to configure the native projects in the installation instructions in the expo-brightness repository.

用法

¥Usage

Basic Brightness Usage

import React, { 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>Brightness Module Example</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)`

Name	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:

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

Example

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

Methods

`Brightness.getBrightnessAsync()`

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()`

Checks user's permissions for accessing system brightness.

Returns:

Promise<PermissionResponse>

A promise that fulfils with an object of type PermissionResponse.

Only for:

Android

`Brightness.getSystemBrightnessAsync()`

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.

Only for:

Android

`Brightness.getSystemBrightnessModeAsync()`

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()`

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.

Only for:

Android

`Brightness.isUsingSystemBrightnessAsync()`

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()`

Asks the user to grant permissions for accessing system brightness.

Returns:

Promise<PermissionResponse>

A promise that fulfils with an object of type PermissionResponse.

Only for:

Android

`Brightness.restoreSystemBrightnessAsync()`

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)`

Name	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.

Only for:

Android

`Brightness.setSystemBrightnessAsync(brightnessValue)`

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

WARNING: This method is experimental.

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.

Only for:

Android

`Brightness.setSystemBrightnessModeAsync(brightnessMode)`

Name	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>

Deprecated Use restoreSystemBrightnessAsync method instead.

Only for:

Android

`Brightness.useSystemBrightnessAsync()`

Returns:

Promise<void>

Event Subscriptions

Only for:

iOS

`Brightness.addBrightnessListener(listener)`

Name	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:

Subscription

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

Interfaces

`PermissionResponse`

An object obtained by permissions get and request functions.

PermissionResponse Properties

Name	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.

Types

`BrightnessEvent`

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

`PermissionExpiration`

Literal Type: multiple types

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

Acceptable values are: 'never' | number

¥You must add the following permissions to your app.json inside the expo.android.permissions array.

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

iOS 系统

¥iOS

无需任何权限。

¥No permissions required.