# @capgo/capacitor-brightness 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-brightness/

版本：8\.0\.24
npm 元数据更新时间：2026-10-15T03:10:50.876Z
中文译文更新时间：2026-11-09T03:59:29.496Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-brightness
原文对照：https://npmcn.com/package/%40capgo/capacitor-brightness/?lang=original
项目主页：https://capgo.app/docs/plugins/brightness/
源码仓库：https://github.com/Cap-go/capacitor-brightness

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：99.4 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-01-04T17:22:42.187Z
- 最新版本发布：2026-10-15T03:10:50.586Z
- 近 30 天下载量：40942（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

IOS和Android上的控制屏幕亮度

## 安装

```sh
npm install @capgo/capacitor-brightness
```

也可以使用：`pnpm add @capgo/capacitor-brightness`、`yarn add @capgo/capacitor-brightness`、`bun add @capgo/capacitor-brightness`

## README

# @ capgo/ 电容- 轻快

从您的 Capacitor app 读取并设置屏幕亮度, 例如在显示 QR 代码或 票 时显示屏幕亮度 。 在Android上,也可以控制系统亮度及其自动模式.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-brightness)](https://capgo.app/?ref=plugin_brightness)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_brightness)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_brightness) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-brightness` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-braightness到我的Capacitor应用上,并把它接上"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_brightness) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_brightness)

![@capgo/capacitor-brightness for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-brightness/main/assets/github-social-preview.png)

## 主要特点

-   **应用亮度**数字 : `getBrightness()` 财务报告和审定财务报表 `setBrightness()` 用于iOS和Android上的当前屏幕.
-   **系统亮度**数字 : `getSystemBrightness()` 财务报告和审定财务报表 `setSystemBrightness()` 安卓号.
-   **亮度模式**数字 : `getSystemBrightnessMode()` 财务报告和审定财务报表 `setSystemBrightnessMode()` 在Android上自动和手动之间切换.
-   **恢复**数字 : `restoreSystemBrightness()` 手控制回系统, `isUsingSystemBrightness()` 请检查当前状态 .
-   **权限**数字 : `checkPermissions()` 财务报告和审定财务报表 `requestPermissions()` 安卓系统设置访问.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-22. 系统亮度和模式仅为Android. 在网上不可用.

## 为什么Capacitor亮?

唯一提供电容的插件 **完全亮度控制** 用于iOS和Android:

-   **App 级别亮度** - 在不影响系统设置的情况下控制活动亮度
-   **系统级亮度** - 修改全球设备亮度(Android)
-   **自动/ 手动模式** - 在自动和手动亮度模式之间切换(Android)
-   **权限处理** - 支持WRITE SETTINGS权限流
-   **跨平台** - 一致的API跨iOS和Android

用于阅读应用程序,视频播放器,相机应用程序,以及需要屏幕亮度控制的任何应用程序.

## 文档

可在下列地点查阅完整文件: [https://capgo.app/docs/plugins/brightness/ 页面存档备份,存于互联网档案馆](https://capgo.app/docs/plugins/brightness/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-brightness` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-brightness
npx cap sync
```

## Android 配置

对于Android来说,如果想要修改系统亮度(不仅仅是应用亮度),就需要添加 `WRITE_SETTINGS` 允许您使用 `AndroidManifest.xml`数字 :

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

注:此权限需要用户通过Android 6.0+上的系统设置确认.

## 所需资源

-   iOS:iOS 15+ (使用UIScreen.braightness) (英语)
-   Android: API 24+(用于应用程序亮度,设置的窗口管理器). 系统亮度系统)

## API 密码

-   [`getBrightness()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getbrightness)
-   [`setBrightness(...)`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-setbrightness)
-   [`getSystemBrightness()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getsystembrightness)
-   [`setSystemBrightness(...)`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-setsystembrightness)
-   [`getSystemBrightnessMode()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getsystembrightnessmode)
-   [`setSystemBrightnessMode(...)`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-setsystembrightnessmode)
-   [`isUsingSystemBrightness()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-isusingsystembrightness)
-   [`restoreSystemBrightness()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-restoresystembrightness)
-   [`isAvailable()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-isavailable)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-requestpermissions)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-enums)

### 获取亮度( )

```typescript
getBrightness() => Promise<GetBrightnessResult>
```

获取设备主屏幕当前亮度水平.

**回返情况:** `Promise<[GetBrightnessResult](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getbrightnessresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 设置亮度(...)

```typescript
setBrightness(options: SetBrightnessOptions) => Promise<void>
```

设置设备主屏幕的亮度级别 .

在iOS上,亮度会持续到设备被锁定. 在Android上,亮度仅适用于当前活性.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SetBrightnessOptions](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-setbrightnessoptions)` | \- 明亮的选择. |

**自:** 8.0.0 (单位:千美元)

* * *

### 获取系统亮度( C)

```typescript
getSystemBrightness() => Promise<GetBrightnessResult>
```

获得全系统屏幕亮度.

**回返情况:** `Promise<[GetBrightnessResult](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getbrightnessresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 系统亮度(...)

```typescript
setSystemBrightness(options: SetBrightnessOptions) => Promise<void>
```

设置全系统屏幕亮度. 在Android上需要WRITE SETTINGS许可. 这也改变了亮度模式为MANAUAL.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SetBrightnessOptions](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-setbrightnessoptions)` | \- 明亮的选择. |

**自:** 8.0.0 (单位:千美元)

* * *

### 获取SystemBrightnessMode ()

```typescript
getSystemBrightnessMode() => Promise<GetBrightnessModeResult>
```

获取当前系统亮度模式(自动或手动). 在Android上需要WRITE SETTINGS许可.

**回返情况:** `Promise<[GetBrightnessModeResult](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getbrightnessmoderesult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### systemBrightness Mode(...) 系统亮度

```typescript
setSystemBrightnessMode(options: SetBrightnessModeOptions) => Promise<void>
```

设置系统亮度模式(自动或手动). 在Android上需要WRITE SETTINGS许可.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SetBrightnessModeOptions](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-setbrightnessmodeoptions)` | \- 亮度模式选项. |

**自:** 8.0.0 (单位:千美元)

* * *

### 是 Using 系统亮度( )

```typescript
isUsingSystemBrightness() => Promise<IsUsingSystemBrightnessResult>
```

检查当前活动是否使用全系统亮度值 .

**回返情况:** `Promise<[IsUsingSystemBrightnessResult](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-isusingsystembrightnessresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 恢复系统亮度( C)

```typescript
restoreSystemBrightness() => Promise<void>
```

重置当前活动的亮度设置以使用全系统值.

**自:** 8.0.0 (单位:千美元)

* * *

### 易读 ()

```typescript
isAvailable() => Promise<IsAvailableResult>
```

检查当前设备是否有亮度 API .

**回返情况:** `Promise<[IsAvailableResult](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-isavailableresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 检查( )

```typescript
checkPermissions() => Promise<PermissionStatus>
```

检查用户访问系统亮度的权限 .

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-permissionstatus)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 请求( )

```typescript
requestPermissions() => Promise<PermissionStatus>
```

请求访问系统亮度的权限 . 在Android上,这打开了系统设置,以授予WRITE SETTINGS权限.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-permissionstatus)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<GetPluginVersionResult>
```

获取本地插件版本 .

**回返情况:** `Promise<[GetPluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-getpluginversionresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 接口

#### 获取亮度

获得Braightness或获得SystemBraightness的结果.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`brightness`** | `number` | 亮度值从0到1. 0是最小亮度, 1是最大亮度. | 8.0.0 (单位:千美元) |

#### 设置亮度选项

SetBraightness 或 setSystemBraightness 的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`brightness`** | `number` | 亮度值从0到1. 0是最小亮度, 1是最大亮度. | 8.0.0 (单位:千美元) |

#### 获取亮度模式

(原始内容存档于2017-10-21). Results of getSystemBrightness Mode.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`mode`** | `[BrightnessMode](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-brightnessmode)` | 当前亮度模式 . | 8.0.0 (单位:千美元) |

#### 设置亮度模式选项

设置SystemBrightnessMode 的选项.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`mode`** | `[BrightnessMode](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-brightnessmode)` | 要设置的亮度模式 。 无法设置为 UNKNOWN . | 8.0.0 (单位:千美元) |

#### 是Using系统亮度反应

结果是Using System Braightness(英语:Using System Braightness). 星洲网.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`isUsing`** | `boolean` | 当前的活动是否使用全系统亮度值. | 8.0.0 (单位:千美元) |

#### 易伤性结果

由此而来.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`available`** | `boolean` | 当前设备中是否有亮度 API . | 8.0.0 (单位:千美元) |

#### 权限状态

许可状态结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`brightness`** | `[PermissionState](https://npmcn.com/package/%40capgo/capacitor-brightness/#readme-permissionstate)` | 是否允许修改系统亮度 . | 8.0.0 (单位:千美元) |

#### 获取 PluginVersion 结果

获取PluginVersion的结果.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`version`** | `string` | 本地插件版本 . | 8.0.0 (单位:千美元) |

### 类型异名

#### 权限状态

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### 数字

#### 亮度模式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`UNKNOWN`** | `0` | 亮度模式不详. | 8.0.0 (单位:千美元) |
| **`AUTOMATIC`** | `1` | 亮度由系统自动调整. | 8.0.0 (单位:千美元) |
| **`MANUAL`** | `2` | 亮度由用户手动设置. | 8.0.0 (单位:千美元) |

## 常见问题

### @capgo/capacitor-brightness 是什么？

IOS和Android上的控制屏幕亮度

### 如何安装 @capgo/capacitor-brightness？

在项目目录运行 npm install @capgo/capacitor-brightness，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-brightness 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-brightness 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-brightness 可以商用吗？

@capgo/capacitor-brightness 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-brightness 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-brightness 在 2026/10/09 – 2026/11/07 这 30 天内被下载 40,942 次，日均约 1,365 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-brightness 还在维护吗？

最新版本 8\.0\.24 发布于 2026/10/15（25 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/01/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。