> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通知图标

> 了解推送通知图标在 Web Push、Android 和 iOS 平台上的工作方式，包括当前平台要求、尺寸和最佳实践。

推送通知图标是与通知一起显示的小图像。它们帮助用户快速识别您的品牌、理解上下文并将您的消息与其他消息区分开来。每个平台处理图标的方式不同,因此遵循特定于平台的标准对于确保通知正确显示至关重要。

如需了解附加到通知的大图像,请参阅[图像和富媒体](./rich-media)。

<Frame caption="Android Chrome Web 推送通知示例,包含小徽章图标、大图标和图像。">
  <img src="https://mintcdn.com/onesignal/kfwVh0swYuB4jUMn/images/push/push-with-icons.png?fit=max&auto=format&n=kfwVh0swYuB4jUMn&q=85&s=6f75da9802f07db975405542bcf2125e" alt="推送通知图标" width="658" height="570" data-path="images/push/push-with-icons.png" />
</Frame>

***

## 推送通知图标的最佳实践

* 尽可能使用**带透明度的 PNG 图像**。
* 保持图标**简单且在非常小的尺寸下可识别**。
* 避免使用可能变得难以辨认的文本或精细细节。
* 遵循**特定于平台的规则**,包括尺寸、颜色和透明度。
* 在跨平台和操作系统版本的真实设备上测试通知。

***

## Web 通知图标

Web 推送通知显示在发送时提供的图标或在您的网站设置中定义为默认的图标。如果未提供图标,则使用默认的铃铛图标。

* 支持的格式:PNG、JPG、GIF(非动画)
* 图标必须是正方形。推荐尺寸为 `256x256` 像素。

<Info>
  不同的浏览器(Chrome、Edge、Safari、Firefox)可能会根据设备和操作系统以不同方式裁剪或缩放图标。建议使用正方形 `256x256` 图标以确保在所有浏览器上的一致显示。
</Info>

在您的[仪表板设置 > 推送和应用内 > Web 设置](./web-push-setup)中设置默认图标。

您还可以使用仪表板或 REST API 为每个通知覆盖图标。有关详细信息,请参阅[使用非默认图标发送通知](#send-notifications-with-non-default-icons)。

### Android Web 推送徽章图标

在 Android 设备上,Web 推送通知可能会显示由 Web 应用清单 `badge` 属性定义的较小**徽章图标**。徽章图标用于有限的 UI 上下文(例如 Android 状态栏),并且可能不会在所有 Android 设备上显示。如果未提供徽章图标,则默认为浏览器图标。

虽然徽章图标不受与 Android 应用小通知图标相同的严格仅 alpha 规则的约束,但它们仍在系统控制的 UI 中呈现。

**最佳实践:**

* 使用带**透明背景**的**正方形 PNG**
* 保持设计**简单且高对比度**
* 避免文本或精细细节
* 使用单色或最少颜色以获得最佳一致性

建议最小尺寸为 `72×72 像素`。可以接受更大的图像,并将根据需要缩小。

示例小徽章图标:`https://i.imgur.com/9QFB20F.png`

<Frame caption="使用示例徽章图标在 Android 状态栏中显示徽章图标的示例。">
  <img src="https://mintcdn.com/onesignal/kfwVh0swYuB4jUMn/images/push/badge-icon-android-status-bar.png?fit=max&auto=format&n=kfwVh0swYuB4jUMn&q=85&s=5864715448d5c0a3053c03e42e49a49e" alt="使用示例徽章图标在 Android 状态栏中显示徽章图标的示例。" width="744" height="162" data-path="images/push/badge-icon-android-status-bar.png" />
</Frame>

<Note>
  与 Android 应用小通知图标不同,Web 推送徽章图标可能在某些设备上保留颜色。但是,全彩或复杂图标可能会根据 Android 版本、浏览器和设备制造商而呈现不一致。
</Note>

有关详细信息,请参阅[使用非默认图标发送通知](#send-notifications-with-non-default-icons)。

***

## iOS 通知图标

iOS 通知始终使用您的**应用图标**。

* 通知图标自动从您应用的图标资源派生
* 您无法为每条消息更改通知图标
* 更改图标需要更新您的应用图标并发布新的应用版本

<Note>
  iOS 上没有 APNs 有效负载字段允许您指定自定义通知图标。

  此行为由 iOS 强制执行,适用于标准推送通知、关键警报和实时活动。
</Note>

### 通信通知

在 iOS 15 及更高版本上,Apple 支持[通信通知](https://developer.apple.com/documentation/usernotifications/implementing-communication-notifications)。

正确实现后,通信风格的通知(例如消息或通话应用)可能会在受支持的系统视图中显示**联系人或发送者图像**而不是应用图标。

<Note>
  通信通知仅限于特定用例,并需要明确采用 Apple 的通信通知 API。它们不适用于通用通知。
</Note>

***

## Android 通知图标

Android(包括 Amazon 和华为设备)支持**小**和**大**通知图标。

Android 还支持[对话通知](https://developer.android.com/develop/ui/views/notifications/conversations),允许您将图标更改为用户的个人资料图像。

<Note>
  在 Android 8.0+(API 26+)上,通知外观受系统 UI、[通知渠道](./android-notification-categories)和设备制造商自定义的严重影响。
</Note>

<Frame>
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/cbb4e86-android-notification-icons.jpg?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=a366f3629206f59331f76502bcb485b5" alt="Android 通知图标位置" width="1888" height="1274" data-path="images/docs/cbb4e86-android-notification-icons.jpg" />
</Frame>

### 小通知图标

小通知图标显示在状态栏和通知的左上角。如果未提供自定义小图标,OneSignal 将显示默认的铃铛图标。

Android 使用**图标的 alpha 通道**而不是其颜色数据来呈现小通知图标。系统在显示图标时应用自己的色调(或您配置的强调色)。

**要求和最佳实践:**

* 在**透明背景**上使用**单色剪影图标**
* 设计图标时使**形状由透明度定义**,而不是颜色
* 避免渐变、阴影或多色艺术作品
* 保持设计简单且在非常小的尺寸下可识别

一种常见且推荐的方法是将图标设计为**透明背景上的白色艺术作品**,但从技术上讲,Android 使用的是 **alpha 掩码**,而不是白色本身。

<Warning>
  具有实心背景或全彩艺术作品的图标可能会呈现不正确——通常显示为白色方块、裁剪形状或意外的剪影——具体取决于设备制造商和 Android 版本。

  Android 通常会忽略小通知图标中的颜色信息,并从 alpha 通道和系统或应用定义的着色中派生最终外观。
</Warning>

#### 小图标强调色

您可以更改通知小图标周围显示的颜色。

<Frame>
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4fce1c6db18b7ff1019763684781993a3d921b538e93918e33fc3fb0d78a79b6-Screenshot_20240927_151014_One_UI_Home.jpg?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=84872fd066f015557904a412a17fdcd0" alt="Android notification showing small icon accent color" width="1080" height="1058" data-path="images/docs/4fce1c6db18b7ff1019763684781993a3d921b538e93918e33fc3fb0d78a79b6-Screenshot_20240927_151014_One_UI_Home.jpg" />
</Frame>

要设置默认颜色,请将以下行添加到项目中的 `res/values/strings.xml` 文件中。

如果您想为深色模式设置不同的颜色,也可以将键添加到 `res/values-night/strings.xml` 中。

使用 HEX 值。使用 [Android Asset Studio](https://romannurik.github.io/AndroidAssetStudio/icons-generic.html#source.type=clipart\&source.clipart=ac_unit\&source.space.trim=1\&source.space.pad=0\&size=32\&padding=8\&color=rgb\(139%2C%20195%2C%2074\)\&name=ic_ac_unit) 配色方案获取帮助。

```xml theme={null}
<resources>
    <string name="onesignal_notification_accent_color">FF00FF00</string>
</resources>
```

要基于每个通知设置颜色,请在我们的[创建通知](/reference/create-message) API 调用中设置 `android_accent_color`,或在"消息 > 新推送 > 平台设置 > Google Android 选项"下的"强调色"字段中输入值。

<Warning>
  如果您最近刚向应用添加了图标资源,您可能需要等待几天才能使用该图标发送通知。这是因为大多数用户可能需要数天甚至数周才能将其应用更新到包含新图标的最新版本。
</Warning>

#### 自定义非 alpha 通道小图标图像

某些设备制造商会按原样显示图像(忽略 alpha 通道规则)。如果您希望在所有设备上使用非 alpha 通道图像,可以根据 [Android 的文档设置自定义通知布局](https://developer.android.com/training/notify-user/custom-notification)。

我们强烈建议遵循 alpha 规则,因为图标在所有设备上可能看起来不一致。Google 这样设计是有原因的——图标太小,看不到任何有意义的细节,因此强制使用单一颜色有助于一眼就能识别图标。

### 大通知图标

大图标显示在 Android 通知的右侧。

* 推荐尺寸:**256×256 像素**
* 格式:PNG 或 JPG
* 如果未设置,Android 可能会重用小图标

***

## 如何添加 Android 默认图标

我们强烈建议为每个基于 Android 的应用(Google Play、Amazon、华为)配置默认通知图标。缺失或配置不正确的图标是通知呈现损坏的最常见原因。

<Note>
  默认图标**内置于您的应用中**,而不是上传到 OneSignal 仪表板。您将它们添加到项目的资源目录(或使用 Expo 的插件配置),OneSignal SDK 会自动使用它们。
</Note>

Android 支持两个默认图标:

* **小通知图标**(必需)
* **大通知图标**(可选但推荐)

<Steps>
  <Step title="生成小通知图标">
    小通知图标显示在状态栏和通知标题中。

    **要求:**

    * 单色剪影图标
    * 透明背景(需要 alpha 通道)
    * 无颜色、渐变或阴影

    一种常见且推荐的方法是**透明背景上的白色图标**,但 Android 使用的是 **alpha 通道**,而不是白色本身。

    <Note>
      生成符合要求的小图标的最快最安全的方法是使用 [Android Asset Studio – 通知图标](http://romannurik.github.io/AndroidAssetStudio/icons-notification.html#source.space.trim=1\&source.space.pad=0\&name=ic_stat_onesignal_default)。
    </Note>

    **图标名称:** `ic_stat_onesignal_default`
  </Step>

  <Step title="创建所需的小图标尺寸">
    **必需**:您必须包含小图标的**所有密度变体**。缺少任何尺寸都可能导致 Android 回退到系统默认图标。

    | 图标名称                        | 密度 (dp) | 尺寸 (px) |
    | --------------------------- | ------- | ------- |
    | `ic_stat_onesignal_default` | MDPI    | 24x24   |
    | `ic_stat_onesignal_default` | HDPI    | 36x36   |
    | `ic_stat_onesignal_default` | XHDPI   | 48x48   |
    | `ic_stat_onesignal_default` | XXHDPI  | 72x72   |
    | `ic_stat_onesignal_default` | XXXHDPI | 96x96   |
  </Step>

  <Step title="生成大通知图标(可选)">
    **最佳实践:**

    * 正方形图像
    * PNG 或 JPG
    * 推荐透明背景
    * 推荐尺寸:**256×256 px**

    与小图标不同:

    * 允许颜色
    * **不需要**仅 alpha
    * 只需要一个尺寸

    **所需文件名:** `ic_onesignal_large_icon_default.png`
  </Step>

  <Step title="将图标放置在正确的项目路径中">
    每个图标必须放置在适合您框架的正确资源目录中。确保以下路径存在;创建您缺少的任何文件夹。

    **必需**:每个图像必须存在于以下路径中:

    <Tabs>
      <Tab title="Android Native">
        * `res/drawable-mdpi/` (24x24)
        * `res/drawable-hdpi/` (36x36)
        * `res/drawable-xhdpi/` (48x48)
        * `res/drawable-xxhdpi/` (72x72)
        * `res/drawable-xxxhdpi/` (96x96)
        * `res/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>

      <Tab title="Unity">
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-mdpi/` (24x24)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-hdpi/` (36x36)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xhdpi/` (48x48)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxhdpi/` (72x72)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxxhdpi/` (96x96)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>

      <Tab title="Cordova/Ionic">
        * `<project-root>/platforms/android/app/src/main/res/drawable-mdpi/` (24x24)
        * `<project-root>/platforms/android/app/src/main/res/drawable-hdpi/` (36x36)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xhdpi/` (48x48)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xxhdpi/` (72x72)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/` (96x96)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)

        <Warning>
          With versions of Cordova before 7.0, you will need to use `<project-root>/platforms/android/res/drawable-{size}/` instead of the path shown above when adding the icon resource to `config.xml`
        </Warning>
      </Tab>

      <Tab title="React Native / Expo">
        * `android/app/src/main/res/drawable-mdpi/` (24x24)
        * `android/app/src/main/res/drawable-hdpi/` (36x36)
        * `android/app/src/main/res/drawable-xhdpi/` (48x48)
        * `android/app/src/main/res/drawable-xxhdpi/` (72x72)
        * `android/app/src/main/res/drawable-xxxhdpi/` (96x96)
        * `android/app/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)

        **Expo 快捷方式:** 如果您使用 `onesignal-expo-plugin`,您可以提供单个 96x96 的源 PNG,插件会自动生成所有密度变体。将其添加到您的 `app.json` 或 `app.config.js`:

        ```json theme={null}
        {
          "plugins": [
            ["onesignal-expo-plugin", {
              "mode": "production",
              "smallIcons": ["./assets/ic_stat_onesignal_default.png"],
              "largeIcons": ["./assets/ic_onesignal_large_icon_default.png"]
            }]
          ]
        }
        ```

        您无需手动创建 `android/` 子目录——插件会在构建时将生成的文件放置在正确的 drawable 文件夹中。有关完整的插件配置,请参阅 [React Native / Expo SDK setup](./react-native-expo-sdk-setup)。
      </Tab>

      <Tab title=".NET Maui">
        * `Resources/Images/drawable-mdpi/` (24x24)
        * `Resources/Images/drawable-hdpi/` (36x36)
        * `Resources/Images/drawable-xhdpi/` (48x48)
        * `Resources/Images/drawable-xxhdpi/` (72x72)
        * `Resources/Images/drawable-xxxhdpi/` (96x96)
        * `Resources/Images/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>

      <Tab title="Flutter">
        * `android/app/src/main/res/drawable-mdpi/` (24x24)
        * `android/app/src/main/res/drawable-hdpi/` (36x36)
        * `android/app/src/main/res/drawable-xhdpi/` (48x48)
        * `android/app/src/main/res/drawable-xxhdpi/` (72x72)
        * `android/app/src/main/res/drawable-xxxhdpi/` (96x96)
        * `android/app/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>
    </Tabs>
  </Step>
</Steps>

您的项目应类似于此(取决于您的 SDK):

<Frame caption="Android Native 项目中 drawable 文件夹内的图标文件">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/42f16ed-Screen_Shot_2021-12-10_at_10.36.53_AM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=4b0c4810b478b4b84e3ec15984c35e19" alt="Android project directory structure showing icon files in drawable folders" width="982" height="1404" data-path="images/docs/42f16ed-Screen_Shot_2021-12-10_at_10.36.53_AM.png" />
</Frame>

<Warning>
  **图标显示问题排查:**

  * 如果您看到**实心方块**而不是图标,则图像没有正确的透明度。
  * 如果您看到 **OneSignal 铃铛图标**,则一个或多个所需的小图标尺寸缺失或放置在错误的目录中。
</Warning>

<Check>
  您的 Android 应用现在已正确配置默认通知图标。
</Check>

***

## 使用非默认图标发送通知

从 OneSignal 仪表板或 REST API 发送推送通知时,您可以使用自定义图标覆盖 Android、Amazon、华为和 Web 推送通知的默认图标。您无法覆盖 iOS 通知的图标。

### REST API 参数

**Android、Amazon 和华为 REST API 参数:**

<ParamField path="small_icon" type="string">
  Amazon: `adm_small_icon` Huawei: `huawei_small_icon`

  对于小图标,图像必须存在于与默认小图标相同的项目路径中。它不能使用远程 URL。有关添加自定义图标的位置的详细信息,请参阅[如何添加 Android 默认图标](#how-to-add-android-default-icons)。

  在 REST API 参数中设置图标名称时**不包含**文件扩展名。

  示例: `"small_icon": "my_custom_icon_name_without_extension"`
</ParamField>

<ParamField path="large_icon" type="string">
  Amazon: `adm_large_icon` Huawei: `huawei_large_icon`

  对于大图标,图像可以存在于与默认大图标相同的项目路径中,也可以作为远程 URL。有关添加自定义图标的位置的详细信息,请参阅[如何添加 Android 默认图标](#how-to-add-android-default-icons)。

  在 REST API 参数中设置图标名称时**不包含**文件扩展名。

  示例: `"large_icon": "my_custom_icon_name_without_extension"`
</ParamField>

**Web 推送 REST API 参数:**

<ParamField path="chrome_web_icon" type="string">
  Firefox: `firefox_icon`

  图像资源的 URL。必须是图像资源的直接 URL。

  示例: `"chrome_web_icon": "https://example.com/my_custom_icon.png"`
</ParamField>

<ParamField path="chrome_web_badge" type="string">
  图像资源的 URL。必须是图像资源的直接 URL。

  示例: `"chrome_web_badge": "https://i.imgur.com/9QFB20F.png"`
</ParamField>

### 仪表板

在 OneSignal 仪表板中,使用**消息 > 推送 > 新推送**表单或**模板**,导航到特定于平台的选项。

对于 Android、Amazon 和华为,如果文件存在于与默认图标相同的项目路径中,请设置图标名称时**不包含**文件扩展名。对于大通知图标,您还可以提供将显示图标的直接 URL。

<Frame caption="OneSignal 仪表板,覆盖默认图标的位置。">
  <img src="https://mintcdn.com/onesignal/-HTs3_mQDpKtLbvU/images/push/android-icon-override.png?fit=max&auto=format&n=-HTs3_mQDpKtLbvU&q=85&s=f5ad49e6b26dfa3245d82d07049f0997" alt="OneSignal dashboard showing icon override fields in Android platform settings" width="1052" height="396" data-path="images/push/android-icon-override.png" />
</Frame>

***

## 常见问题

### 为什么我的 Android 小图标显示为白色或灰色方块?

图像没有正确的透明度。Android 仅使用 alpha 通道渲染小通知图标——任何具有实心背景的完全不透明像素都会显示为填充方块。请使用 [Android Asset Studio](http://romannurik.github.io/AndroidAssetStudio/icons-notification.html#source.space.trim=1\&source.space.pad=0\&name=ic_stat_onesignal_default) 将图标重新生成为透明背景上的单色剪影。

### 为什么显示 OneSignal 铃铛图标而不是我的自定义图标?

小图标的一个或多个所需密度变体缺失或放置在错误的 drawable 目录中。您必须包含所有五个尺寸(MDPI 到 XXXHDPI),并使用确切的文件名 `ic_stat_onesignal_default`。有关正确路径,请参阅[如何添加 Android 默认图标](#how-to-add-android-default-icons)。

### 我可以为每条消息更改 iOS 通知图标吗?

不可以。iOS 始终将您的应用图标用于推送通知。没有 APNs 有效负载字段可以覆盖它。更改图标需要更新您的应用图标资源并发布新的应用版本。

### 我的 Web 推送图标应该是什么尺寸?

使用 `256x256` 像素的正方形 PNG 图像。不同的浏览器和操作系统可能会裁剪或缩放图标,但 `256x256` 在 Chrome、Firefox、Edge 和 Safari 之间提供最佳的一致性。

### 我可以为 Android 小图标使用 URL 吗?

不可以。Android 小图标必须是与您的应用捆绑的本地资源文件。只有大图标支持远程 URL。

### 如何在 Expo 中添加通知图标?

使用 `onesignal-expo-plugin`,您提供单个源 PNG(小图标为 96x96,大图标为 256x256),并在 `app.json` 或 `app.config.js` 的 `smallIcons` 和 `largeIcons` 数组下引用它。插件会自动生成所有密度变体,并在构建时将其放置在正确的 `android/` 目录中。您无需手动创建 drawable 文件夹。有关示例配置,请参阅["将图标放置在正确的项目路径中"下的 Expo 选项卡](#how-to-add-android-default-icons)。

### 我需要将默认图标上传到 OneSignal 仪表板吗?

不需要。默认通知图标内置于您的应用二进制文件中,而不是上传到 OneSignal。您将它们添加到项目的资源目录(或 Expo 的插件配置),OneSignal SDK 会自动使用它们。OneSignal 仪表板仅允许您针对 Android 和 Web 推送按消息覆盖图标。

***

## 相关页面

<Columns cols={2}>
  <Card title="图像和富媒体" icon="image" href="./rich-media">
    将大图像、GIF 和视频附加到推送通知。
  </Card>

  <Card title="Android 通知类别" icon="bell" href="./android-notification-categories">
    创建和管理 Android 通知渠道,以自定义声音、振动和重要性。
  </Card>

  <Card title="Web 推送设置" icon="globe" href="./web-push-setup">
    为 Web 推送通知配置您的网站,包括默认图标设置。
  </Card>

  <Card title="创建消息 API" icon="code" href="/reference/create-message">
    使用 REST API 发送带有自定义图标的推送通知。
  </Card>
</Columns>