# @capawesome/capacitor-badge 中文文档

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

版本：8\.0\.4
npm 元数据更新时间：2026-10-08T04:33:50.759Z
中文译文更新时间：2026-11-09T01:49:43.447Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：69 kB，29 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2022-08-04T17:43:10.748Z
- 最新版本发布：2026-10-08T04:33:50.390Z
- 近 30 天下载量：892099（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 6 个）

## 中文简介

Capacitor插件访问并更新Android,iOS,和Web上应用图标的徽标编号.

## 安装

```sh
npm install @capawesome/capacitor-badge
```

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

## README

# 电容徽标插件

控制器插件,用于访问并更新应用程序图标的徽标编号.

[![Thousands of teams ship faster with Capawesome Cloud Native Builds and Live Updates](https://capawesome.io/assets/banners/cloud-teams-ship-faster-with-capacitor.png)](https://capawesome.io/)

## 特征

Capacitor徽标插件是Capacitor App最完整的应用图标徽标解决方案之一. 以下是一些关键特征:

-   🖥️ **跨平台**:支持Android,iOS,和Web(PWA).
-   🔢 **徽章管理**:得到,设置,增加,减少,并清楚警徽计数.
-   💾 **持久徽章**: 重启或应用程序重新启动后, 徽章计数持续存在 .
-   🔄 **自动清除选项**:恢复应用时自动重置计数器.
-   🔐 **权限处理**: 检查并请求徽章显示权限.
-   ⚙️ **可配置**:自定义持久性和自动清晰的行为.
-   🤝 **兼容性**: 与 [应用图标](https://capawesome.io/docs/sdks/capacitor/app-icon/) 财务报告和审定财务报表 [火地云通讯](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/) 插件 .
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

徽章插件通常用于显示反映待决项目的应用程序图标上的计数,例如:

-   **未读信件**: 在应用程序图标上显示未读的聊天消息或电子邮件的数量.
-   **待发通知**: 保持徽章与用户尚未见到的通知同步.
-   **打开任务**: 在购物车中显示打开的待办事宜、提醒或项目的数量.
-   **自动重置**: 当用户使用程序恢复时自动清除计数器 `autoClear` 配置选项.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 7.x.x (中文(简体) ) | 7.x.x (中文(简体) ) | 折旧 |
| 6.x.x (中文(简体) ) | 6.x.x (中文(简体) ) | 折旧 |
| 5.x.x (中文(简体) ) | 5.x.x (中文(简体) ) | 折旧 |

## 演示

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

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

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

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

```bash
npm install @capawesome/capacitor-badge
npx cap sync
```

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$shortcutBadgerVersion` 版本 `me.leolin:ShortcutBadger` (默认 : `1.1.22`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

### iOS系统

#### 隐私表

添加数据 `NSPrivacyAccessedAPICategoryUserDefaults` 您的字典密钥 [隐私宣言](https://capacitorjs.com/docs/ios/privacy-manifest) (通常情况) `ios/App/PrivacyInfo.xcprivacy`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- Add this dict entry to the array if the file already exists. -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>
```

## 配置

这些配置值是可用的 :

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`persist`** | `boolean` | 配置插件在重启或应用程序后是否恢复计数器 。 仅在Android和iOS上提供. | `true` |
| **`autoClear`** | `boolean` | 配置插件是否在恢复应用程序后重新设置计数器 。 打开 **iOS系统**,这也将清除所有通知。 仅在Android和iOS上提供. | `false` |

### 实例

单位 `capacitor.config.json`数字 :

```json
{
  "plugins": {
    "Badge": {
      "persist": true,
      "autoClear": false
    }
  }
}
```

单位 `capacitor.config.ts`数字 :

```ts
/// <reference types="@capawesome/capacitor-badge" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Badge: {
      persist: true,
      autoClear: false,
    },
  },
};

export default config;
```

## 使用量

以下例子显示如何获得,设置,增加,减少,并清除徽章计数,检查徽章是否得到支持,以及检查和请求权限.

### 获取当前徽章数

读取当前徽章计数 。 重新启动或程序重新启动后, 计数不会丢失 :

```typescript
import { Badge } from '@capawesome/capacitor-badge';

const get = async () => {
  const result = await Badge.get();
  return result.count;
};
```

### 设置徽章数

设置徽章计数为特定值. 在iOS上,将计数设置为 `0` 将删除徽章并清除所有通知 :

```typescript
import { Badge } from '@capawesome/capacitor-badge';

const set = async (count: number) => {
  await Badge.set({ count });
};
```

### 增加或减少徽章计数

例如,当新信件到达或被读取时,徽章数会增加或减少一个:

```typescript
import { Badge } from '@capawesome/capacitor-badge';

const increase = async () => {
  await Badge.increase();
};

const decrease = async () => {
  await Badge.decrease();
};
```

### 清除徽章计数

从应用程序图标中删除徽章 。 在iOS上,这也将清除所有通知:

```typescript
import { Badge } from '@capawesome/capacitor-badge';

const clear = async () => {
  await Badge.clear();
};
```

### 检查是否支持徽章

检查当前设备是否支持徽标计数, 例如, 并不是每个 Android 发射器都支持徽标 :

```typescript
import { Badge } from '@capawesome/capacitor-badge';

const isSupported = async () => {
  const result = await Badge.isSupported();
  return result.isSupported;
};
```

### 检查和请求权限

检查并请求显示徽章的权限 :

```typescript
import { Badge } from '@capawesome/capacitor-badge';

const checkPermissions = async () => {
  const result = await Badge.checkPermissions();
};

const requestPermissions = async () => {
  const result = await Badge.requestPermissions();
};
```

## API 密码

-   [`get()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-get)
-   [`set(...)`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-set)
-   [`increase()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-increase)
-   [`decrease()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-decrease)
-   [`clear()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-clear)
-   [`isSupported()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-issupported)
-   [`checkPermissions()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-requestpermissions)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-type-aliases)

### 获取()

```typescript
get() => Promise<GetBadgeResult>
```

得到警徽计数. 重启或应用程序重新启动后,徽章计数不会丢失.

默认 : `0`。 。 。 .

**回返情况:** `Promise<[GetBadgeResult](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-getbadgeresult)>`

* * *

### 设置(...)

```typescript
set(options: SetBadgeOptions) => Promise<void>
```

设出徽记.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetBadgeOptions](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-setbadgeoptions)` |

* * *

### 增加()

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

增加警徽数.

* * *

### 减少()

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

减少警徽数.

* * *

### 清除( c)

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

清除警徽计数.

打开 **iOS系统**,这将移除徽章,并清除所有通知.

* * *

### 已支持 ()

```typescript
isSupported() => Promise<IsSupportedResult>
```

检查是否支持徽章计数 .

**回返情况:** `Promise<[IsSupportedResult](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-issupportedresult)>`

* * *

### 检查( )

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

检查显示徽章的权限 .

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

* * *

### 请求( )

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

请求允许显示徽章 .

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

* * *

### 接口

#### 获取 Badge 报表

| Prop | 类型 |
| --- | --- |
| **`count`** | `number` |

#### 设置基准选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`count`** | `number` | 警徽计数要设置. 打开 **iOS系统**,将计数设置为 `0` 并清除所有通知. |

#### 支持的结果

| Prop | 类型 |
| --- | --- |
| **`isSupported`** | `boolean` |

#### 权限状态

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`display`** | `[PermissionState](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-permissionstate)` | 显示徽章的授权状态 . |

### 类型异名

#### 权限状态

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

## 基尔克

打开 **机器人** 没有官方API来设置徽章,因此并非所有发射器都支持徽章. 此插件使用 [快捷键](https://github.com/leolin310148/ShortcutBadger)这取决于针对供应商的机制。 所有辅助发射器都列入清单 [那边](https://github.com/leolin310148/ShortcutBadger#supported-launchers)。在库存Android发射器,如像素发射器上,没有显示徽章.

打开 **网页**,应用程序必须作为安装的PWA(在任务栏或码头)运行.

## 财务问题

### 为什么我的Android设备没有显示警徽?

Android没有提供官方API来为发射器图标设置徽章. 此插件因此使用 [快捷键](https://github.com/leolin310148/ShortcutBadger) 它依赖于一些制造商(如三星、小米、HTC和索尼)提供的供应商专用机制。 只有列入清单的发射器 [辅助发射器](https://github.com/leolin310148/ShortcutBadger#supported-launchers) 可以显示徽章。 在库存的Android发射器上,最出名的是像素发射器,没有显示徽章. 你可以用这个 `isSupported()` 用于检查当前设备是否支持徽章的方法.

### 插件能否显示一个 Android 通知徽章( 点) ?

没有。 自Android 8.0起,发射器显示 [通知徽章](https://developer.android.com/develop/ui/views/notifications/badges) 只在应用程序有 _活动_ 通知。 该徽章出自该通知并一经驳回即消失,因此不能单独设置. 在Android的股票上,它也是一个没有计数的点. 如果您的应用程序已经显示通知, 徽章会自动显示, 没有插件调用 .

### 重启或应用程序重启后, 徽章计数是否持续 ?

是的, 默认情况下, 徽章计数会在重启或应用程序后恢复 。 您可以通过设置 `persist` 配置选项到 `false`,参见 [配置](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-configuration) 节.

### 恢复应用时,我怎么自动清除徽章??

设定 `autoClear` 配置选项到 `true` 在恢复应用程序后重新设置计数器。 请注意,在iOS上,这也将清除所有通知。 见 [配置](https://npmcn.com/package/%40capawesome/capacitor-badge/#readme-configuration) 节为例.

### 为什么 `checkPermissions()` 总是返回 `granted` 在Android和Web上吗?

只有iOS需要权限才能显示徽章. 在Android和Web上不需要权限,所以权限状态总是 `granted`。 。 。 .

### 为什么清除徽章也会删除我在iOS上的通知?

在iOS上,打电话 `clear()` 或设置徽章计数到 `0` 删除徽章并清除所有通知。 这是平台行为,不能被插件所改变.

### 这个插件在网络上工作吗 ?

是的,但应用程序必须作为安装的PWA(在任务栏或码头)运行. 同时检查浏览器是否支持使用 `isSupported()` 方法.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [应用图标](https://capawesome.io/docs/sdks/capacitor/app-icon/):运行时更改应用程序图标.
-   [应用快捷键](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/): 管理应用快捷键和快速动作.
-   [火地云通讯](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/):通过Firebase Cloud Massaging接收按键通知.

## 通讯

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

## 更改日志

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

## 许可证

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

## 贷项

此插件基于 [电容徽章](https://github.com/capawesome-team/capacitor-badge) 插件 . 感谢所有为这个项目捐款的人!

## 常见问题

### @capawesome/capacitor-badge 是什么？

Capacitor插件访问并更新Android,iOS,和Web上应用图标的徽标编号\.

### 如何安装 @capawesome/capacitor-badge？

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

### @capawesome/capacitor-badge 支持 TypeScript 吗？

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

### @capawesome/capacitor-badge 支持 ESM 还是 CommonJS？

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

### @capawesome/capacitor-badge 可以商用吗？

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

### @capawesome/capacitor-badge 的下载量有多少？

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

### @capawesome/capacitor-badge 还在维护吗？

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