メインコンテンツへ飛ぶ

nativeImage

tray や Dock やアプリケーションのアイコンを PNG や JPG ファイルで作成します。

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

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

画像ファイルを受け取る Electron API は、ファイルパスまたは NativeImage インスタンスのいずれかを受け付けます。 null が渡されたときは空の透明な画像が使用されます。

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

Main Process
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 インスタンスを生成します。

Main Process
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 (DPI スケール 100%)
    • 20x20 (DPI スケール 125%)
    • 24x24 (DPI スケール 150%)
    • 32x32 (DPI スケール 200%)
  • 大きいアイコン
    • 32x32 (DPI スケール 100%)
    • 40x40 (DPI スケール 125%)
    • 48x48 (DPI スケール 150%)
    • 64x64 (DPI スケール 200%)
    • 256x256

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

note

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

高解像度の画像​

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

例えば、icon.png が通常の標準解像度の画像であれば、icon@2x.png が 2 倍のインチ毎ドット (DPI) 密度を持つ高解像度の画像として扱われます。

Electron で同時に異なるピクセル密度のディスプレイをサポートしたい場合、同じフォルダ内に異なるサイズの画像を置き、DPI 接尾子無しでファイル名を使用して下さい。 以下がその例です。

images/
├── icon.png
├── icon@2x.png
└── icon@3x.png
Main Process
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 では、テンプレート画像 は黒とアルファチャンネルで構成されます。 テンプレート画像は単体の画像として使用するものではなく、通常、最終的にさせたい見た目を作成するため、他のコンテンツと混合されます。

最も一般的なケースは、メニューバー (Tray) のアイコンに使用することです。これは明るいメニューバーと暗いメニューバーの両方に適応できます。

画像をテンプレート画像としてマークするには、その基本ファイル名の末尾に 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

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

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

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

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

  • imageName string
  • hslShift number[] (任意)

戻り値 NativeImage

指定の画像名に対応する NSImage から NativeImage の新しいインスタンスを作成します。 使用可能な値のリストは、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​

tray や Dock やアプリケーションアイコンのような画像を、ネイティブにラップします。

プロセス: メイン、レンダラー
このクラスは '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])​

History
  • options Object (任意)
    • scaleFactor Number (任意) - 省略値は 1.0 です。

戻り値 string - 画像の データ URL。

image.getBitmap([options])​

  • options Object (任意)
    • scaleFactor Number (任意) - 省略値は 1.0 です。

戻り値 Buffer - 生のビットマップ画像のピクセルデータを含む Buffer。

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

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

画像を テンプレート画像 としてマークします。

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 (任意) - Base64 エンコードした PNG または JPEG 画像を格納しているデータURL。

画像の表現を指定された縮尺で追加します。 これによって、異なる縮尺の表現をプログラムで画像に追加できます。 空の画像で呼び出すことができます。

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

nativeImage.isMacTemplateImage macOS​

boolean 型のプロパティです。その画像が テンプレート画像 と見なされるかどうかを決定します。

このプロパティは macOS にのみ影響することに注意してください。