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

Dans Electron, pour les API d'acquisition d'images, vous pouvez passer des chemins de fichiers ou des instances de type NativeImage. Une image vide sera utilisée lorsque null sera transmise.

Par exemple, lors de la création d'une barre d'état ou de la configuration d'une icône de fenêtre, vous pouvez passer le chemin d'un fichier image de la façon sous la forme d'une string:

const { BrowserWindow, Tray } = require('electron')

const appIcon = new Tray('/Users/somebody/images/icon.png')
const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })
console.log(appIcon, win)

Ou récupérer l'image à partir du presse-papiers, renvoyant une NativeImage:

const { clipboard, Tray } = require('electron')
const image = clipboard.readImage()
const appIcon = new Tray(image)
console.log(appIcon)

Formats supportés​

Actuellement, les formats d'image PNG et JPEG sont pris en charge. PNG est recommandé en raison de son support de la transparence et de la compression sans perte.

Sous Windows, vous pouvez également charger les icônes ICO à partir de chemins de fichier. Pour une meilleure qualité visuelle , il est recommandé d'inclure au moins les tailles suivantes dans les :

  • 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

Consultez la section Taille requise dans cet article.

Images à haute résolution​

Sur les plates-formes prennant en charge les DPI élevés tels que les écrans Apple Retina, vous pouvez ajouter @2x après le nom du fichier de base de l'image pour le marquer comme image de haute résolution.

Par exemple, si icon.png est une image normale ayant une résolution standard, alors icon@2x.png sera traitée comme une image haute résolution ayant une densité DPI double.

Si vous voulez prendre en charge simultanément les écrans avec des densités DPI différentes, vous pouvez mettre des images de tailles différentes dans le même dossier et utiliser le nom de fichier sans le suffixe des DPI. Par exemple :

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

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

Image modèle​

Les image modèles sont constituées de noir et d'un canal alpha. 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.

Le cas le plus courant est l''utilisation d'images modèles pour une icône de la barre de menus, pour qu'il puisse s'adapter aux barres de menu claires et sombres.

Remarque : Les template d'image ne sont pas prise en charge que sur macOS.

Pour marquer une image comme image modèle, son nom de fichier doit être suffixé avec Template. Par exemple :

  • xxxTemplate.png
  • xxxTemplate@2x.png

Méthodes​

Le module nativeImage possède les méthodes suivantes, qui retournent toutes une instance de la classe NativeImage:

nativeImage.createEmpty()​

Retourne NativeImage

Crée une instance NativeImage vide.

nativeImage.createThumbnailFromPath(path, maxSize) macOS Windows​

  • path string - chemin vers le fichier à partir duquel nous souhaitons construire une miniature.
  • maxSize Taille - Largeur et hauteur maximales (nombres positifs) de la vignette retournée. L'implémentation de Windows ignorera maxSize.height et redimensionnera la hauteur selon maxSize.width.

Retourne une Promise<NativeImage> - résolue avec l'aperçu miniature du fichier et qui est une NativeImage.

nativeImage.createFromPath(path)​

  • path string

Retourne NativeImage

Crée une nouvelle instance de NativeImage à partir d'un fichier localisé par le chemin path. Cette méthode retournera une image vide si le path n'existe pas, ne peut pas être lu, ou n'est pas une image valide.

const nativeImage = require('electron').nativeImage

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

Crée une nouvelle instance NativeImage à partir de dataURL.

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

  • imageName string
  • hslShift number[] (facultatif)

Retourne NativeImage

Crée une nouvelle instance NativeImage à partir de la NSImage qui correspond au nom d'image donné. Voir System Icons pour une liste de valeurs possibles.

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

  • hsl_shift[0] (teinte) : Valeur absolue de la teinte pour l'image - 0 et 1 donnant 0 et 360 sur la roue couleur des teintes (rouge).
  • 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

où SYSTEM_IMAGE_NAME doit être remplacé par n'importe quelle valeur de cette liste.

Classe : NativeImage​

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

Processus : Principal, Rendu
Cette classe n'est pas exportée depuis le module 'electron'. 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.

Retourne Buffer - Un tampon qui contient les données encodées PNG de l'image.

image.toJPEG(quality)​

  • qualité Entier - Entre 0 - 100.

Retourne Buffer - Un tampon qui contient les données encodées en JPEG de l'image.

image.toBitmap([options])​

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

Retourne Buffer - Un tampon qui contient une copie des données du pixel brut bitmap de l'image.

image.toDataURL([options])​

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

Retourne string - L'URL des données de l'image.

image.getBitmap([options])​

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

Retourne Buffer - Un tampon qui contient les données brutes des pixels bitmap de l'image.

La différence entre getBitmap() et toBitmap() est que getBitmap() ne copie pas les données bitmap, donc vous devez utiliser le Buffer retourné immédiatement durant le tick actuel de la boucle d'événement; sinon les données pourraient être modifiées ou détruites.

image.getNativeHandle() macOS​

Retourne Buffer - Un tampon qui stocke le pointeur C sur la gestion native sous-jacente de l'image . Sur macOS, un pointeur vers NSImage serait retourné.

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.

Retourne 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

Marque l'image comme une image de modèle.

image.isTemplateImage()​

Retourne boolean - Si l'image est une image de modèle.

image.crop(rect)​

  • rect Rectangle - L'aire de l'image à recadrer.

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.

Retourne Number - Le ratio d'aspect de l'image.

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

Retourne Number[] - Un tableau de tous les facteurs d'échelle correspondant aux représentations pour une nativeImage donnée.

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. Ceci peut être utilisé pour ajouter explicitement différentes représentations de facteur d'échelle à une image. Ceci peut être exécuté sur des images vides.

Propriétés d'instance​

nativeImage.isMacTemplateImage macOS​

Une propriété boolean qui détermine si l'image est considérée comme une image de modèle.

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