nativeImage
Создает иконки приложения, в том числе для системного лотка (Windows), дока (macOS), используя файлы 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:
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:
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.
On Windows, you can also load ICO
icons from file paths. For best visual quality, we recommend including at least the following sizes:
- Мелкие значки
- 16x16 (100% DPI scale)
- 20x20 (125% DPI scale)
- 24x24 (150% DPI scale)
- 32x32 (200% DPI scale)
- Большие значки
- 32x32 (100% DPI scale)
- 40x40 (125% DPI scale)
- 48x48 (150% DPI scale)
- 64x64 (200% DPI scale)
- 256x256
Check the Icon Scaling section in the Windows App Icon Construction reference.
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
const { Tray } = require('electron')
const appTray = new Tray('/Users/somebody/images/icon.png')
The following suffixes for DPI are also supported:
@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. Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.
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 - path to a file that we intend to construct a thumbnail out of.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: The Windows implementation will ignore size.height
and scale the height according to size.width
.
nativeImage.createFromPath(path)
path
string - path to a file that we intend to construct an image out of.
Возвращает NativeImage
Создает новый экземпляр NativeImage
из файла, расположенного по адресу path
. Этот метод возвращает пустое изображение, если путь path
не существует, не может быть прочитан или является некорректным.
const { nativeImage } = require('electron')
const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)
nativeImage.createFromBitmap(buffer, options)
buffer
Buffer
Возвращает NativeImage
Creates a new NativeImage
instance from buffer
that contains the raw bitmap pixel data returned by toBitmap()
. The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])
buffer
Buffer
Возвращает NativeImage
Создает новый NativeImage
из buffer
. Tries to decode as PNG or JPEG first.
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
stringhslShift
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]
(saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0,5 = оставить без изменений. 1 = fully saturate the image.hsl_shift[2]
(lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 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
Встроенная упаковка изображений, таких как область уведомлений, док-станция и значки приложений.
Process: Main, Renderer
This class is not exported from the 'electron'
module. Он доступен только в качестве возвращаемого значения других методов в Electron API.
Методы экземпляра
Для экземпляров класса NativeImage
доступны следующие методы:
image.toPNG([options])
Возвращает Buffer
- A Buffer, который содержит закодированные данные изображения PNG
.
image.toJPEG(quality)
quality
Integer - Качество От 0 до 100.
Возвращает Buffer
- A Buffer, который содержит закодированные данные изображения JPEG
.
image.toBitmap([options])
Возвращает Buffer
- Buffer, который содержит копию сырых данных растровых пикселей изображения.
image.toDataURL([options])
History
Version(s) | Changes |
---|---|
None |
|
Returns string
- The Data URL of the image.
image.getBitmap([options])
Возвращает Buffer
- Buffer, который содержит сырые данные растровых пикселей изображения.
The difference between getBitmap()
and toBitmap()
is that getBitmap()
does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed.
image.getNativeHandle()
macOS
Возвращает Buffer
- Buffer в котором хранится указатель C на базовый собственный дескриптор изображения. On macOS, a pointer to NSImage
instance is returned.
Обратите внимание, что возвращаемый указатель - это слабый указатель на исходное изображение, а не на копию, поэтому вы должны убедиться, что связанный с ним экземпляр NativeImage
находится рядом.
image.isEmpty()
Возвращает boolean
- признак того что изображение пустое.
image.getSize([scaleFactor])
scaleFactor
Number (optional) - Defaults to 1.0.
Возвращает Size.
If scaleFactor
is passed, this will return the size corresponding to the image representation most closely matching the passed value.
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)
Возвращает NativeImage
- измененый размер изображения.
Если указаны только height
или width
, то текущее соотношение сторон будет сохранено в изображении.
image.getAspectRatio([scaleFactor])
scaleFactor
Number (optional) - Defaults to 1.0.
Returns Number
- The image's aspect ratio (width divided by height).
If scaleFactor
is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()
Returns Number[]
- An array of all scale factors corresponding to representations for a given NativeImage
.
image.addRepresentation(options)
Add an image representation for a specific scale factor. This can be used to programmatically add different scale factor representations to an image. This can be called on empty images.