# @capawesome/capacitor-assets 中文文档

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

版本：5\.0\.1
npm 元数据更新时间：2026-10-22T14:44:43.397Z
中文译文更新时间：2026-11-09T09:19:56.614Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：156 kB，44 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：10 个
- 首次发布：2026-10-16T06:01:06.247Z
- 最新版本发布：2026-10-22T14:44:42.823Z
- 近 30 天下载量：3113（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

为 Capacitor app 创建图标并放出屏幕图像

## 安装

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

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

## README

# @capawesome/电容资产

[![npm version](https://img.shields.io/npm/v/@capawesome/capacitor-assets)](https://www.npmjs.com/package/@capawesome/capacitor-assets) [![npm downloads](https://img.shields.io/npm/dm/@capawesome/capacitor-assets)](https://www.npmjs.com/package/@capawesome/capacitor-assets) [![license](https://img.shields.io/npm/l/@capawesome/capacitor-assets)](https://github.com/capawesome-team/capacitor-assets/blob/main/LICENSE)

生成一个的图标并放出屏幕 [电容](https://capacitorjs.com/) iOS,Android和进步的Web Apps的应用,来自单一的标志或自有的源图像.

这是维护的叉子 [@ capacor/ 资产](https://github.com/ionic-team/capacitor-assets) 以 [帅呆了](https://capawesome.io/)。这是一个即时替换:只有软件包名称改变了。 见 [从 @ concessor/ 资产中迁移](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-migrating-from-capacitorassets)。 。 。 .

## 开始

1.  安装软件包 :
    
    ```shell
    npm install --save-dev @capawesome/capacitor-assets
    ```
    
2.  来个 `logo.png` 至少为 1024x1024px, 最好是具有透明背景, 变成 `assets/` 在项目根中的文件夹.
    
3.  为您的项目中的每个平台生成资产 :
    
    ```shell
    npx @capawesome/capacitor-assets generate
    ```
    

图标和溅出屏幕直接写入你的iOS,Android和网络项目. 当标志更改时, 重新运行命令 .

要设置你的品牌颜色,看 [简单模式](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-easy-mode)。要使用自己的图标和溅出屏幕而不是标志,请参见 [自定义模式](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-custom-mode)。 。 。 .

## 源文件

该工具读取其源文件 `assets/` 在工程根中的文件夹,或来自 `resources/` 如果存在的话。 使用 `--assetPath` 以指向另一个文件夹。 有二法能取补.

### 简单模式

Easy Mode从一个标志生成一切. 这是推荐的方法:减少你的工作,结果在每个平台上都是一样的。 它为了方便而交易定制性.

```
assets/
├── logo.png
├── logo-dark.png
├── icon-monochrome.png
└── icon-maskable.png
```

| 文件 | 最小尺寸 | 页:1 |
| --- | --- | --- |
| `logo.(png|svg)` | 1024x1024px (英语) | 标志. `icon.(png|svg)` 用作替代名称. |
| `logo-dark.png` | 1024x1024px (英语) | 可选的 暗模式喷出屏幕的标志 . |
| `icon-monochrome.png` | 1024x1024px (英语) | 可选的 在Android 13+上为主题应用图标设置的单色层,参见 [自定义模式](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-custom-mode)。 。 。 . |
| `icon-maskable.png` | 512×512px (中文(简体) ) | 可选的 隐形PWA图标,看 [自定义模式](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-custom-mode)。 。 。 . |

该标志被放入图标的背景颜色上,并放入另一个喷出屏幕上. 通过您的品牌颜色作为选项 :

```shell
npx @capawesome/capacitor-assets generate --iconBackgroundColor '#eeeeee' --splashBackgroundColor '#eeeeee' --splashBackgroundColorDark '#111111'
```

在溅射屏幕上,默认标志为宽度的五分之一. 换一个 `--logoSplashScale` 或者说 `--logoSplashTargetWidth`,参见 [选项](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-options)。 。 。 .

### 自定义模式

自定义 模式赋予你全能控制:您提供图标层,而溅出屏幕本身.

```
assets/
├── icon-only.png
├── icon-foreground.png
├── icon-background.png
├── icon-monochrome.png
├── icon-maskable.png
├── splash.png
└── splash-dark.png
```

| 文件 | 最小尺寸 | 页:1 |
| --- | --- | --- |
| `icon-only.(png|jpg)` | 1024x1024px (英语) | IOS和PWA上的应用图标,和Android上遗留的启动器图标. |
| `icon-foreground.(png|jpg)` | 1024x1024px (英语) | Android适应图标的前地层. |
| `icon-background.(png|jpg)` | 1024x1024px (英语) | Android适应图标的背景层. |
| `icon-monochrome.(png|jpg)` | 1024x1024px (英语) | 可选的 单色层用于 [主题应用程序图标](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive) 在Android 13+上:一个透明背景上的单色外形,系统有线. 保持与前方相同的安全区. 需要前地和后地层(或标志),因为发射器XML引用了全部三个. |
| `icon-maskable.(png|jpg)` | 512×512px (中文(简体) ) | 可选的 PWA 图标 `maskable` 列出条目,按原样使用。 把它和中央80%圆圈内的艺术品一起充血,看 [可遮蔽图标](https://web.dev/articles/maskable-icon)。没有它,应用程序图标被设置在 `--iconBackgroundColor`。 。 。 . |
| `splash.(png|jpg)` | 2732x2732px (英语) | 喷出屏幕。 把艺术品放在中间, 边缘被裁剪在大多数屏幕上. |
| `splash-dark.(png|jpg)` | 2732x2732px (英语) | 可选的 暗模式的喷出屏幕 . |

自定义文件胜过标志 。 如果文件夹持有两者,则自定义文件会覆盖同一输出生成的标志. `logo.png` 加号 `splash.png`例如,从徽标中给出图标,从 `splash.png`。 。 。 .

### 平台专用文件

文件在 `assets/ios/` 财务报告和审定财务报表 `assets/android/` 仅适用于一个平台,并优先于文件 `assets/` 产生相同的输出。 名称匹配, 但有一个例外: 应用程序图标是 `icon-only.png` 内 `assets/`不过 `ios/icon.png` 财务报告和审定财务报表 `android/icon.png` 在平台文件夹中( 一个根) `icon.png` 是一个 Easy Mode 标志.

| 文件 | 最小尺寸 | 页:1 |
| --- | --- | --- |
| `ios/icon.(png|jpg)` | 1024x1024px (英语) | IOS应用图标. |
| `ios/icon-dark.(png|jpg)` | 1024x1024px (英语) | IOS 18+上的黑暗应用图标. 使用透明的背景 . |
| `ios/icon-tinted.(png|jpg)` | 1024x1024px (英语) | IOS 18+上的有锡应用图标. 使用灰度图像,参见 [苹果公司的准则](https://developer.apple.com/design/human-interface-guidelines/app-icons)。 。 。 . |
| `ios/splash[-dark].(png|jpg)` | 2732x2732px (英语) | IOS喷出屏幕. |
| `android/icon.(png|jpg)` | 1024x1024px (英语) | Android后遗症发射器图标. |
| `android/icon-(foreground|background|monochrome).(png|jpg)` | 1024x1024px (英语) | 安卓的适应性图标层. |
| `android/splash[-dark].(png|jpg)` | 2732x2732px (英语) | 安卓喷出屏幕. |
| `android/notification-icon.(png|svg)` | 96x96px (中文(简体) ) | Android通知图标,透明背景为白色. 见 [通知图标](https://npmcn.com/package/%40capawesome/capacitor-assets/#readme-notification-icon)。 。 。 . |

## 产生的资产

没有平台选项, `generate` 运行项目中找到的每个平台。 过 `--ios`, (中文(简体) ), `--android` 或者说 `--pwa` 选择平台 :

```shell
npx @capawesome/capacitor-assets generate --ios --android
```

### iOS系统

写入 `ios/App/App/Assets.xcassets/` (修改项目路径为: `--iosProject`:

-   `AppIcon.appiconset/`: 1024×1024px 应用程序图标, 外加暗色和有色变体 `ios/icon-dark` 财务报告和审定财务报表 `ios/icon-tinted` 已存在。 图标放在 `--iconBackgroundColor`,因为iOS需要一个不透明的图标.
-   `Splash.imageset/`: 2732×2732px通用溅射屏幕以1x,2x和3x为正色和暗色. 这个 `Contents.json` 文件被更新,模板图像被删除.

### 机器人

写入 `android/app/src/main/res/` (修改项目路径为: `--androidProject` 和风味 `--androidFlavor`:

-   `mipmap-<density>/ic_launcher_foreground.png`, (中文(简体) ), `ic_launcher_background.png` 财务报告和审定财务报表 `ic_launcher_monochrome.png`,与 `mipmap-anydpi-v26/ic_launcher.xml` 财务报告和审定财务报表 `ic_launcher_round.xml`:适应图标. 单色层只有在单色源文件存在时才会被引用. 血层满出血 源头在 `--androidAdaptiveIconScale` 层(`1` 用于绘制到Android108dp模板的源.
-   `mipmap-<density>/ic_launcher.png` 财务报告和审定财务报表 `ic_launcher_round.png`:为Android 7.1及更年长的后遗症发射器图标. 在 Easy 模式下, 标识被放置在 `--iconBackgroundColor`。 。 。 .
-   `drawable-<orientation>[-night]-<density>/splash.png`: 显示于 [Splash 屏幕插件](https://capacitorjs.com/docs/apis/splash-screen)。 。 。 .
-   `AndroidManifest.xml`数字 : `android:icon` 财务报告和审定财务报表 `android:roundIcon` 点到生成的图标.

#### Android 12+ 发射屏幕

Android 12并后从活动主题中绘制出发射屏幕:一个以坚固颜色为中心而成的图标,而不是全屏图像. 在主题点到图标之前,系统显示发射器图标,以及 `splash.png` 仅在之后通过 Splash 屏幕插件出现 。 因此,该工具还:

-   写入 `drawable[-night]-<density>/ic_splash.png`:中间的36%的喷出物作为288dp平方. Android把它遮住到一个192dp的圆圈, 所以把艺术品放在中间的24%的溅出。 以简单模式保存 `--logoSplashScale` 在或低于 `0.24`,或 `--logoSplashTargetWidth` 在或低于 `655`。 。 。 .
-   写出颜色 `splash_background` 改为 `values[-night]/colors.xml`:喷出物上左上像素的颜色. 文件内的其他颜色被保存.
-   套装 `windowSplashScreenBackground` 财务报告和审定财务报表 `windowSplashScreenAnimatedIcon` 编辑 `AppTheme.NoActionBarLaunch` 样式 `values/styles.xml`,并删除其 `android:background` 如果是的话 `@drawable/splash`:在Android 12下方,它用全屏喷出来覆盖图标. 样式必须延伸 `Theme.SplashScreen`,它从4号控制器开始做。 如果没有,工具会打印出警告并离开 `styles.xml` 一个人.

随着标志以平坦的背景为中心,发射屏幕再看起来就像iOS上的喷出屏幕.

#### 通知图标

若为 `assets/android/notification-icon.png` 存在, 工具写入 `drawable-<density>/ic_notification.png` 在24、36、48、72和96px时。 Android只使这个图标的α通道,所以在透明的背景上使用白色像素. 使用 `--androidNotificationIconName` 以更改资源名称.

然后点出您的通知插件 :

-   [`@capacitor/push-notifications`](https://capacitorjs.com/docs/apis/push-notifications) 财务报告和审定财务报表 [`@capacitor-firebase/messaging`](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-messaging/): 将此添加到 `<application>` 要素 `android/app/src/main/AndroidManifest.xml`数字 :
    
    ```xml
    <meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@drawable/ic_notification" />
    ```
    
-   [`@capacitor/local-notifications`](https://capacitorjs.com/docs/apis/local-notifications)设置 `smallIcon` 改为 `ic_notification` 在插件配置中.
    
-   [`@onesignal/capacitor-plugin`](https://documentation.onesignal.com/docs/notification-icons#how-to-add-android-default-icons): OneSignal 读取了固定资源名称, 因此生成该名称下的图标 :
    
    ```shell
    npx @capawesome/capacitor-assets generate --androidNotificationIconName ic_stat_onesignal_default
    ```
    
    要在Android 12上加上这个图标 `<application>` 元素(无 `#`:
    
    ```xml
    <meta-data android:name="com.onesignal.NotificationAccentColor.DEFAULT" android:value="FF00FF00" />
    ```
    

### 巴布亚新几内亚

网页目录是 `public`, (中文(简体) ), `src` 或者说 `www`,以先存在为准。 图像是写给它的 `assets/icons/` 如果网页目录有 `assets/` 文件夹,除此之外 `icons/` 文件夹。 该工具写道:

-   `icon-<size>.png` 与 `purpose: "any"` 财务报告和审定财务报表 `icon-maskable-<size>.png` 与 `purpose: "maskable"`,用于48,72,96,128,192,256和512等尺寸. 在 Easy 模式下, 标记被放置在 `--iconBackgroundColor`,所以图标是不透明的。 习惯 `icon-only.png` 用于: `any` 图标。 习惯 `icon-maskable.png` 用于: `maskable` 图标。 没有它,可遮掩的图标 将艺术品插入大约四分之三的图标上 `--iconBackgroundColor`,所以它能活过发射口罩;到达角落的艺术品仍然可以被圆口罩剪去.
-   `apple-splash-<width>-<height>@<density>.png`: iOS 飞溅屏幕(`apple-touch-startup-image`),用于基于: [苹果人界面准则](https://developer.apple.com/design/human-interface-guidelines/layout) 并更新该工具的新版本。 在 Easy 模式下, 标记被放置在 `--splashBackgroundColor`,或打开 `--splashBackgroundColorDark` 用于暗模式.
-   名单(`manifest.webmanifest`,或 `manifest.json` 如果有的话)用图标创建或更新,以及何时 `--splashBackgroundColor` 给出,使用 `background_color`启用 `--pwaManifestPath` 指向特定文件.

为什么四分之三的可以遮掩的图标?

Android 浏览器在如何 [可遮蔽图标](https://web.dev/articles/maskable-icon) 地图到适应性图标。 Firefox将它用于对接安全区,Chrome's WebAPK将它作为可适应层直接使用,因此同一图标在Chrome上比Firefox上大约1.3倍. 四分之三是两者的几何中间:徽标在克罗梅上会保持未被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗蒙上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克罗梅上被克上被克罗梅上被克罗梅上.

## 选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `--ios`, (中文(简体) ), `--android`, (中文(简体) ), `--pwa` | 找到每个平台 | 只为给定平台生成 . |
| `--assetPath <path>` | `assets`,则 `resources` | 带有源文件的文件夹 . |
| `--iosProject <dir>` | `ios/App` | IOS项目. |
| `--androidProject <dir>` | `android` | 安卓计划. |
| `--androidFlavor <name>` | `main` | Android产品口味 资产写到(`app/src/<flavor>/res`) (中文(简体) ). |
| `--androidNotificationIconName <name>` | `ic_notification` | Android 通知图标的资源名称 . |
| `--androidAdaptiveIconScale <scale>` | `0.6667` | Android可适应图标源尺度,为地层0至1. |
| `--pwaManifestPath <path>` | 发现于 `public`, (中文(简体) ), `src` 或者说 `www` | 网络应用程序列表文件 . |
| `--verbose` |  | 活字输出. |

标记和颜色 :

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `--iconBackgroundColor <color>` | `#ffffff` | 图标上标识后的背景颜色,以及平台需要不透明图标的自定义图标后的背景颜色. |
| `--iconBackgroundColorDark <color>` | `#111111` | 暗模式图标的背景颜色 。 目前还没有被任何平台使用. |
| `--splashBackgroundColor <color>` | `#ffffff` | 由标志生成的溅射屏幕的背景颜色. 也写给PWA `background_color`。 。 。 . |
| `--splashBackgroundColorDark <color>` | `#111111` | 由标志所生成的暗模式溅出屏幕的背景颜色. |
| `--logoSplashScale <scale>` | `0.2` | 作为喷出屏幕的2732×2732px喷出物的一小部分,标志的宽度由产生. |
| `--logoSplashTargetWidth <width>` |  | 喷出物上标志的宽度以像素表示. 胜过 `--logoSplashScale`。 。 。 . |

颜色是十六进制值。 引用它们,所以你的外壳不读 `#` 作为评论: `'#eeeeee'`。 。 。 .

参见命令行的完整列表 :

```shell
npx @capawesome/capacitor-assets generate --help
```

## 从 @ concessor/ 资产中迁移

```shell
npm uninstall @capacitor/assets
npm install --save-dev @capawesome/capacitor-assets
```

替换 `@capacitor/assets` 与 `@capawesome/capacitor-assets` 在您的脚本。 源文件和选项相同. 改变了什么:

-   PWA 图标为 `icon-<size>.png` 财务报告和审定财务报表 `icon-maskable-<size>.png`,单独 `any` 财务报告和审定财务报表 `maskable` 在清单中输入。 早期版本将PNG数据写入 `icon-<size>.webp` 带有综合目的的文件。 旧文件从清单中删除并删除 `icons/` 接下来的比赛 例如,更新参考文献 `apple-touch-icon` 链接中 `index.html`。 。 。 .
-   在"Easy Mode"中,标志是每个平台上溅出量的五分之一. 更早的版本在iOS上以自有的宽度来缩放,并自画出每个Android密度.
-   Android适应性图标层出血多,以一些发射器大小来固定下部和右边缘的一黑线. 重出所出圣像.
-   `--pwaNoAppleFetch` 没有效果。 Apple移除了用于取取的工具的屏幕大小表,因此大小来自内置列表.

见 [更改日志](https://github.com/capawesome-team/capacitor-assets/blob/main/CHANGELOG.md) 用于所有从叉子开始添加的东西.

## 捐款

见 [捐款额](https://github.com/capawesome-team/capacitor-assets/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

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

## 常见问题

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

为 Capacitor app 创建图标并放出屏幕图像

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

在项目目录运行 npm install @capawesome/capacitor-assets，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 capacitor-assets，可以用 npx capacitor-assets 直接运行。

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

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @capawesome/capacitor-assets 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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