电容 App 图标插件

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

特征

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

缺少一个功能? 刚刚 打开一个问题 我们看看!

使用大小写

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

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

兼容性

安装

你可以用我们的 AI 辅助设置 以安装插件. 添加数据 超级技能 至您的 AI 工具,使用以下命令:

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.

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

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

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

机器人

在Android上,每个替代图标被宣布为 <activity-alias> 指向发射装置的活动。 插件允许请求的别名, 并禁用其它的名 .

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

<!-- 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上提供:

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

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

获取当前图标

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

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

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

设置替代图标

将应用程序图标更改为您的应用程序先前已声明的替代图标( 请参见 安装) (中文(简体) ). 仅在Android和iOS上提供:

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

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

重置到默认图标

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

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

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

API 密码

• getCurrentIcon()
• isAvailable()
• resetIcon()
• setIcon(...)
• 接口

获取当前Icon ()

getCurrentIcon() => Promise<GetCurrentIconResult>

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

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

仅在Android和iOS上提供.

回返情况: Promise<GetCurrentIconResult>

自: 0.1.0 (中文(简体) )

易读 ()

isAvailable() => Promise<IsAvailableResult>

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

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

仅在Android和iOS上提供.

回返情况: Promise<IsAvailableResult>

自: 0.1.0 (中文(简体) )

重置Icon( )

resetIcon() => Promise<void>

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

仅在Android和iOS上提供.

自: 0.1.0 (中文(简体) )

设置Icon(...)

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

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

图标必须事先由应用程序宣布 。 见设置指示 页:1 机器人 财务报告和审定财务报表 iOS系统 更多信息.

仅在Android和iOS上提供.

自: 0.1.0 (中文(简体) )

接口

获取当前结果

易伤性结果

SetIcon 选项

财务问题

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

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

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

不, 此插件不能动态添加图标 。 您想要切换的每个图标都必须在应用程序前被宣布为 <activity-alias> 输入 AndroidManifest.xml 在Android上,并作为iOS上的资产目录中设置的替代应用程序图标. 见 安装 详细设置指令.

我给什么图标名字 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等项目.

相关插件

• 应用快捷键:在主屏幕上管理应用快捷键并快速动作.
• App 更新:协助用户更新本地应用程序.
• 徽标: 访问并更新应用程序图标的徽标编号.

通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 《卡帕索克通讯》。 。 。 .

更改日志

见 变动情况。 。 。 .

许可证

见 自由主义。 。 。 .