# @anuradev/capacitor-background-mode 中文文档

规范地址：https://npmcn.com/package/%40anuradev/capacitor-background-mode/

版本：8\.1\.0
npm 元数据更新时间：2026-08-15T23:44:24.159Z
中文译文更新时间：2026-11-06T07:30:19.254Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40anuradev/capacitor-background-mode
原文对照：https://npmcn.com/package/%40anuradev/capacitor-background-mode/?lang=original
项目主页：https://github.com/angeloraso/capacitor-background-mode.git#readme
源码仓库：https://github.com/angeloraso/capacitor-background-mode.git

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

- 包体积（解压后）：106 kB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2023-05-02T14:10:36.940Z
- 最新版本发布：2026-08-15T23:44:24.012Z
- 近 30 天下载量：8372（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 6 个）

## 中文简介

启用背景模式的电容插件

## 安装

```sh
npm install @anuradev/capacitor-background-mode
```

也可以使用：`pnpm add @anuradev/capacitor-background-mode`、`yarn add @anuradev/capacitor-background-mode`、`bun add @anuradev/capacitor-background-mode`

## README

# @anuradev/电容-背景-模式

启用背景模式的电容插件

此插件替换为 [电容器-插件-背景-模式](https://github.com/angeloraso/capacitor-plugin-background-mode)

## 安装

```bash
npm install @anuradev/capacitor-background-mode
npx cap sync
```

### 背景麦克风访问

背景麦克风访问默认被禁用 。 为了启用它,宣布 消费申请中要求的许可 `AndroidManifest.xml`数字 :

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

请求麦克风许可并启用前台服务:

```typescript
await BackgroundMode.requestMicrophonePermission();
await BackgroundMode.enable({ allowMicrophoneInBackground: true });
```

## API 密码

-   [`enable(...)`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-enable)
-   [`disable()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-disable)
-   [`updateNotification(...)`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-updatenotification)
-   [`checkNotificationsPermission()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-checknotificationspermission)
-   [`requestNotificationsPermission()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-requestnotificationspermission)
-   [`checkMicrophonePermission()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-checkmicrophonepermission)
-   [`requestMicrophonePermission()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-requestmicrophonepermission)
-   [`checkBatteryOptimizations()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-checkbatteryoptimizations)
-   [`requestDisableBatteryOptimizations()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-requestdisablebatteryoptimizations)
-   [`enableWebViewOptimizations()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-enablewebviewoptimizations)
-   [`disableWebViewOptimizations()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-disablewebviewoptimizations)
-   [`moveToBackground()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-movetobackground)
-   [`moveToForeground()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-movetoforeground)
-   [`isScreenOff()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-isscreenoff)
-   [`isEnabled()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-isenabled)
-   [`isActive()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-isactive)
-   [`wakeUp()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-wakeup)
-   [`unlock()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-unlock)
-   [`addListener('appInBackground', ...)`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-addlistenerappinbackground-)
-   [`addListener('appInForeground', ...)`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-addlistenerappinforeground-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-type-aliases)

### 启用(...)

```typescript
enable(settings: Partial<ISettings>) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`settings`** | `[Partial](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-partial)<[ISettings](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-isettings)>` |

* * *

### 禁用( c)

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

* * *

### 更新通知(...)

```typescript
updateNotification(settings: Partial<ISettings>) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`settings`** | `[Partial](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-partial)<[ISettings](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-isettings)>` |

* * *

### 检查通知

```typescript
checkNotificationsPermission() => Promise<NotificationPermissionStatus>
```

**回返情况:** `Promise<[NotificationPermissionStatus](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-notificationpermissionstatus)>`

* * *

### 批准()

```typescript
requestNotificationsPermission() => Promise<NotificationPermissionStatus>
```

**回返情况:** `Promise<[NotificationPermissionStatus](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-notificationpermissionstatus)>`

* * *

### 麦克风

```typescript
checkMicrophonePermission() => Promise<MicrophonePermissionStatus>
```

**回返情况:** `Promise<[MicrophonePermissionStatus](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-microphonepermissionstatus)>`

* * *

### 麦克风

```typescript
requestMicrophonePermission() => Promise<MicrophonePermissionStatus>
```

**回返情况:** `Promise<[MicrophonePermissionStatus](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-microphonepermissionstatus)>`

* * *

### 检查 Battery Optimizations ()

```typescript
checkBatteryOptimizations() => Promise<{ enabled: boolean; }>
```

**回返情况:** `Promise<{ enabled: boolean; }>`

* * *

### 不可拆卸电池 Optimizations ()

```typescript
requestDisableBatteryOptimizations() => Promise<{ enabled: boolean; }>
```

**回返情况:** `Promise<{ enabled: boolean; }>`

* * *

### 启用WebViewoptimizations ()

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

* * *

### 禁用WebView optimization ()

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

* * *

### 移动背景 ()

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

* * *

### 移动到前景 ()

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

* * *

### isScreenOff () (中文(简体) )

```typescript
isScreenOff() => Promise<{ isScreenOff: boolean; }>
```

**回返情况:** `Promise<{ isScreenOff: boolean; }>`

* * *

### 已启用

```typescript
isEnabled() => Promise<{ enabled: boolean; }>
```

**回返情况:** `Promise<{ enabled: boolean; }>`

* * *

### 正态( A)

```typescript
isActive() => Promise<{ activated: boolean; }>
```

**回返情况:** `Promise<{ activated: boolean; }>`

* * *

### 唤醒( )

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

* * *

### 解锁( )

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

* * *

### 添加倾听器( “ 应用背景” ,...)

```typescript
addListener(eventName: 'appInBackground', listenerFunc: () => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'appInBackground'` |
| **`listenerFunc`** | `() => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-pluginlistenerhandle)>`

* * *

### 添加倾听器( “ 应用前景 ” ,...)

```typescript
addListener(eventName: 'appInForeground', listenerFunc: () => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'appInForeground'` |
| **`listenerFunc`** | `() => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-pluginlistenerhandle)>`

* * *

### 删除所有收听器( )

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

* * *

### 接口

#### 定居

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`title`** | `string` |  |  |
| **`text`** | `string` |  |  |
| **`subText`** | `string` |  |  |
| **`bigText`** | `boolean` |  |  |
| **`resume`** | `boolean` |  |  |
| **`silent`** | `boolean` |  |  |
| **`hidden`** | `boolean` |  |  |
| **`color`** | `string` |  |  |
| **`icon`** | `string` |  |  |
| **`channelName`** | `string` |  |  |
| **`channelDescription`** | `string` |  |  |
| **`allowClose`** | `boolean` |  |  |
| **`closeIcon`** | `string` |  |  |
| **`closeTitle`** | `string` |  |  |
| **`showWhen`** | `boolean` |  |  |
| **`disableWebViewOptimization`** | `boolean` |  |  |
| **`allowMicrophoneInBackground`** | `boolean` | 允许前台服务在应用程序处于后台时使用麦克风. | `false` |
| **`visibility`** | `'public' | 'private' | 'secret'` |  |  |

#### 通知状态

| Prop | 类型 |
| --- | --- |
| **`notifications`** | `[PermissionState](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-permissionstate)` |

#### 微型电话

| Prop | 类型 |
| --- | --- |
| **`microphone`** | `[PermissionState](https://npmcn.com/package/%40anuradev/capacitor-background-mode/#readme-permissionstate)` |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

### 类型异名

#### 部分

让 T 中的所有属性可选

`{ [P in keyof T]?: T[P]; }`

#### 权限状态

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

## 常见问题

### @anuradev/capacitor-background-mode 是什么？

启用背景模式的电容插件

### 如何安装 @anuradev/capacitor-background-mode？

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

### @anuradev/capacitor-background-mode 支持 TypeScript 吗？

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

### @anuradev/capacitor-background-mode 支持 ESM 还是 CommonJS？

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

### @anuradev/capacitor-background-mode 可以商用吗？

@anuradev/capacitor-background-mode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @anuradev/capacitor-background-mode 的下载量有多少？

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

### @anuradev/capacitor-background-mode 还在维护吗？

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