メインコンテンツへスキップ

nativeImage

PNGまたはJPGファイルを使用して、トレイ、ドック、およびアプリケーションのアイコンを作成します。

プロセス: メイン, レンダラー

nativeImageモジュールは、システムイメージを操作するための統一されたインターフェースを提供します。 これらは、同じアイコンの複数のスケールされたバージョンを提供したり、macOSのテンプレート画像を活用したりする場合に便利です。

画像ファイルを受け入れるElectron APIは、ファイルパスまたはNativeImageインスタンスを受け入れます。nullが渡された場合、空で透明な画像が使用されます。

たとえば、トレイを作成したり、BrowserWindowのアイコンを設定したりするときに、画像ファイルのパスを文字列として渡すことができます。

メインプロセス
const { BrowserWindow, Tray } = require('electron')

const tray = new Tray('/Users/somebody/images/icon.png')
const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })

または、同じファイルからNativeImageインスタンスを生成します。

メインプロセス
const { BrowserWindow, nativeImage, Tray } = require('electron')

const trayIcon = nativeImage.createFromPath('/Users/somebody/images/icon.png')
const appIcon = nativeImage.createFromPath('/Users/somebody/images/window.png')
const tray = new Tray(trayIcon)
const win = new BrowserWindow({ icon: appIcon })

サポートされている形式​

現在、PNGおよびJPEG画像形式はすべてのプラットフォームでサポートされています。PNGは、透明度と可逆圧縮をサポートしているため、推奨されます。

Windowsでは、ファイルパスからICOアイコンをロードすることもできます。 最適な画質を得るには、少なくとも次のサイズを含めることをお勧めします。

  • 小さいアイコン
    • 16x16 (100% DPIスケール)
    • 20x20 (125% DPIスケール)
    • 24x24 (150% DPIスケール)
    • 32x32 (200% DPIスケール)
  • 大きいアイコン
    • 32x32 (100% DPIスケール)
    • 40x40 (125% DPIスケール)
    • 48x48 (150% DPIスケール)
    • 64x64 (200% DPIスケール)
    • 256x256

Windowsのアプリアイコンの構成リファレンスの「アイコンのスケーリング」セクションを確認してください。

注意

EXIFメタデータは現在サポートされておらず、画像のエンコードとデコード中に考慮されません。

高解像度画像​

高ピクセル密度ディスプレイ（Apple Retinaなど）をサポートするプラットフォームでは、画像の基本ファイル名の後に@2xを追加して、2倍スケールの高解像度画像としてマークできます。

たとえば、icon.pngが標準解像度の通常の画像の場合、icon@2x.pngは、1インチあたりのドット数（DPI）密度が2倍の高解像度画像として扱われます。

異なるDPI密度のディスプレイを同時にサポートする場合は、異なるサイズの画像を同じフォルダに入れ、Electron内でDPIサフィックスなしでファイル名を使用できます。 例えば

images/
├── icon.png
├── icon@2x.png
└── icon@3x.png
メインプロセス
const { Tray } = require('electron')
const appTray = new Tray('/Users/somebody/images/icon.png')

DPIの次のサフィックスもサポートされています。

  • @1x
  • @1.25x
  • @1.33x
  • @1.4x
  • @1.5x
  • @1.8x
  • @2x
  • @2.5x
  • @3x
  • @4x
  • @5x

テンプレート画像 macOS​

macOSでは、テンプレート画像は黒とアルファチャンネルで構成されています。 テンプレート画像はスタンドアロン画像として使用することを意図しておらず、通常は目的の最終的な外観を作成するために他のコンテンツと混合されます。

最も一般的なケースは、メニューバー（トレイ）アイコンにテンプレート画像を使用することです。これにより、ライトとダークの両方のメニューバーに適応できます。

画像をテンプレート画像としてマークするには、その基本ファイル名を単語Template（例：xxxTemplate.png）で終わらせる必要があります。異なるDPI密度でテンプレート画像を指定することもできます（例：xxxTemplate@2x.png）。

メソッド​

nativeImageモジュールには次のメソッドがあり、すべてNativeImageクラスのインスタンスを返します。

nativeImage.createEmpty()​

NativeImageを返します

空のNativeImageインスタンスを作成します。

nativeImage.createThumbnailFromPath(path, size) macOS Windows​

  • path string - サムネイルを作成するファイルのパス。
  • size Size - サムネイルの目的の幅と高さ（正の数）。

Promise<NativeImage>を返します - ファイルのサムネイルプレビュー画像で満たされ、これはNativeImageです。

注：Windowsの実装では、size.heightは無視され、size.widthに従って高さが調整されます。

nativeImage.createFromPath(path)​

  • path string - 画像を作成するファイルのパス。

NativeImageを返します

pathにあるファイルから新しいNativeImageインスタンスを作成します。 このメソッドは、pathが存在しない、読み取れない、または有効な画像ではない場合は、空の画像を返します。

const { nativeImage } = require('electron')

const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)

nativeImage.createFromBitmap(buffer, options)​

  • buffer Buffer
  • options Object
    • width Integer
    • height Integer
    • scaleFactor Number (オプション) - デフォルトは1.0です。

NativeImageを返します

toBitmap()によって返される生のビットマップピクセルデータを含むbufferから新しいNativeImageインスタンスを作成します。 特定の形式はプラットフォームに依存します。

nativeImage.createFromBuffer(buffer[, options])​

  • buffer Buffer
  • options Object (オプション)
    • width Integer (オプション) - ビットマップバッファに必要です。
    • height Integer (オプション) - ビットマップバッファに必要です。
    • scaleFactor Number (オプション) - デフォルトは1.0です。

NativeImageを返します

bufferから新しいNativeImageインスタンスを作成します。 まずPNGまたはJPEGとしてデコードしようとします。

nativeImage.createFromDataURL(dataURL)​

  • dataURL string

NativeImageを返します

base64でエンコードされたData URL文字列であるdataUrlから新しいNativeImageインスタンスを作成します。

nativeImage.createFromNamedImage(imageName[, hslShift]) macOS​

  • imageName string
  • hslShift number[] (オプション)

NativeImageを返します

指定された画像名にマップされるNSImageから新しいNativeImageインスタンスを作成します。 可能な値のリストについては、AppleのNSImageNameドキュメントを参照してください。

hslShiftは、次の規則に従って画像に適用されます。

  • hsl_shift[0] (色相): 画像の絶対色相値 - 0と1は、色相環（赤）で0と360にマッピングされます。
  • hsl_shift[1] (彩度): 次のキー値を持つ画像の彩度シフト：0 =すべての色を削除します。 0.5 =変更しないでください。 1 =画像を完全に彩度にします。
  • hsl_shift[2] (明度): 次のキー値を持つ画像の明度シフト：0 =すべての明度を削除します（すべてのピクセルを黒にします）。 0.5 =変更しないでください。 1 =完全な明度（すべてのピクセルを白にします）。

つまり、[-1, 0, 1]にすると画像が完全に白になり、[-1, 1, 0]にすると画像が完全に黒になります。

場合によっては、NSImageNameがその文字列表現と一致しないことがあります。 その一例がNSFolderImageNameで、その文字列表現は実際にはNSFolderになります。 したがって、渡す前に、画像の正しい文字列表現を判断する必要があります。 これは、次の方法で実行できます。

echo -e '#import <Cocoa/Cocoa.h>\nint main() { NSLog(@"%@", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test

ここで、SYSTEM_IMAGE_NAMEは、このリストの値に置き換える必要があります。

クラス: NativeImage​

トレイ、ドック、アプリケーションアイコンなどの画像をネイティブにラップします。

プロセス: メイン, レンダラー
このクラスは、'electron'モジュールからエクスポートされません。 Electron APIの他のメソッドの戻り値としてのみ利用できます。

インスタンスメソッド​

NativeImageクラスのインスタンスでは、次のメソッドを使用できます。

image.toPNG([options])​

  • options Object (オプション)
    • scaleFactor Number (オプション) - デフォルトは1.0です。

Bufferを返します - イメージのPNGエンコードされたデータを含むBufferです。

image.toJPEG(quality)​

  • quality Integer - 0～100の整数。

Bufferを返します - イメージのJPEGエンコードされたデータを含むBufferです。

image.toBitmap([options])​

  • options Object (オプション)
    • scaleFactor Number (オプション) - デフォルトは1.0です。

Bufferを返します - イメージの生のビットマップピクセルデータのコピーを含むBufferです。

image.toDataURL([options])​

履歴
  • options Object (オプション)
    • scaleFactor Number (オプション) - デフォルトは1.0です。

stringを返します - イメージのデータURLです。

image.getBitmap([options])​

  • options Object (オプション)
    • scaleFactor Number (オプション) - デフォルトは1.0です。

Bufferを返します - イメージの生のビットマップピクセルデータを含むBufferです。

getBitmap()とtoBitmap()の違いは、getBitmap()はビットマップデータをコピーしないため、返されたBufferを現在のイベントループティックですぐに使用する必要があることです。そうしないと、データが変更または破棄される可能性があります。

image.getNativeHandle() macOS​

Bufferを返します - イメージの基になるネイティブハンドルのCポインタを格納するBufferです。macOSでは、NSImageインスタンスへのポインタが返されます。

返されるポインタは、コピーではなく基になるネイティブイメージへの弱いポインタであるため、関連するnativeImageインスタンスが維持されていることを必ず確認する必要があります。

image.isEmpty()​

booleanを返します - イメージが空かどうか。

image.getSize([scaleFactor])​

  • scaleFactor Number (オプション) - デフォルトは1.0です。

Sizeを返します。

scaleFactorが渡されると、渡された値に最も近いイメージ表現に対応するサイズが返されます。

image.setTemplateImage(option)​

  • option boolean

イメージをmacOSのテンプレートイメージとしてマークします。

image.isTemplateImage()​

booleanを返します - イメージがmacOSのテンプレートイメージかどうか。

image.crop(rect)​

  • rect Rectangle - 切り抜くイメージの領域。

NativeImageを返します - 切り抜かれたイメージ。

image.resize(options)​

  • options Object
    • width Integer (オプション) - デフォルトはイメージの幅。
    • height Integer (オプション) - デフォルトはイメージの高さ。
    • quality string (オプション) - リサイズされたイメージの希望品質。可能な値には、good、better、またはbestが含まれます。デフォルトはbestです。これらの値は、希望の品質/速度のトレードオフを表します。それらは、基盤となるプラットフォームの機能 (CPU、GPU) に依存するアルゴリズム固有の方法に変換されます。3つの方法すべてが、特定のプラットフォームで同じアルゴリズムにマップされる可能性があります。

NativeImageを返します - リサイズされたイメージ。

heightまたはwidthのみが指定されている場合、リサイズされたイメージでは現在の縦横比が維持されます。

image.getAspectRatio([scaleFactor])​

  • scaleFactor Number (オプション) - デフォルトは1.0です。

Numberを返します - イメージの縦横比 (幅を高さで割ったもの)。

scaleFactorが渡されると、渡された値に最も近いイメージ表現に対応する縦横比が返されます。

image.getScaleFactors()​

Number[]を返します - 特定のNativeImageの表現に対応するすべてのスケールファクターの配列。

image.addRepresentation(options)​

  • options Object
    • scaleFactor Number (オプション) - イメージ表現を追加するスケールファクター。
    • width Integer (オプション) - デフォルトは0。ビットマップバッファーがbufferとして指定されている場合は必須。
    • height Integer (オプション) - デフォルトは0。ビットマップバッファーがbufferとして指定されている場合は必須。
    • buffer Buffer (オプション) - 生のイメージデータを含むバッファー。
    • dataURL string (オプション) - base 64エンコードされたPNGまたはJPEGイメージのいずれかを含むデータURL。

特定のスケールファクターのイメージ表現を追加します。これは、異なるスケールファクター表現をプログラムでイメージに追加するために使用できます。これは、空のイメージで呼び出すことができます。

インスタンスプロパティ​

nativeImage.isMacTemplateImage macOS​

イメージがテンプレートイメージと見なされるかどうかを決定するbooleanプロパティ。

このプロパティはmacOSでのみ有効であることに注意してください。