nativeImage
tray や Dock やアプリケーションのアイコンを PNG や JPG ファイルで作成します。
Electron では、 API が画像を取る場合、ファイルパスまたは NativeImage
インスタンスを渡すことができます。 null
が渡されたときは空の画像が使用されます。
例として、tray を作ったりウインドウのアイコンを設定したりするとき、string
で画像ファイルパスを渡せます。
const { BrowserWindow, Tray } = require('electron')
const appIcon = new Tray('/Users/somebody/images/icon.png')
const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })
console.log(appIcon, win)
clipboard から画像を読む場合は、NativeImage
が返されます。
const { clipboard, Tray } = require('electron')
const image = clipboard.readImage()
const appIcon = new Tray(image)
console.log(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
この記事 内の サイズ要件 の章を確認して下さい。
高解像度の画像
Apple Retina ディスプレイのような高解像度をサポートしているプラットフォームにおいて、画像のファイルネームの後ろに @2x
を加えることで、高解像度の画像としてマークすることができます。
例えば、icon.png
が通常の標準解像度の画像であれば、icon@2x.png
が2倍のピクセル密度を持つ高解像度の画像として扱われます。
同時に異なるピクセル密度のディスプレイをサポートしたい場合、同じフォルダ内に異なるサイズの画像を置き、DPI 接尾子無しでファイル名を使用して下さい。 以下がその例です。
images/
├── icon.png
├── icon@2x.png
└── icon@3x.png
const { Tray } = require('electron')
const appIcon = new Tray('/Users/somebody/images/icon.png')
console.log(appIcon)
以下の DPI 接尾子がサポートされています。
@1x
@1.25x
@1.33x
@1.4x
@1.5x
@1.8x
@2x
@2.5x
@3x
@4x
@5x
テンプレート画像
テンプレート画像は黒色とアルファチャンネルで構成されます。 テンプレート画像は単体の画像として使用するものではなく、通常、最終的にさせたい見た目を作成するため、他のコンテンツと混合されます。
最も一般的なケースは、メニューバーのアイコンに使用することです。これは明るいメニューバーと暗いメニューバーの両方に適応できます。
注釈: テンプレート画像は macOS でのみサポートされています。
画像をテンプレート画像としてマークするには、そのファイル名が Template
で終わる必要があります。 以下がその例です。
xxxTemplate.png
xxxTemplate.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').nativeImage
const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)
nativeImage.createFromBitmap(buffer, options)
buffer
Buffer
戻り値 NativeImage
buffer
から新しい NativeImage
インスタンスを作成します。これにはtoBitmap()
によって返された生のビットマップピクセルデータが含まれます。 詳細な形式はプラットフォームに依存します。
nativeImage.createFromBuffer(buffer[, options])
buffer
Buffer
戻り値 NativeImage
buffer
から NativeImage
の新しいインスタンスを作成します。 最初に PNG または JPEG としてデコードしようとします。
nativeImage.createFromDataURL(dataURL)
dataURL
string
戻り値 NativeImage
dataURL
から NativeImage
の新しいインスタンスを作成します。
nativeImage.createFromNamedImage(imageName[, hslShift])
macOS
imageName
stringhslShift
number[] (任意)
戻り値 NativeImage
指定した画像名にマップされる NSImage から NativeImage
の新しいインスタンスを作成します。 使用可能な値のリストは、システムアイコン
を参照してください。
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])
戻り値 Buffer
- PNG
エンコードされた画像データを含む Buffer。
image.toJPEG(quality)
quality
Integer - 0 - 100 の間です。
戻り値 Buffer
- JPEG
エンコードされた画像データを含む Buffer。
image.toBitmap([options])
戻り値 Buffer
- 生のビットマップ画像のピクセルデータのコピーを含む Buffer。
image.toDataURL([options])
戻り値 string
- 画像のデータURL。
image.getBitmap([options])
戻り値 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
- 画像がテンプレート画像かどうか。
image.crop(rect)
rect
Rectangle - 画像をトリミングする領域。
戻り値 NativeImage
- トリミングされた画像。
image.resize(options)
戻り値 NativeImage
- リサイズされた画像。
height
または width
のどちらかのみが指定された場合、アスペクト比はリサイズされた画像でも保持されます。
image.getAspectRatio([scaleFactor])
scaleFactor
Number (任意) - 省略値は 1.0 です。
戻り値 Number
- イメージのアスペクト比。
scaleFactor
が渡された場合、渡された値に最も近い画像表現に対応するアスペクト比を返します。
image.getScaleFactors()
戻り値 Number[]
- この NativeImage の表現に対応するすべての拡大率の配列。
image.addRepresentation(options)
画像の表現を指定された縮尺で追加します。 これによって、異なる縮尺の表現を明示的に画像へ追加できます。 空の画像で呼び出すことができます。
インスタンスプロパティ
nativeImage.isMacTemplateImage
macOS
boolean
型のプロパティです。その画像が テンプレート画像 と見なされるかどうかを決定します。
このプロパティは macOS にのみ影響することに注意してください。