nativeImage
Créez des icônes pour les applications, barre de tâches et barre d'état en utilisant des fichiers PNG ou JPG.
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, size)
macOS Windows
path
string - chemin vers le fichier à partir duquel nous souhaitons construire une miniature.size
Taille - la largeur et la hauteur souhaitées (nombres positifs) de la miniature.
Retourne une Promise<NativeImage>
- résolue avec l'aperçu miniature du fichier et qui est une NativeImage.
Note: L’implémentation Windows ignorera size.height
et ajustera la hauteur en fonction de size.width
.
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
Integerheight
IntegerscaleFactor
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
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
stringhslShift
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])
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])
Retourne Buffer
- Un tampon qui contient une copie des données du pixel brut bitmap de l'image.
image.toDataURL([options])
Retourne string
- L'URL des données de l'image.
image.getBitmap([options])
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 sontgood
,better
oubest
. La valeur par défaut estmeilleur
. 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é pourbuffer
.height
Integer (facultatif) - 0 par défaut. Requis si un Buffer bitmap est spécifié pourbuffer
.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.