Aller au contenu principal

nativeImage

Créez des icônes pour les applications, barre de tâches et barre d'état en utilisant des fichiers PNG ou JPG.

Processus: Main, Renderer

[!IMPORTANT] Si vous voulez appeler cette API à partir d'un processus de rendu avec l'isolation du contexte activée, placez l'appel API dans votre script de préchargement et exposez-le en utilisant l'API contextBridge.

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

Formats supportés​

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

Sous Windows, vous pouvez également charger les icônes ICO à partir de chemins de fichier. For best visual quality, we recommend including at least the following sizes:

  • Petite icône
    • 16x16 (100% DPI scale)
    • 20x20 (125% DPI scale)
    • 24x24 (150% DPI scale)
    • 32x32 (200% DPI scale)
  • Grande icône
    • 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.

note

Les métadonnées EXIF ne sont actuellement pas prises en charge et ne seront donc pas prises en compte lors de l'encodage et du décodage d'images .

Images à haute résolution​

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. Par exemple :

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

const appTray = new Tray('/Users/somebody/images/icon.png')

Les suffixes suivants pour le DPI sont également pris en charge :

  • @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. Elles ne sont pas destinées à être utilisées comme des images autonomes mais sont généralement mélangées avec d'autres contenus pour créer l'apparence finale désirée.

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éthodes​

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

nativeImage.createEmpty()​

Retourne NativeImage

Crée une instance NativeImage vide.

nativeImage.createThumbnailFromPath(path, size) macOS Windows​

  • path string - chemin vers le fichier à partir duquel nous souhaitons construire une miniature.
  • 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.

Retourne 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
  • Objet options
    • width Integer
    • height Integer
    • scaleFactor Number (facultatif) - 1.0 par défaut.

Retourne NativeImage

Crée une nouvelle instance de NativeImage à partir de buffer qui contient les données brutes en pixel de la bitmap retournées par toBitmap(). Le format spécifique dépend de la plate-forme.

nativeImage.createFromBuffer(buffer[, options])​

  • buffer Buffer
  • options Object (facultatif)
    • width Integer (facultatif) - Requis pour les buffers de bitmap.
    • height Integer (facultatif) - Requis pour les buffers de bitmap.
    • scaleFactor Number (facultatif) - 1.0 par défaut.

Retourne NativeImage

Crée une nouvelle instance NativeImage à partir de buffer. Essaie de décoder d'abord en tant qu PNG ou JPEG.

nativeImage.createFromDataURL(dataURL)​

  • dataURL string

Retourne NativeImage

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

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

  • imageName string
  • hslShift number[] (facultatif)

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

Le hslShift est appliqué à l'image avec les règles suivantes :

  • 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) : Un décalage de saturation pour l'image, avec les valeurs de clés suivantes : 0 = supprime toute la couleur,. 0.5 = laisse inchangé et 1 = saturation complète de l'image.
  • hsl_shift[2] (luminositée) Décalage de luminosité pour l'image, avec le valeurs clés suivantes : 0 = supprime toute luminosité (rendre tous les pixels noirs). 0.5 = laisse inchangé et 1 = pleine luminosité (rendre tous les pixels blancs).

Cela signifie que pour[-1, 0, 1] le résultat sera une image complètement blanche et que pour [-1, 1, 0] une image complètement noire.

Dans certains cas, le NSImageName ne correspond pas à sa représentation en string ; un exemple est NSFolderImageName, dont la string la représentant serait en fait NSFolder. Par conséquent, vous devrez déterminer la bonne représentation de votre image avant de la passer. Cela peut être fait avec les éléments suivants :

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.

Classe : NativeImage​

Encapsule nativement des images telles que des icônes d'application, des barres de tâches ou d'états.

Process: Main, Renderer
This class is not exported from the 'electron' module. Elle n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.

Méthodes d’instance​

Les méthodes suivants sont disponibles pour les instances de NativeImage :

image.toPNG([options])​

  • options Object (facultatif)
    • scaleFactor Number (facultatif) - 1.0 par défaut.

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

image.toJPEG(quality)​

  • qualité Entier - Entre 0 - 100.

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

image.toBitmap([options])​

  • options Object (facultatif)
    • scaleFactor Number (facultatif) - 1.0 par défaut.

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

image.toDataURL([options])​

History
  • options Object (facultatif)
    • scaleFactor Number (facultatif) - 1.0 par défaut.

Returns string - The Data URL of the image.

image.getBitmap([options]) __ obsolète​

  • options Object (facultatif)
    • scaleFactor Number (facultatif) - 1.0 par défaut.

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.

Note que le pointeur retourné est un pointeur faible vers l'image native sous-jacente au lieu d'une copie, donc vous devez vous assurer que l'instance associée nativeImage est conservée.

image.isEmpty()​

Retourne boolean - Si l'image est vide.

image.getSize([scaleFactor])​

  • scaleFactor Number (facultatif) - Par défaut à 1.0.

Returns Size.

Si scaleFactor est fournit, la méthode retournera la taille correspondant à la représentation d'image la plus proche de la valeur passée.

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.

Retourne NativeImage - L'image recadrée.

image.resize(options)​

  • Objet options
    • width Integer (facultatif) - Largeur de l'image par défaut.
    • height Integer (facultatif) - Hauteur de l'image par défaut.
    • Qualité string (facultatif) - La qualité souhaitée de l'image de retaille. Les valeurs possibles sont good, better ou best. La valeur par défaut est meilleur. Ces valeurs expriment un compromis qualité/vitesse souhaité. Ils sont traduits en une méthode spécifique à l'algorithme dépendant des capacités (CPU, GPU) de la plate-forme sous-jacente. Il est possible que les trois méthodes soient mappées au même algorithme sur une plate-forme donnée.

Retourne NativeImage - L'image redimensionnée.

Si seulement la hauteur ou la largeur sont spécifiées, alors le ratio d'aspect actuel sera préservé dans l'image redimensionnée.

image.getAspectRatio([scaleFactor])​

  • scaleFactor Number (facultatif) - Par défaut 1.0.

Returns Number - The image's aspect ratio (width divided by height).

Si scaleFactor est passé, cela retournera le format d'image correspondant représentation d'image la plus proche de la valeur passée.

image.getScaleFactors()​

Returns Number[] - An array of all scale factors corresponding to representations for a given NativeImage.

image.addRepresentation(options)​

  • Objet options
    • scaleFactor Number (facultatif) - Facteur d'échelle .
    • largeur Integer (facultatif) - 0 par défaut. Requis si un Buffer bitmap est spécifié pour buffer.
    • height Integer (facultatif) - 0 par défaut. Requis si un Buffer bitmap est spécifié pour buffer.
    • tampon Buffer (facultatif) - Le tampon contenant les données de l'image brute.
    • dataURL string (optionelle) - URL de données contenant soit une image PNG encodée en base 64 ou une image JPEG.

Ajoute une représentation d'image pour un facteur d'échelle spécifique. This can be used to programmatically add different scale factor representations to an image. Ceci peut être exécuté sur des images vides.

Propriétés d'instance​

nativeImage.isMacTemplateImage macOS​

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

Veuillez noter que cette propriété n'a qu'un effet sur macOS.