nativeImage
Crea iconos de bandeja, base y aplicación usando archivos PNG o 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 })
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 [email protected] 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
├── [email protected]
└── [email protected]
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. [email protected]).
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
pathstring - path to a file that we intend to construct a thumbnail out of.sizeSize - 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.heightand scale the height according tosize.width.
nativeImage.createFromPath(path)
pathstring - path to a file that we intend to construct an image out of.
Devuelve 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)
bufferBuffer
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])
bufferBuffer
Devuelve NativeImage
Crea una nueva instancia NativeImage desde buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)
dataURLcadena
Devuelve NativeImage
Creates a new NativeImage instance from dataUrl, a base 64 encoded Data URL string.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOS
imageNamestringhslShiftnumber[] (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
where SYSTEM_IMAGE_NAME should be replaced with any value from this list.
Clase: NativeImage
Envuelve nativamente imágenes como la bandeja, el muelle y los íconos de las aplicaciones.
Process: Main, Renderer
This class is not exported from the 'electron' module. 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])
Returns Buffer - A Buffer that contains the image's PNG encoded data.
image.toJPEG(quality)
qualityInteger - Entre 0 - 100.
Returns Buffer - A Buffer that contains the image's JPEG encoded data.
image.toBitmap([options])
Returns Buffer - A Buffer that contains a copy of the image's raw bitmap pixel data.
image.toDataURL([options])
History
| Version(s) | Changes |
|---|---|
None |
|
Returns string - The Data URL of the image.
image.getBitmap([options]) Obsoleto
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.
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])
scaleFactorNumber (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)
optionbooleano
Marks the image as a macOS template image.
image.isTemplateImage()
Returns boolean - Whether the image is a macOS template image.
image.crop(rect)
rectRectangle - The area of the image to crop.
Devuelve NativeImage - La imagen recortada.
image.resize(options)
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])
scaleFactorNumber (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.
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.