Saltar al contenido principal

nativeImage

Crea iconos de bandeja, base y aplicación usando archivos PNG o JPG.

Proceso: Main, Renderer

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 Soportados​

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

En Windows, puedes leer iconos ICO desde rutas de archivos. For best visual quality, we recommend including at least the following sizes:

  • Ícono pequeño
    • 16x16 (100% DPI scale)
    • 20x20 (125% DPI scale)
    • 24x24 (150% DPI scale)
    • 32x32 (200% DPI scale)
  • Ícono Grande
    • 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.

::: Nota

Los metadatos EXIF no están soportados actualmente y no serán tenidos en cuenta durante la codificación y decodificación de imágenes.

:::

Imagen de alta resolución​

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. Por ejemplo:

images/
├── icon.png
├── icon@2x.png
└── icon@3x.png
Main Process
const { Tray } = require('electron')
const appTray = new Tray('/Users/somebody/images/icon.png')

Los siguientes sufijos para DPI son soportados:

  • @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. Las imágenes de plantilla no están destinadas a ser utilizadas como imágenes independientes y son generalmente mezcladas con otro contenido para crear la apariencia final deseada.

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()​

Devuelve NativeImage

Crea una instancia vacía 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.

Devuelve NativeImage

Crea una instancia NativeImage desde un archivo ubicado en path. Este método devuelve una imagen si la path no existe, o si no puede ser leída o si la imagen no es válida.

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
    • alto Integer
    • scaleFactor Number (optional) - Defaults to 1.0.

Devuelve 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 (opcional)
    • width Integer (opcional) - Requerido para búferes de bipmaps.
    • height Entero (opcional) - Necesario para los búferes de mapa de bits.
    • scaleFactor Number (optional) - Defaults to 1.0.

Devuelve NativeImage

Crea una nueva instancia NativeImage desde buffer. Tries to decode as PNG or JPEG first.

nativeImage.createFromDataURL(dataURL)​

  • dataURL cadena

Devuelve NativeImage

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

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

  • imageName string
  • hslShift number[] (opcional)

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

El hslShift se aplica a la imagen con las siguientes reglas:

  • 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 = Dejar sin cambios. 1 = fully saturate the image.
  • hsl_shift[2] (luminosidad): Un cambio en la luminosidad para la imagen, con los siguientes valores claves: 0 = elimina toda la luminosidad (hace que todos los pixeles sean negros). 0.5 = Dejar sin cambios. 1 = Luminosidad total (hace que todos los píxeles sean blancos).

Esto significa que [-1, 0, 1] hará la imagen completamente blanca y [-1, 1, 0] la hará completamente negra.

En algunos casos, el NSImageName no coincide con su cadena de representación; un ejemplo de esto es NSFolderImageName, cuya cadena de representación en realidad sería NSFolder. Por lo tanto, necesitar determinar la cadena de representación correcta para su imagen antes de pasarla. Esto puede hacer con lo siguiente:

echo -e '#import <Cocoa/Cocoa.h>\nint main() { NSLog(@"%@", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test

donde SYSTEM_IMAGE_NAME debe ser reemplazado con cualquier valor de this list.

Clase: NativeImage​

Envuelve nativamente imágenes como la bandeja, el muelle y los íconos de las aplicaciones.

Proceso: Main, Renderer
Esta clase no es exportada desde el módulo 'electron'. Sólo está disponible como un valor de retorno de otros métodos en la API de Electron.

Métodos de Instancia​

Los siguientes métodos están disponibles para las distancias de la clase NativeImage:

image.toPNG([options])​

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

Devuelve Buffer - Un Buffer que contiene la información codificada de la imagen PNG.

image.toJPEG(quality)​

  • quality Integer - Entre 0 - 100.

Devuelve Buffer - Un Bufferque contiene la información codificada de la imagen JPEG.

image.toBitmap([options])​

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

Devuelve Buffer - Un Buffer que contiene una copia de la información sin procesar de pixeles del mapa de bits de la imagen.

image.toDataURL([options])​

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

Returns string - The Data URL of the image.

image.getBitmap([options])​

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

Devuelve Buffer - Un Buffer que contiene la información sin procesar de pixeles del mapa de bits de la imagen.

La diferencia entre getBitmap() y toBitmap() es que getBitmap() no copia los datos bitmap, por lo que debe utilizar inmediatamente el Búfer devuelto en el ciclo del evento actual; de lo contrario, los datos podrían modificarse o destruirse.

image.getNativeHandle() macOS​

Devuelve Buffer - Un Buffer que almacena el puntero C en el controlador nativo subyacente de la imagen. On macOS, a pointer to NSImage instance is returned.

Observe que el puntero devuelto es un puntero debil a la imagen nativa subyacente en lugar de una copia. Por lo tanto, debe asegurarse que la instancia asociada nativeImage se encuentre cerca.

image.isEmpty()​

Devuelve boolean - Si la imagen está vacía.

image.getSize([scaleFactor])​

  • scaleFactor Number (optional) - Defaults to 1.0.

Devuelve 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 booleano

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 - El área de la imagen para ser recortada.

Devuelve NativeImage - La imagen recortada.

image.resize(options)​

  • options Object
    • width Integer (opcional) - Por defecto es el ancho de la imagen.
    • height Entero (opcional) - El valor predeterminado es la altura de la imagen.
    • quality string (opcional) - La calidad deseada para el cambio de tamaño de imagen. Possible values include good, better, or best. Por defecto es best. Estos valores expresan una compensación de calidad/velocidad deseada. Son traducidas dentro de un método de algoritmo específico que depende de las capacidades (CPU, GPU) de la plataforma subyacente. It is possible for all three methods to be mapped to the same algorithm on a given platform.

Devuelve NativeImage - La imagen redimensionada.

Si solo la height o la width son especificadas, entonces la relación de aspecto actual se conservará en la imagen 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 Entero (opcional) - Por defecto es 0. Required if a bitmap buffer is specified as buffer.
    • height Entero (opcional) - Por defecto es 0. Required if a bitmap buffer is specified as buffer.
    • buffer Buffer (opcional) - El buffer que contiene los datos de la imagen sin procesar.
    • 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.

Propiedades de la instancia​

nativeImage.isMacTemplateImage macOS​

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

Por favor note que esta propiedad solo tiene efecto en macOS.