Перейти к основному содержанию

nativeImage

Создает иконки приложения, в том числе для системного лотка (Windows), дока (macOS), используя файлы PNG и JPG.

Process: Main, Renderer

[!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.

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.

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
Main Process
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] 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

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 (optional) - Defaults to 1.0.

Возвращает 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
  • options Object (опционально)
    • width Integer (опционально) - требуется для буферов растровых изображений.
    • height Integer (опционально) - требуется для буферов растровых изображений.
    • scaleFactor Number (optional) - Defaults to 1.0.

Возвращает 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 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] (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

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

Класс: NativeImage​

Встроенная упаковка изображений, таких как область уведомлений, док-станция и значки приложений.

Process: Main, Renderer
This class is not exported from the 'electron' module. Он доступен только в качестве возвращаемого значения других методов в Electron API.

Методы экземпляра​

Для экземпляров класса NativeImage доступны следующие методы:

image.toPNG([options])​

  • options Object (опционально)
    • scaleFactor Number (optional) - Defaults to 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 (optional) - Defaults to 1.0.

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

image.toDataURL([options])​

History
  • options Object (опционально)
    • scaleFactor Number (optional) - Defaults to 1.0.

Returns string - The Data URL of the image.

image.getBitmap([options]) Deprecated​

  • options Object (опционально)
    • scaleFactor Number (optional) - Defaults to 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. On macOS, a pointer to NSImage instance is returned.

Обратите внимание, что возвращаемый указатель - это слабый указатель на исходное изображение, а не на копию, поэтому вы должны убедиться, что связанный с ним экземпляр NativeImage находится рядом.

image.isEmpty()​

Возвращает boolean - признак того что изображение пустое.

image.getSize([scaleFactor])​

  • scaleFactor Number (optional) - Defaults to 1.0.

Returns 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 - The area of the image to crop.

Возвращает NativeImage - обрезанное изображение.

image.resize(options)​

  • options Object
    • width Integer (optional) - Defaults to the image's width.
    • height Integer (optional) - Defaults to the image's height.
    • quality string (опционально) - Желаемое качество изображения при изменения размера. Possible values include good, better, or best. The default is best. These values express a desired quality/speed tradeoff. They are translated into an algorithm-specific method that depends on the capabilities (CPU, GPU) of the underlying platform. It is possible for all three methods to be mapped to the same algorithm on a given platform.

Возвращает 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)​

  • options Object
    • scaleFactor Number (optional) - The scale factor to add the image representation for.
    • width Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.
    • height Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.
    • buffer Buffer (optional) - The buffer containing the raw image data.
    • dataURL string (optional) - The data URL containing either a base 64 encoded PNG or JPEG image.

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.

Свойства экземпляра​

nativeImage.isMacTemplateImage macOS​

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

Пожалуйста, обратите внимание, что это свойство влияет только на macOS.