nativeImage

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

[!IMPORTANT] If you want to call this API from a renderer process with context isolation enabled, place the API call in your preload script and expose it using the contextBridge API.

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

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

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

Main Process

const{BrowserWindow,Tray}=require('electron')

const tray =newTray('/Users/somebody/images/icon.png')
const win =newBrowserWindow({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 =newTray(trayIcon)
const win =newBrowserWindow({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 =newTray('/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 - the desired width and height (positive numbers) of the thumbnail.

Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.

[!NOTE] Windows implementation will ignore size.height and scale the height according to size.width.

`nativeImage.createFromPath(path)`

path string - 画像を構築するためのファイルへのパス。

戻り値 NativeImage

Creates a new NativeImage instance from an image file (e.g., PNG or JPEG) located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image.

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

where SYSTEM_IMAGE_NAME should be replaced with any value from this list.

クラス: NativeImage

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

Process: Main, Renderer
This class is not exported from the 'electron' module. Electron API では、他のメソッドの戻り値としてのみ利用できます。

インスタンスメソッド

NativeImage クラスのインスタンスには、以下のメソッドがあります。

`image.toPNG([options])`

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

Returns Buffer - A Buffer that contains the image's PNG encoded data.

`image.toJPEG(quality)`

quality Integer - 0 - 100 の間です。

Returns Buffer - A Buffer that contains the image's JPEG encoded data.

`image.toBitmap([options])`

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

Returns Buffer - A Buffer that contains a copy of the image's raw bitmap pixel data.

`image.toDataURL([options])`

History

Version(s)	Changes
None	`nativeImage.toDataURL` が PNG の色空間を保持するようになりました

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

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

`image.getBitmap([options])` 非推奨

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

Legacy alias for image.toBitmap().

`image.getNativeHandle()` macOS

Returns Buffer - A Buffer that stores C pointer to underlying native handle of the image. macOS では、NSImage のインスタンスのポインタが返されます。

返されるポインタは、コピーではなく、元のネイティブな画像へのウィークポインタであることに注意して下さい。関連する nativeImage インスタンスが確実に_保持されなければなりません_。

`image.isEmpty()`

戻り値 boolean - 画像が空かどうか。

`image.getSize([scaleFactor])`

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

Returns Size.

scaleFactor が渡された場合、渡された値に最も近い画像表現に対応するサイズを返します。

`image.setTemplateImage(option)`

option boolean

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

`image.isTemplateImage()`

戻り値 boolean - 画像が macOS のテンプレート画像かどうか。

`image.crop(rect)`

rect Rectangle - The area of the image to crop.

戻り値 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 にのみ影響することに注意してください。

nativeImage

サポートされているフォーマット​

高解像度の画像​

テンプレート画像 macOS​

メソッド​

nativeImage.createEmpty()​

nativeImage.createThumbnailFromPath(path, size) macOS Windows​

nativeImage.createFromPath(path)​

nativeImage.createFromBitmap(buffer, options)​

nativeImage.createFromBuffer(buffer[, options])​

nativeImage.createFromDataURL(dataURL)​

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

クラス: NativeImage​

インスタンスメソッド​

image.toPNG([options])​

image.toJPEG(quality)​

image.toBitmap([options])​

image.toDataURL([options])​

image.getBitmap([options]) 非推奨​

image.getNativeHandle() macOS​

image.isEmpty()​

image.getSize([scaleFactor])​

image.setTemplateImage(option)​

image.isTemplateImage()​

image.crop(rect)​

image.resize(options)​

image.getAspectRatio([scaleFactor])​

image.getScaleFactors()​

image.addRepresentation(options)​

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

nativeImage.isMacTemplateImage macOS​

サポートされているフォーマット

高解像度の画像

テンプレート画像 macOS

メソッド

`nativeImage.createEmpty()`

`nativeImage.createThumbnailFromPath(path, size)` macOS Windows

`nativeImage.createFromPath(path)`

`nativeImage.createFromBitmap(buffer, options)`

`nativeImage.createFromBuffer(buffer[, options])`

`nativeImage.createFromDataURL(dataURL)`

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

クラス: NativeImage

インスタンスメソッド

`image.toPNG([options])`

`image.toJPEG(quality)`

`image.toBitmap([options])`

`image.toDataURL([options])`

`image.getBitmap([options])` 非推奨

`image.getNativeHandle()` macOS

`image.isEmpty()`

`image.getSize([scaleFactor])`

`image.setTemplateImage(option)`

`image.isTemplateImage()`

`image.crop(rect)`

`image.resize(options)`

`image.getAspectRatio([scaleFactor])`

`image.getScaleFactors()`

`image.addRepresentation(options)`

インスタンスプロパティ

`nativeImage.isMacTemplateImage` macOS