Ir para o conteúdo principal

nativeImage

Cria ícones de bandeija, dock e aplicações usando arquivos PNG ou 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 })

Formatos Suportados​

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:

  • Ícone pequeno
    • 16x16 (com escala de DPI com 100%)
    • 20x20 (com escala de DPI com 125%)
    • 24x24 (com escala de DPI com 150%)
    • 32x32 (com escala de DPI com 200%)
  • Ícone grande
    • 32x32 (com escala de DPI com 100%)
    • 40x40 (com escala de DPI com 150%)
    • 48x48 (com escala de DPI com 150%)
    • 64x64 (com escala de DPI com 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.

Imagem em Alta Resolução​

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. Como por exemplo:

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. Imagens padrão não são destinadas a serem usadas sozinhas, e geralmente são acompanhadas por outros conteúdos para criar a aparência final desejada.

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

Métodos​

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

nativeImage.createEmpty()​

Retorna NativeImage

Cria uma instância NativeImage vazia.

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.

Retorna 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.

Retorna 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
  • Objeto options (opcional)
    • width Integer (opicional) - Necessário para buffers de bitmap.
    • height Integer (opicional) - Necessário para buffers de bitmap.
    • scaleFactor Number (optional) - Defaults to 1.0.

Retorna NativeImage

Cria uma nova instância NativeImage a partir do buffer. Tries to decode as PNG or JPEG first.

nativeImage.createFromDataURL(dataURL)​

  • dataURL string

Retorna NativeImage

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

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

  • imageName string
  • hslShift number[] (optional)

Retorna 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.

O hslShift é aplicado à imagem com as seguintes regras:

  • 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 = leave unchanged. 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 = leave unchanged. 1 = full lightness (make all pixels white).

Isso significa que [-1, 0, 1] irá deixar a imagem totalmente branca e [-1, 1, 0] irá deixar a imagem totalmente preta.

In some cases, the NSImageName doesn't match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:

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.

Class: NativeImage​

Natively wrap images such as tray, dock, and application icons.

Process: Main, Renderer
This class is not exported from the 'electron' module. Ele é somente disponibilizado como um valor de retorno de outros métodos na API Electron.

Métodos de Instância​

Os seguintes métodos estão disponíveis nas instâncias da classe NativeImage:

image.toPNG([options])​

  • Objeto options (opcional)
    • scaleFactor Number (optional) - Defaults to 1.0.

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

image.toJPEG(quality)​

  • quality Integer - Between 0 - 100.

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

image.toBitmap([options])​

  • Objeto options (opcional)
    • 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
  • Objeto options (opcional)
    • scaleFactor Number (optional) - Defaults to 1.0.

Returns string - The Data URL of the image.

image.getBitmap([options]) Deprecated​

  • Objeto options (opcional)
    • scaleFactor Number (optional) - Defaults to 1.0.

Legacy alias for image.toBitmap().

image.getNativeHandle() no 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.

Perceba que o ponteiro retornado é um ponteiro fraco para a imagem nativa subjacente invés de uma cópia, então você deve se certificar de que a instância nativeImage esteja próxima.

image.isEmpty()​

Returns boolean - Whether the image is empty.

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.

Retorna NativeImage - A imagem cortada.

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 (optional) - The desired quality of the resize image. Possible values include good, better, or best. O padrão é best. Esses valores apresentam a qualidade/velocidade de troca desejada. 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.

Retorna NativeImage - A imagem redimensionada.

Se apenas o height ou o width forem definidos então a atual proporção de tela da imagem será preservada na imagem redimensionada.

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) - Padrão sendo 0. Required if a bitmap buffer is specified as buffer.
    • height Integer (opcional) - Padrão sendo 0. Required if a bitmap buffer is specified as buffer.
    • buffer Buffer (opcional) - O buffer contendo os dados crus (sem alteração) da imagem.
    • 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.

Propriedades da Instância​

nativeImage.isMacTemplateImage no macOS​

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

Please note that this property only has an effect on macOS.