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

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

版本：7\.0\.0
npm 元数据更新时间：2026-10-23T21:47:40.625Z
中文译文更新时间：2026-11-09T04:21:44.968Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：42.9 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2021-02-01T21:41:19.638Z
- 最新版本发布：2025-12-24T20:56:23.244Z
- 近 30 天下载量：29045（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 1 个）

## 中文简介

用于修改iOS应用程序图标的 Capacitor 社区插件.

## 安装

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

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

## README

  
![](https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png)

### 应用图标

**`@capacitor-community/app-icon`**

用于管理应用程序图标的 Capacitor 社区插件. 主要特征是您可以在程序上更改应用程序图标.

![](https://img.shields.io/maintenance/yes/2025?style=flat-square) [![](https://img.shields.io/npm/l/@capacitor-community/app-icon?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/app-icon)  
[![](https://img.shields.io/npm/dw/@capacitor-community/app-icon?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/app-icon) [![](https://img.shields.io/npm/v/@capacitor-community/app-icon?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/app-icon) [![](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/app-icon)

![](https://github.com/capacitor-community/app-icon/blob/main/media/appicon_demo.gif) ![](https://github.com/capacitor-community/app-icon/blob/main/media/appicon_demo_android.gif)

## 维护者

| 维护者 | GitHub 图像 | 社会 |
| --- | --- | --- |
| 约翰·博尔赫斯 | [约翰伯格斯](https://github.com/johnborges) | [@johnborges (英语)](https://twitter.com/johnborges) |

## 开始前

> 此插件只更改设备主屏幕上的主应用程序图标 。 跳板等区域的图标不会改变并会继续显示原作. (iOS) (中文(简体) )

> 只有在应用程序处于前台(iOS)时才允许更改应用程序图标.

## 安装

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

## 配置

在使用此插件之前, 需要将替代图标包含在应用程序捆绑和项目中 。 要切换到苍蝇上的任何图标,必须先将其添加到工程中. 以下是每个平台的配置步骤.

## Android 配置

### 添加替代图标

将替代图标直接添加到您的 Android 项目 `app/src/main/res`。 。 。 .

### 设置应用程序Manifest.xml

每个备选图标均由 [`<activity-alias>`](https://developer.android.com/guide/topics/manifest/activity-alias-element)中添加所有替代图标 `ApplicationManifest.xml` 作为儿童因素 `<application>`编辑 `name` 属性 `<activity-alias>` 必须是有点的前缀 `.` 见 [应用程序Manifest.xml](https://github.com/capacitor-community/app-icon/blob/android-support/example/android/app/src/main/AndroidManifest.xml) 举个例子.

```xml
<application>
    <!-- ... -->
    <activity
        android:name=".MainActivity"
        android:exported="true"
        android:launchMode="singleTask"
        android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
        android:label="@string/title_activity_main"
        android:theme="@style/AppTheme.NoActionBarLaunch">

        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <!-- <category android:name="android.intent.category.LAUNCHER" /> -->
        </intent-filter>

    </activity>
    <activity-alias
        android:label="Stencil"
        android:icon="@drawable/stencil"
        android:roundIcon="@drawable/stencil"
        android:name=".stencil"
        android:enabled="true"
        android:exported="true"
        android:targetActivity=".MainActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity-alias>
  
  <!-- additional <activity-alias> -->

<application>
```

## iOS 配置

> 从 [https://www.youtube.com/watch?v=AT89of YpWTU (中文(简体) )](https://www.youtube.com/watch?v=AT89ofYpWTU)

### 在资产目录中创建替代图标

在"XCode"中去"资产"并创建App图标.  
然后填入图像 1024x1024px

![XCode Assets Alternate Icons](https://npmcn.com/package/%40capacitor-community/app-icon/media/xcode_assets.png)

> 资产名称应当与代码中使用的名称相匹配

### 更改构建设置

1.  访问构建设置
2.  搜索 App 图标,
3.  选择“ 是” 用于 `Include All App Icon Assets`
4.  包含列表( 在 `Alternate App Icon Sets`),在"资产目录"中有应用程序图标的精确名称.

![Build Settings XCode](https://npmcn.com/package/%40capacitor-community/app-icon/media/xcode_build_settings.png)

## 使用量

```javascript
import { AppIcon } from '@capacitor-community/app-icon';

const changeIcon = async (iconName) => {
  await AppIcon.change({name: iconName, suppressNotification: true});
}

const getName = async () => {
  const { value } = await AppIcon.getName();
  console.log(value);
}

const resetIcon = async () => {
  const disable: string[] = ['stencil']; // all added aliaces names 
  await AppIcon.reset({ suppressNotification: true, disable });
}
```

## API 密码

-   [`isSupported()`](https://npmcn.com/package/%40capacitor-community/app-icon/#readme-issupported)
-   [`getName()`](https://npmcn.com/package/%40capacitor-community/app-icon/#readme-getname)
-   [`change(...)`](https://npmcn.com/package/%40capacitor-community/app-icon/#readme-change)
-   [`reset(...)`](https://npmcn.com/package/%40capacitor-community/app-icon/#readme-reset)
-   [接口](https://npmcn.com/package/%40capacitor-community/app-icon/#readme-interfaces)

### 已支持 ()

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

检查是否支持更改应用程序图标 。 (仅iOS)

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

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

* * *

### 获取Name ()

```typescript
getName() => Promise<{ value: string | null; }>
```

获得当前设置的替代图标的名称。 如果设置了原始图标, 返回为无效 .

**回返情况:** `Promise<{ value: string | null; }>`

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

* * *

### 更改(...)

```typescript
change(options: IconOptions) => Promise<void>
```

更改应用程序图标为指定的替代 .

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

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

* * *

### 重设(...)

```typescript
reset(options: ResetOptions) => Promise<void>
```

还原应用程序图标为正本 .

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

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

* * *

### 接口

#### 图标选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`name`** | `string` | 要设置的替代图标名称 |  |
| **`disable`** | `string[]` | 要禁用图标的名称 。 这不用于iOS,而用于Android. | 3.1.0 (中文(简体) ) |
| **`suppressNotification`** | `boolean` | 更改图标后显示的应用通知中控制标签 。 (iOS) (中文(简体) ) |  |

#### 重置选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`suppressNotification`** | `boolean` | 更改图标后显示的应用通知( iOS) . |  |
| **`disable`** | `string[]` | 要禁用图标的名称 。 这不用于iOS,而用于Android. | 3.1.1 国家 |

## 贡献者

感谢这些伟大的人[emoji 密钥](https://allcontributors.org/docs/en/emoji-key):

<table><tbody><tr><td align="center"><a href="http://johnborg.es/" rel="nofollow noopener noreferrer"><img alt="John Borges" src="https://avatars.githubusercontent.com/u/1888122?v=4?s=100" width="100px;" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><sub><b>约翰·博尔赫斯</b></sub></a><br><a href="https://github.com/capacitor-community/app-icon/commits?author=johnborges" title="Code" rel="nofollow noopener noreferrer">💻</a></td><td align="center"><a href="http://www.devdactic.com/" rel="nofollow noopener noreferrer"><img alt="Simon Grimm" src="https://avatars.githubusercontent.com/u/2514208?v=4?s=100" width="100px;" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><sub><b>西蒙・格林</b></sub></a><br><a href="https://github.com/capacitor-community/app-icon/commits?author=saimon24" title="Code" rel="nofollow noopener noreferrer">💻</a></td><td align="center"><a href="https://github.com/chvonrohr" rel="nofollow noopener noreferrer"><img alt="Christian von Rohr" src="https://avatars.githubusercontent.com/u/1733057?v=4?s=100" width="100px;" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><sub><b>克里斯蒂安·冯·罗尔</b></sub></a><br><a href="https://github.com/capacitor-community/app-icon/commits?author=chvonrohr" title="Code" rel="nofollow noopener noreferrer">💻</a></td><td align="center"><a href="https://qliq.dev/" rel="nofollow noopener noreferrer"><img alt="QliQ.dev" src="https://avatars.githubusercontent.com/u/5783161?v=4?s=100" width="100px;" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><sub><b>页:1</b></sub></a><br><a href="https://github.com/capacitor-community/app-icon/commits?author=qliqdev" title="Code" rel="nofollow noopener noreferrer">💻</a></td><td align="center"><a href="https://hadouin.com/" rel="nofollow noopener noreferrer"><img alt="Hadouin" src="https://avatars.githubusercontent.com/u/79368202?v=4?s=100" width="100px;" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><sub><b>哈多因,哈多因,哈多因,哈多因</b></sub></a><br><a href="https://github.com/capacitor-community/app-icon/commits?author=hadouin" title="Documentation" rel="nofollow noopener noreferrer">📖</a></td><td align="center"><a href="https://harding.dev/" rel="nofollow noopener noreferrer"><img alt="Alexander Harding" src="https://avatars.githubusercontent.com/u/2166114?v=4?s=100" width="100px;" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br><sub><b>亚历山大·哈丁</b></sub></a><br><a href="https://github.com/capacitor-community/app-icon/commits?author=aeharding" title="Code" rel="nofollow noopener noreferrer">💻</a></td></tr></tbody></table>

本项目遵循 [全部贡献者](https://github.com/all-contributors/all-contributors) 规格。 任何捐款都欢迎!

## 常见问题

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

用于修改iOS应用程序图标的 Capacitor 社区插件\.

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

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

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

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

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

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

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

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

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

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

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

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