# @capawesome-team/capacitor-android-foreground-service 中文文档

规范地址：https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/

版本：8\.1\.0
npm 元数据更新时间：2026-03-17T15:36:05.564Z
中文译文更新时间：2026-11-09T02:53:22.741Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capawesome-team/capacitor-android-foreground-service
原文对照：https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/?lang=original
项目主页：https://capawesome.io/plugins/android-foreground-service/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

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

- 包体积（解压后）：102 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2023-10-21T14:43:16.069Z
- 最新版本发布：2026-03-17T15:36:05.234Z
- 近 30 天下载量：71493（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 3 个）

## 中文简介

电容插件在Android上运行一个前景服务.

## 安装

```sh
npm install @capawesome-team/capacitor-android-foreground-service
```

也可以使用：`pnpm add @capawesome-team/capacitor-android-foreground-service`、`yarn add @capawesome-team/capacitor-android-foreground-service`、`bun add @capawesome-team/capacitor-android-foreground-service`

## README

# @capawesome-team/电容-和机器人-前地服务

电容插件在Android上运行一个前景服务.

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |

## 安装

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

```bash
npx skills add capawesome-team/skills
```

然后使用下列提示:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-android-foreground-service` plugin in my project.
```

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

```bash
npm install @capawesome-team/capacitor-android-foreground-service
npx cap sync
```

### 机器人

此 API 需要将以下权限添加到您 `AndroidManifest.xml` 开始之前或之后 `application` 标签 :

```xml
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<!-- Required to keep the app running in the background without any ressource limitations -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Required to request the manage overlay permission -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
```

**请注意**替换 `FOREGROUND_SERVICE_LOCATION` 使用您想要使用的前景服务类型(参见 [前景服务类型](https://developer.android.com/develop/background-work/services/fg-service-types)) (中文(简体) ). 见 [服务类型](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-servicetype) 用于现有类型.

您还需要添加以下接收器和服务 **内部** 页:1 `application` 在您的标签 `AndroidManifest.xml`数字 :

```xml
<receiver android:name="io.capawesome.capacitorjs.plugins.foregroundservice.NotificationActionBroadcastReceiver" />
<service android:name="io.capawesome.capacitorjs.plugins.foregroundservice.AndroidForegroundService" android:foregroundServiceType="location" />
```

**请注意**替换 `location` 使用您想要使用的前景服务类型(参见 [前景服务类型](https://developer.android.com/develop/background-work/services/fg-service-types)) (中文(简体) ). 见 [服务类型](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-servicetype) 用于现有类型.

## 配置

此插件不需要配置 .

## 演示

这里有一个实例: [robingenz/电容器-插管-demo](https://github.com/robingenz/capacitor-plugin-demo)

| 机器人 |
| --- |
| ![Android Demo](https://user-images.githubusercontent.com/13857929/188438969-fcbf02d3-0db2-4277-8039-ddfb6bce42ae.gif) |

## 使用量

```typescript
import { Capacitor } from '@capacitor/core';
import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';

const startForegroundService = async () => {
  await ForegroundService.startForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
    buttons: [
      {
        title: 'Button 1',
        id: 1,
      },
      {
        title: 'Button 2',
        id: 2,
      },
    ],
    silent: false,
    notificationChannelId: 'default',
  });
};

const updateForegroundService = async () => {
  await ForegroundService.updateForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
  });
};

const stopForegroundService = async () => {
  await ForegroundService.stopForegroundService();
};

const createNotificationChannel = async () => {
  await ForegroundService.createNotificationChannel({
    id: 'default',
    name: 'Default',
    description: 'Default channel',
    importance: Importance.Default,
  });
};

const deleteNotificationChannel = async () => {
  await ForegroundService.deleteNotificationChannel({
    id: 'default',
  });
};
```

## API 密码

-   [`moveToForeground()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-movetoforeground)
-   [`startForegroundService(...)`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-startforegroundservice)
-   [`updateForegroundService(...)`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-updateforegroundservice)
-   [`stopForegroundService()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-stopforegroundservice)
-   [`checkPermissions()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-requestpermissions)
-   [`checkManageOverlayPermission()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-checkmanageoverlaypermission)
-   [`requestManageOverlayPermission()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-requestmanageoverlaypermission)
-   [`createNotificationChannel(...)`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-createnotificationchannel)
-   [`deleteNotificationChannel(...)`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-deletenotificationchannel)
-   [`addListener('buttonClicked', ...)`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-addlistenerbuttonclicked-)
-   [`addListener('notificationTapped', ...)`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-addlistenernotificationtapped-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-enums)

### 移动到前景 ()

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

将应用程序移动到前景.

在Android SDK 23+上,用户必须给予管理覆盖权限. 你可以用这个 `requestManageOverlayPermission()` 请求方法 权限和 `checkManageOverlayPermission()` 用于检查是否 获得许可.

只能从Android上找到.

**自:** 0.3.0 (中文(简体) )

* * *

### 启动前景服务(...)

```typescript
startForegroundService(options: StartForegroundServiceOptions) => Promise<void>
```

启动前景服务.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartForegroundServiceOptions](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-startforegroundserviceoptions)` |

**自:** 0.0.1 资源

* * *

### 更新前景服务(...)

```typescript
updateForegroundService(options: UpdateForegroundServiceOptions) => Promise<void>
```

更新运行前景服务的通知细节.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartForegroundServiceOptions](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-startforegroundserviceoptions)` |

**自:** 6.1.0 (中文(简体) )

* * *

### 站点前端服务( C)

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

停止前卫服务.

只能从Android上找到.

**自:** 0.0.1 资源

* * *

### 检查( )

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

检查显示通知的权限 .

打开 **机器人**,这种方法只需要调用Android 13+.

只能从Android上找到.

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

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

* * *

### 请求( )

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

请求显示通知的权限 .

打开 **机器人**,这种方法只需要调用Android 13+.

只能从Android上找到.

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

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

* * *

### 检查管理重叠

```typescript
checkManageOverlayPermission() => Promise<ManageOverlayPermissionResult>
```

请检查date=中的日期值 (帮助) .

只能从Android上找到.

**回返情况:** `Promise<[ManageOverlayPermissionResult](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-manageoverlaypermissionresult)>`

**自:** 0.3.0 (中文(简体) )

* * *

### 管理重叠

```typescript
requestManageOverlayPermission() => Promise<ManageOverlayPermissionResult>
```

请求管理覆盖权限 .

只能从Android上找到.

**回返情况:** `Promise<[ManageOverlayPermissionResult](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-manageoverlaypermissionresult)>`

**自:** 0.3.0 (中文(简体) )

* * *

### 创建通知频道(...)

```typescript
createNotificationChannel(options: CreateNotificationChannelOptions) => Promise<void>
```

创建通知通道 . 如果不引用,插件会创建一个频道,其名称和描述设置为"Default".

仅供Android(SDK 26+)使用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CreateNotificationChannelOptions](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-createnotificationchanneloptions)` |

**自:** 6.1.0 (中文(简体) )

* * *

### 删除通知频道(...)

```typescript
deleteNotificationChannel(options: DeleteNotificationChannelOptions) => Promise<void>
```

删除通知频道.

仅供Android(SDK 26+)使用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DeleteNotificationChannelOptions](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-deletenotificationchanneloptions)` |

**自:** 6.1.0 (中文(简体) )

* * *

### 添加 Listener ('按钮点击',...)

```typescript
addListener(eventName: 'buttonClicked', listenerFunc: ButtonClickedEventListener) => Promise<PluginListenerHandle>
```

点击通知按钮时调用 .

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'buttonClicked'` |
| **`listenerFunc`** | `[ButtonClickedEventListener](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-buttonclickedeventlistener)` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-pluginlistenerhandle)>`

**自:** 0.2.0 (中文(简体) )

* * *

### 添加倾听器( 已通知, ...)

```typescript
addListener(eventName: 'notificationTapped', listenerFunc: NotificationTappedEventListener) => Promise<PluginListenerHandle>
```

监听前台服务通知时调用.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'notificationTapped'` |
| **`listenerFunc`** | `[NotificationTappedEventListener](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-notificationtappedeventlistener)` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-pluginlistenerhandle)>`

**自:** 8.1.0 联合国

* * *

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

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

删除此插件的所有听众 .

**自:** 0.2.0 (中文(简体) )

* * *

### 接口

#### 启动前景服务选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`body`** | `string` | 通知书正文如下:. |  | 0.0.1 资源 |
| **`buttons`** | `NotificationButton[]` | 通知上要显示的按钮 。 仅在Android上可用(SDK 24+). |  | 0.2.0 (中文(简体) ) |
| **`id`** | `number` | 通知识别符. |  | 0.0.1 资源 |
| **`serviceType`** | `[ServiceType](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-servicetype)` | 前景服务类型. 仅在Android(SDK 29+)上可用. |  | 6.2.0 (单位:千美元) |
| **`smallIcon`** | `string` | 通知的状态栏图标 。 图标应该放置在您的应用程序中 `res/drawable` 文件夹。 此选项的值应该是可绘制的资源ID, 即没有扩展名的文件名 . |  | 0.0.1 资源 |
| **`title`** | `string` | 通知的标题. |  | 0.0.1 资源 |
| **`silent`** | `boolean` | 如果是真的,则只在第一次通知时发出警报(声音/振动)。 之后的更新将会被沉默. | `false` | 6.1.0 (中文(简体) ) |
| **`notificationChannelId`** | `string` | 通知频道标识符. |  | 6.1.0 (中文(简体) ) |

#### 通知按钮

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`title`** | `string` | 按钮标题. | 0.2.0 (中文(简体) ) |
| **`id`** | `number` | 按钮标识符 。 用于在 `buttonClicked` 事件已释放. | 0.2.0 (中文(简体) ) |

#### 权限状态

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`display`** | `[PermissionState](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-permissionstate)` | 显示通知的权限状态 . | 5.0.0 (单位:千美元) |

#### 管理重叠任务结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`granted`** | `boolean` | 是否获得许可 。 总是这样 `true` android SDK < 23 (英语). | 0.3.0 (中文(简体) ) |

#### 创建通知

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`description`** | `string` | 本频道的描述(向用户介绍). | 6.1.0 (中文(简体) ) |
| **`id`** | `string` | 频道标识符. | 6.1.0 (中文(简体) ) |
| **`importance`** | `[Importance](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-importance)` | 发送到此频道的通知的中断级别 . | 6.1.0 (中文(简体) ) |
| **`name`** | `string` | 此频道的名称( 向用户介绍) . | 6.1.0 (中文(简体) ) |

#### 删除通知

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 频道标识符. | 6.1.0 (中文(简体) ) |

#### 插件听筒

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

#### 按钮点击事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`buttonId`** | `number` | 按钮标识符 . | 0.2.0 (中文(简体) ) |

#### 通知 纹身事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`notificationId`** | `number` | 通知识别符. | 8.1.0 联合国 |

### 类型异名

#### 更新前景服务选项

`[StartForegroundServiceOptions](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-startforegroundserviceoptions)`

#### 权限状态

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

#### 按钮点击事件收听器

`(event: [ButtonClickedEvent](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-buttonclickedevent)): void`

#### 通知窗口

`(event: [NotificationTappedEvent](https://npmcn.com/package/%40capawesome-team/capacitor-android-foreground-service/#readme-notificationtappedevent)): void`

### 数字

#### 服务类型

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Location`** | `8` | 长跑使用需要位置访问的病例,如导航和位置共享. | 6.2.0 (单位:千美元) |
| **`Microphone`** | `128` | 从背景继续麦克风抓取,如语音录音机或通信app. | 6.2.0 (单位:千美元) |

#### 重要性

| 成员 | 数值 | 自兹 |
| --- | --- | --- |
| **`Min`** | `1` | 6.1.0 (中文(简体) ) |
| **`Low`** | `2` | 6.1.0 (中文(简体) ) |
| **`Default`** | `3` | 6.1.0 (中文(简体) ) |
| **`High`** | `4` | 6.1.0 (中文(简体) ) |
| **`Max`** | `5` | 6.1.0 (中文(简体) ) |

## 财务问题

### 为什么用户可以驳回通知?

Android 14 改变了行为,允许用户驳回此类通知,参见 [用户如何经历不可解除通知的变化](https://developer.android.com/about/versions/14/behavior-changes-all#non-dismissable-notifications)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-foreground-service/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-foreground-service/LICENSE)。 。 。 .

## 常见问题

### @capawesome-team/capacitor-android-foreground-service 是什么？

电容插件在Android上运行一个前景服务\.

### 如何安装 @capawesome-team/capacitor-android-foreground-service？

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

### @capawesome-team/capacitor-android-foreground-service 支持 TypeScript 吗？

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

### @capawesome-team/capacitor-android-foreground-service 支持 ESM 还是 CommonJS？

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

### @capawesome-team/capacitor-android-foreground-service 可以商用吗？

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

### @capawesome-team/capacitor-android-foreground-service 的下载量有多少？

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

### @capawesome-team/capacitor-android-foreground-service 还在维护吗？

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