# @capawesome/capacitor-app-icon 中文文档

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

版本：0\.1\.2
npm 元数据更新时间：2026-09-02T08:21:33.066Z
中文译文更新时间：2026-11-09T06:13:02.510Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：60.7 kB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T06:20:07.306Z
- 最新版本发布：2026-09-02T08:21:32.714Z
- 近 30 天下载量：4963（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

在Android和iOS运行时更改应用图标的Capacitor插件.

## 安装

```sh
npm install @capawesome/capacitor-app-icon
```

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

## README

# 电容 App 图标插件

在运行时更改应用程序图标的电容插件 .

[![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/)

## 特征

-   🎨 **备选图标**: 在您的应用程序声明的图标之间切换家屏图标 .
-   🔍 **当前图标**: 读取当前使用的图标名称.
-   🔄 **重设**: 随时恢复默认图标.
-   🤝 **兼容性**: 与 [应用快捷键](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/) 财务报告和审定财务报表 [徽标](https://capawesome.io/docs/sdks/capacitor/badge/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

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

## 使用大小写

App图标插件一般用于个人化或刷新应用程序在主屏幕上的外观,例如:

-   **季节运动**: 切换到主题图标用于圣诞节等活动,并在后恢复默认图标.
-   **个人化**:让付费用户从一组替代图标中选择自己最喜欢的图标.
-   **应用图标拾取器**: 构建一个设置屏幕,列出所有图标并突出显示当前使用的图标.
-   **品牌更新**:推出新标志作为替代图标,并运行时切换.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **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-app-icon` plugin in my project.
```

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

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

此插件无法动态添加图标 。 您想要切换的每个图标必须是 **应用程序事先宣布的**。以下各节描述如何在每个平台上宣布替代图标.

### 机器人

在Android上,每个替代图标被宣布为 [`<activity-alias>`](https://developer.android.com/guide/topics/manifest/activity-alias-element) 指向发射装置的活动。 插件允许请求的别名, 并禁用其它的名 .

打开你的 `AndroidManifest.xml` 并移除发射器 `<intent-filter>` 从你的 `.MainActivity`添加一个 `<activity-alias>` 用于默认图标,每个备选图标各一个。 完全是一个别名必须是 `android:enabled="true"` (默认图标);所有其他必须是 `android:enabled="false"`。 。 。 .

```xml
<!-- Remove the <intent-filter> from the MainActivity. -->
<activity
    android:name=".MainActivity"
    android:exported="true"
    ... />

<!-- The default icon (enabled). -->
<activity-alias
    android:name=".AppIconDefault"
    android:enabled="true"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>

<!-- An alternate icon (disabled). -->
<activity-alias
    android:name=".Christmas"
    android:enabled="false"
    android:exported="true"
    android:icon="@mipmap/ic_launcher_christmas"
    android:roundIcon="@mipmap/ic_launcher_christmas_round"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>

<!-- Another alternate icon (disabled). -->
<activity-alias
    android:name=".Halloween"
    android:enabled="false"
    android:exported="true"
    android:icon="@mipmap/ic_launcher_halloween"
    android:roundIcon="@mipmap/ic_launcher_halloween_round"
    android:targetActivity=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>
```

图标名称传递到 `setIcon(...)` 是别名 **没有主点** (例如:. `Christmas`) (中文(简体) ). 添加引用的图标资源(例如:. `@mipmap/ic_launcher_christmas`敬你们 `res/mipmap-*` 文件夹.

> \[注\] 改变后的行为取决于发射器. 一些发射器仅在应用程序的任务关闭后才应用了新图标,尽管插件另有要求,但也有少数机构杀死了应用程序. 被钉在一个现在已失效的化名上的快捷键可能会停止工作.

### iOS系统

在iOS上,备用图标被宣布为资产目录中的额外应用图标集. 每个备选图标增加一个图标集(例如:. `Christmas` 财务报告和审定财务报表 `Halloween`在你的小学旁边 `AppIcon` 内 `Assets.xcassets` 在您的应用目标构建的设置中注册名称( 空格分隔) :

```
ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES = "Christmas Halloween";
ASSETCATALOG_COMPILER_INCLUDE_ALL_APPICON_ASSETS = YES;
```

在 Xcode 中,这些设置被称为 **备用 App 图标集** 财务报告和审定财务报表 **包含全部 App 图标资产** 输入 _资产目录汇编器_ 区域.

图标名称传递到 `setIcon(...)` 是图标集的名称(如:. `Christmas`),案例敏感。 主要图标( E)`AppIcon`以 `resetIcon(...)`。 。 。 .

> \[尖叫声\] 执行 **没有** 给另一个图标设置名称 `AppIcon` (例如:. `AppIconChristmas`) (中文(简体) ). 在我们运行 iOS 26 的物理设备测试中, 其名称与主图标集共享的替代图标 `AppIcon` 前缀不会在主屏幕上渲染 : `setIcon(...)` 成功,但系统显示的是空白的占位符图标,而不是替代图标。 iOS模拟器没有受到影响,所以要确保在真设备上进行测试. 这是没有记录的 iOS 行为; 使用名称没有 `AppIcon` 前缀在所有iOS版本中都是安全的.

> \[注\] 系统每次图标被更改时都会显示一个用户可见的提示,当应用程序处于后台时图标不能被更改.

## 配置

此插件不需要配置 .

## 使用量

以下示例显示如何检查替代图标支持,读取当前图标,设置替代图标,并重置到默认图标上.

### 检查是否支持更改应用程序图标

使用 `isAvailable()` 以检查当前设备是否支持替代图标。 关于Android,这总是决定 `true`;在iOS上,它决定了 `supportsAlternateIcons`。仅在Android和iOS上提供:

```typescript
import { AppIcon } from '@capawesome/capacitor-app-icon';

const isAvailable = async () => {
  const { available } = await AppIcon.isAvailable();
  return available;
};
```

### 获取当前图标

读取当前使用的图标名称, 例如在图标拾取器中突出显示 。 回返 `null` 如果默认图标在使用中。 仅在Android和iOS上提供:

```typescript
import { AppIcon } from '@capawesome/capacitor-app-icon';

const getCurrentIcon = async () => {
  const { icon } = await AppIcon.getCurrentIcon();
  return icon;
};
```

### 设置替代图标

将应用程序图标更改为您的应用程序先前已声明的替代图标( 请参见 [安装](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-installation)) (中文(简体) ). 仅在Android和iOS上提供:

```typescript
import { AppIcon } from '@capawesome/capacitor-app-icon';

const setIcon = async () => {
  await AppIcon.setIcon({ icon: 'Christmas' });
};
```

### 重置到默认图标

随时恢复默认的应用图标 。 仅在Android和iOS上提供:

```typescript
import { AppIcon } from '@capawesome/capacitor-app-icon';

const resetIcon = async () => {
  await AppIcon.resetIcon();
};
```

## API 密码

-   [`getCurrentIcon()`](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-getcurrenticon)
-   [`isAvailable()`](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-isavailable)
-   [`resetIcon()`](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-reseticon)
-   [`setIcon(...)`](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-seticon)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-interfaces)

### 获取当前Icon ()

```typescript
getCurrentIcon() => Promise<GetCurrentIconResult>
```

获取当前使用的图标名称 .

回返 `null` 如果默认图标在使用中.

仅在Android和iOS上提供.

**回返情况:** `Promise<[GetCurrentIconResult](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-getcurrenticonresult)>`

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

* * *

### 易读 ()

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

检查当前设备是否支持更改应用程序图标 .

关于Android,这总是决定 `true`。 。 。 . 在iOS上,这决定了 `supportsAlternateIcons`。 。 。 .

仅在Android和iOS上提供.

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

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

* * *

### 重置Icon( )

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

恢复默认的应用程序图标 .

仅在Android和iOS上提供.

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

* * *

### 设置Icon(...)

```typescript
setIcon(options: SetIconOptions) => Promise<void>
```

将应用程序图标更改为带有指定名称的替代图标 .

图标必须事先由应用程序宣布 。 见设置指示 页:1 [机器人](https://capawesome.io/docs/sdks/capacitor/app-icon/#android) 财务报告和审定财务报表 [iOS系统](https://capawesome.io/docs/sdks/capacitor/app-icon/#ios) 更多信息.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetIconOptions](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-seticonoptions)` |

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

* * *

### 接口

#### 获取当前结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`icon`** | `string | null` | 当前使用的图标名称 。 回返 `null` 如果默认图标在使用中. | 0.1.0 (中文(简体) ) |

#### 易伤性结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`available`** | `boolean` | 是否在当前设备上支持更改应用程序图标 . | 0.1.0 (中文(简体) ) |

#### SetIcon 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`icon`** | `string` | 要使用的替代图标的名称 。 在Android上,这个名字是 `&lt;activity-alias&gt;` (没有主点). 在iOS上,这是资产目录中设定的替代应用程序图标的名称. | 0.1.0 (中文(简体) ) |

## 财务问题

### 此插件与其他类似插件有何不同?

它在Android和iOS上运行时都会通过一个完全打入的API来改变应用图标——切换到一个已宣布的替代图标,读取当前使用的图标,重设默认,并检查设备是否支持替代图标. 它真实地记录了平台的现实,从Android的发射装置依赖行为到系统警报iOS显示的每起变化,所以生产中没有出奇. 该插件被针对最新的Capacitor和OS版本积极维护.

### 我可以在运行时添加新的应用程序图标吗?

不, 此插件不能动态添加图标 。 您想要切换的每个图标都必须在应用程序前被宣布为 `<activity-alias>` 输入 `AndroidManifest.xml` 在Android上,并作为iOS上的资产目录中设置的替代应用程序图标. 见 [安装](https://npmcn.com/package/%40capawesome/capacitor-app-icon/#readme-installation) 详细设置指令.

### 我给什么图标名字 `setIcon`? 吗?

在Android上,它是这个名字 `<activity-alias>` 而不包含主点(例如:. `Christmas`) (中文(简体) ). 在iOS上,它是资产目录中设置的替代应用程序图标的名称.

### 为什么新图标没有立即被应用到Android上?

改变后的行为取决于发射器. 一些发射器只在应用程序的任务被关闭后才应用新图标,尽管插件另有要求,但也有少数机构甚至杀死了应用程序. 也注意到被钉在现在已失效的别名上的捷径可能会停止工作.

### IOS为何在图标改变时显示提示?

系统每次图标改变时都会显示一个用户可见的提示. 这是标准的iOS行为,不能被压制. 另请注意,当应用程序处于背景状态时,图标不能被更改.

### 我怎么知道设备是否支持替代图标?

打电话 `isAvailable()` 在提供取图标器之前。 在Android上,它总是决心 `true`在iOS上,它决定了 `supportsAlternateIcons`。 。 。 .

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

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

## 相关插件

-   [应用快捷键](https://capawesome.io/docs/sdks/capacitor/app-shortcuts/):在主屏幕上管理应用快捷键并快速动作.
-   [App 更新](https://capawesome.io/docs/sdks/capacitor/app-update/):协助用户更新本地应用程序.
-   [徽标](https://capawesome.io/docs/sdks/capacitor/badge/): 访问并更新应用程序图标的徽标编号.

## 通讯

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

## 更改日志

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

## 许可证

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

## 常见问题

### @capawesome/capacitor-app-icon 是什么？

在Android和iOS运行时更改应用图标的Capacitor插件\.

### 如何安装 @capawesome/capacitor-app-icon？

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

### @capawesome/capacitor-app-icon 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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