close
  • 简体中文

      • html.appIcon

      • 类型：
      type AppIconItem = {
  src: string;
  size: number;
  target?: 'apple-touch-icon' | 'web-app-manifest';
  purpose?: 'any' | 'maskable' | 'monochrome' | string;
};

type AppIcon = {
  name?: string;
  icons: AppIconItem[];
  filename?: string;
};
      • 默认值： undefined

      设置 Web 应用的图标，用于在添加到移动设备的主屏幕时显示：

      • 生成 web app manifest 文件和其中的 icons 字段。
      • 生成 HTML 文件中的 apple-touch-icon 标签和 manifest 标签。
      Tip

      参考以下文档来了解更多信息：

      示例

      你需要准备多个不同大小的图标，以便在不同设备上显示。

      最常用的图标大小是 192x192 和 512x512，你也可以根据需要来自定义图标大小和图标数量。

      rsbuild.config.ts
      export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        { src: './src/assets/icon-192.png', size: 192 },
        { src: './src/assets/icon-512.png', size: 512 },
      ],
    },
  },
};

      编译后，HTML 中自动生成了以下标签：

      <link rel="manifest" href="/manifest.webmanifest" />
<link
  rel="apple-touch-icon"
  sizes="180x180"
  href="/static/image/icon-192.png"
/>

      其中，manifest.webmanifest 是一个 JSON 文件，包含了应用的名称和图标等信息。

      {
  "name": "My Website",
  "icons": [
    {
      "src": "/static/image/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/static/image/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
      图标大小

      对于 Chrome，你至少需要提供 192x192 像素的图标和 512x512 像素的图标。如果仅提供这两种图标大小，Chrome 会自动缩放图标以适应设备大小。如果你希望缩放自己的图标，并调整图标以实现像素完美，请以 48dp 为增量提供图标。

      name

      • 类型： string
      • 默认值： undefined

      应用的名称，用于在添加到移动设备的主屏幕时显示。如果未设置，则不会生成 manifest.webmanifest 文件。

      详见 Web app manifests - name。

      icons

      • 类型： AppIconItem[]
      • 默认值： undefined

      图标列表，其中：

      • src 是图标的路径，可以是 URL 地址、文件的绝对路径，或是相对于项目 root 的相对路径。
      • size 是图标的大小，以像素为单位。
      • target 是图标的目标，可以是 apple-touch-icon 或 web-app-manifest。如果未设置 target，默认情况下，manifest 文件会包含所有的图标，而 apple-touch-icon 标签只会包含小于 200x200 的图标。
      • purpose 是一个区分大小写的字符串，用于指定浏览器或操作系统在何种场景下可以使用该图标。该字段仅在 target 为 'web-app-manifest' 时生效。更多信息请参考 MDN - purpose。

      示例

      src 可以设置为绝对路径：

      import path from 'node:path';

export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        { src: path.resolve(__dirname, './assets/icon-192.png'), size: 192 },
        { src: path.resolve(__dirname, './assets/icon-512.png'), size: 512 },
      ],
    },
  },
};

      使用 target 选项来指定图标的目标：

      rsbuild.config.ts
      export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        {
          src: './src/assets/icon-180.png',
          size: 180,
          target: 'apple-touch-icon',
        },
        {
          src: './src/assets/icon-192.png',
          size: 192,
          target: 'web-app-manifest',
        },
        {
          src: './src/assets/icon-512.png',
          size: 512,
          target: 'web-app-manifest',
        },
      ],
    },
  },
};

      filename

      • 类型： string
      • 默认值： 'manifest.webmanifest'

      manifest 文件的文件名。

      rsbuild.config.ts
      export default {
  html: {
    appIcon: {
      filename: 'manifest.json',
    },
  },
};

      版本历史

      版本变更内容
      v1.5.5新增对 purpose 选项的支持