メインコンテンツへ飛ぶ

nativeImage

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

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

The nativeImage module provides a unified interface for manipulating system images. These can be handy if you want to provide multiple scaled versions of the same icon or take advantage of macOS template images.

Electron APIs that take image files accept either file paths or NativeImage instances. An empty and transparent image will be used when null is passed.

For example, when creating a Tray or setting a BrowserWindow's icon, you can either pass an image file path as a string:

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' })

or generate a NativeImage instance from the same file:

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 })

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

Currently, PNG and JPEG image formats are supported across all platforms. PNG is recommended because of its support for transparency and lossless compression.

Windows では、ファイルパスから ICO アイコンを読み込むこともできます。 For best visual quality, we recommend including at least the following sizes:

  • 小さいアイコン
    • 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

Check the Icon Scaling section in the Windows App Icon Construction reference.

note

EXIF metadata is currently not supported and will not be taken into account during image encoding and decoding.

高解像度の画像​

On platforms that support high pixel density displays (such as Apple Retina), you can append @2x after image's base filename to mark it as a 2x scale high resolution image.

For example, if icon.png is a normal image that has standard resolution, then icon@2x.png will be treated as a high resolution image that has double Dots per Inch (DPI) density.

If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes within Electron. 以下がその例です。

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

Template Image macOS​

On macOS, template images consist of black and an alpha channel. テンプレート画像は単体の画像として使用するものではなく、通常、最終的にさせたい見た目を作成するため、他のコンテンツと混合されます。

The most common case is to use template images for a menu bar (Tray) icon, so it can adapt to both light and dark menu bars.

To mark an image as a template image, its base filename should end with the word Template (e.g. xxxTemplate.png). You can also specify template images at different DPI densities (e.g. xxxTemplate@2x.png).

メソッド​

The nativeImage module has the following methods, all of which return an instance of the NativeImage class:

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 - path to a file that we intend to construct an image out of.

戻り値 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

Creates a new NativeImage instance from dataUrl, a base 64 encoded Data URL string.

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

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

戻り値 NativeImage

Creates a new NativeImage instance from the NSImage that maps to the given image name. See Apple's NSImageName documentation for a list of possible values.

hslShift は以下のルールで画像に適用されます。

  • hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).
  • 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])​

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

Returns string - The Data URL of the image.

image.getBitmap([options])​

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

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

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

image.getNativeHandle() macOS​

戻り値 Buffer - 画像の元になるネイティブハンドルへの C ポインタを格納する Buffer。 On macOS, a pointer to NSImage instance is returned.

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

image.isEmpty()​

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

image.getSize([scaleFactor])​

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

戻り値 Size.

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

image.setTemplateImage(option)​

  • option boolean

Marks the image as a macOS template image.

image.isTemplateImage()​

Returns boolean - Whether the image is a macOS template image.

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 です。

Returns Number - The image's aspect ratio (width divided by height).

scaleFactor が渡された場合、渡された値に最も近い画像表現に対応するアスペクト比を返します。

image.getScaleFactors()​

Returns Number[] - An array of all scale factors corresponding to representations for a given NativeImage.

image.addRepresentation(options)​

  • options Object
    • scaleFactor Number (任意) - 追加する画像表現の拡大率です。
    • width Integer (任意) - 既定値は 0 です。 buffer にビットマップバッファが指定されている場合は必要です。
    • height Integer (任意) - 既定値は 0 です。 buffer にビットマップバッファが指定されている場合は必要です。
    • buffer Buffer (任意) - 生の画像データを格納するバッファ。
    • dataURL string (任意) - Base64 エンコードした PNG または JPEG 画像を格納しているデータURL。

画像の表現を指定された縮尺で追加します。 This can be used to programmatically add different scale factor representations to an image. 空の画像で呼び出すことができます。

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

nativeImage.isMacTemplateImage macOS​

A boolean property that determines whether the image is considered a template image.

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