icons

icons はマニフェストのメンバーで、このウェブアプリケーションを表すアイコンを定義する 1 つ以上の画像を指定するために使用します。

構文

json
/* 最小限必要なプロパティのある単一のアイコン */
"icons": [
  {
    "src": "icon/basic-icon.png"
  }
]

/* 複数の目的をもつ単一のアイコン */
"icons": [
  {
    "src": "icon/basic-icon.png",
    "purpose": "monochrome maskable"
  }
]

/* さまざまなプロパティによる 2 つのアイコン */
"icons": [
  {
    "src": "icon/low-res.png",
    "sizes": "48x48"
  },
  {
    "src": "maskable_icon.png",
    "sizes": "48x48",
    "type": "image/png"
  }
]

icons

オブジェクトの配列です。 各オブジェクトは、特定の用途で使用されるアイコンを表します。 例えば、異なる画面サイズの端末上でウェブアプリを表すアイコンを追加したり、さまざまなオペレーティングシステムとの統合、スプラッシュ画面、アプリ通知などのために追加することができます。

それぞれのアイコンオブジェクトには、 1 つ以上のプロパティを設定することができます。このうち、 src のみが必須です。利用可能なプロパティは次の通りです。

src

アイコン画像ファイルへのパスを指定する文字列です。 src が相対パスの場合、そのパスはマニフェストファイルの URL からの相対パスとなります。 例えば、相対 URL が images/icon-192x192.png でマニフェストファイルの場所が https://example.com/manifest.json である場合、 https://example.com/images/icon-192x192.png に解決されます。

sizes 省略可

アイコンファイルを使用することができる 1 つ以上のサイズを指定する文字列です。 それぞれのサイズは <幅のピクセル数>x<高さのピクセル数> として指定します。 複数のサイズを指定する場合は、それらを空間で区切ります。例えば、 48x48 96x96 です。 複数のアイコンが利用できる場合、ブラウザーは具体的な表示コンテキストに最適なアイコンを選択することがあります。 PNG のようなラスター形式の場合、正確な利用できるサイズを指定することをお勧めします。 SVG のようなベクター形式では、拡大縮小が可能であることをを示すために any を使用することができます。 sizes` を指定しない場合、アイコンの選択と表示は、ブラウザーの実装によって異なる場合があります。

なお、 sizes の書式は HTML の <link> 要素の sizes 属性と似ています。

type 省略可

アイコンの MIME タイプを指定する文字列です。 値は image/<subtype> という形式で指定する必要があり、ここで <subtype> は特定の画像形式です。例えば、image/png は PNG 画像を示します。 省略した場合、ブラウザーは通常、ファイル拡張子から画像形式を推測します。

purpose 省略可

大文字と小文字を区別するキーワード文字列で、ブラウザーまたはオペレーティングシステムでアイコンが使用できる 1 つ以上の用途を指定します。 値は、単一のキーワードまたは複数のスペースで区切られたキーワードです。 省略すると、ブラウザーはこのアイコンをあらゆる目的に使用することができます。

ブラウザーは、これらの値を手掛かりとして、アイコンをどこにどのように表示するかを決定します。 例えば、 monochrome アイコンは、ベタ塗りのバッジや固定アイコンとして使用されることがあり、これは視覚的にフルカラーの起動アイコンとは異なります。 複数のキーワード、例えば、monochrome maskableとすれば、ブラウザーにそのアイコンをそれらの目的のどちらにも使用することができます。 有効な値とともに認識されていない目的が含まれている場合(例: monochrome fizzbuzz)、そのアイコンは有効な目的に使用することができます。 ただし、認識されていない目的のみを指定した場合(例えば、 fizzbuzz など)、それは無視されます。

有効な値としては次のようなものがあります。

monochrome

このアイコンは、単色の塗りつぶしアイコンとして使うためのものであることを示します。 この値により、ブラウザーはアイコンの色情報を破棄し、アルファチャンネルのみをソリッドフィルの上のマスクとして使用します。

maskable

アイコンがアイコンマスクとセーフゾーンを考慮して設計されていることを示します。これにより、セーフゾーン外の画像のどの部分も無視され、マスクで覆い隠されます。

any

アイコンをどのようなコンテキストでも使用できることを示します。これが既定値です。

解説

アイコンは、オペレーティングシステムのタスクスイッチャー、システム設定、ホーム画面、アプリケーションの一覧、アプリケーションアイコンが表示される他の場所など、さまざまな場面でウェブアプリケーションを一意に識別します。

アイコンを使用できるコンテキストは、ブラウザーとオペレーティングシステムによって、指定されたサイズと形式に基づいて決定されます。

セキュリティの考慮事項

ブラウザーがアイコン画像を取得する能力は、マニフェストのオーナー文書内のコンテンツセキュリティポリシー (CSP) によって管理されており、特に img-src ディレクティブによって管理されています。このセキュリティの側面は、 src プロパティに関連しています。

例えば、 CSP ヘッダーの img-src ディレクティブで icons.example.com を指定した場合、そのドメインからのアイコンのみが取得可能に設定されます。 2 種類のアイコンを含むマニフェストで、一方が icons.example.com/low-res から、もう一方が other.com/hi-res から取得される場合、 CSP の制限により、前者のアイコンのみが正常に取得されます。

パフォーマンスの考慮事項

type プロパティを指定すると、対応していない形式の画像をブラウザーがより簡単に無視できるようになるため、パフォーマンスが大幅に向上します。 type プロパティを指定しなかった場合、ブラウザーはよりリソースに集中した方法、たとえばファイルのシグネチャを MIME スニッフィングなどを使用する必要があるかもしれません。

少なくとも、 type プロパティを除外する場合は、アイコン画像に適切な、かつ曖昧さのないファイル拡張子を使用してください。

複数のアイコンを宣言

この例では、さまざまなシナリオや端末に対応する複数のアイコンを宣言する方法を示しています。特定の状況に対応するアイコンに対応していない場合や利用できない場合は、ブラウザーは利用できる他の形式やサイズに代替します。

  • 2 つの同じサイズ (48x48) のアイコンが異なる形式で指定されています。最初のアイコンは、 type プロパティを使用して WebP として明示的に指定されています。ブラウザーが WebP に対応していない場合は、同じサイズの 2 つ目のアイコンに切り替わります。 2 つ目のアイコンの場合、ブラウザーは HTTP ヘッダーから、または画像ファイルのコンテンツから推測して、 MIME タイプを決定します。このサイズのアイコンは、通常、ブラウザーのタブやブックマークに使用されます。

  • ICO ファイルは、 72x72 から 256x256 までの範囲で複数のサイズが指定されて提供されています。 ICO ファイルには、さまざまな表示サイズに個別に最適化された複数のラスターアイコンが含まれています。これらのサイズのアイコンは、デスクトップのショートカットとして一般的に使用されています。

  • もっと大きなアイコン(257x257 以上)では、 SVG ファイルが指定されます。このアイコンの sizes 値は any に設定され、ブラウザーがこのアイコンを任意のサイズで使用することができるようになります。 SVG アイコンは大きなサイズでも品質を保ちます。これらのアイコンはプログレッシブウェブアプリ (PWA) のような高解像度ディスプレイに最適です。

json
{
  "icons": [
    {
      "src": "icon/low-res.webp",
      "sizes": "48x48",
      "type": "image/webp"
    },
    {
      "src": "icon/low-res",
      "sizes": "48x48"
    },
    {
      "src": "icon/hd_hi.ico",
      "sizes": "72x72 96x96 128x128 256x256"
    },
    {
      "src": "icon/hd_hi.svg",
      "sizes": "any"
    }
  ]
}

仕様書

Specification
Web Application Manifest
# icons-member

ブラウザーの互換性

関連情報