nativeImage
Créez des icônes de bac, d'ancrage et d'application à l'aide de fichiers PNG ou JPG.
Dans Electron, pour les API d'acquisition d'images, vous pouvez passer des chemins de fichiers ou des instances de tyipe NativeImage
. Une image vide sera utilisée lorsque null
sera transmise.
For example, when creating a tray or setting a window's icon, you can pass an image file path as a 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)
Or read the image from the clipboard, which returns a 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
On platforms that have high-DPI support such as Apple Retina displays, you can append @2x
after image's base filename to mark it as a 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 DPI density.
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
Template Image
Les templates d'image 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.
The most common case is to use template images for a menu bar icon, so it can adapt to both light and dark menu bars.
Remarque : Les template d'image ne sont pas prise en charge que sur macOS.
To mark an image as a template image, its filename should end with the word Template
. Par exemple :
xxxTemplate.png
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, maxSize)
macOS Windows
path
string - path to a file that we intend to construct a thumbnail out of.maxSize
Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignoremaxSize.height
and scale the height according tomaxSize.width
.
Returns Promise<NativeImage>
- fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)
path
string
Retourne NativeImage
Creates a new NativeImage
instance from a file 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').nativeImage
const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)
nativeImage.createFromBitmap(buffer, options)
buffer
Buffer- Objet
options
width
Integerheight
IntegerscaleFactor
Double (facultatif) - 1.0 par défaut.
Retourne 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
Retourne NativeImage
Crée une nouvelle instance NativeImage
à partir de buffer
. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)
dataURL
string
Retourne NativeImage
Crée une nouvelle instance NativeImage
à partir de dataURL
.
nativeImage.createFromNamedImage(imageName[, hslShift])
macOS
imageName
stringhslShift
number[] (optional)
Retourne NativeImage
Creates a new NativeImage
instance from the NSImage that maps to the given image name. See System Icons
for a list of possible values.
The hslShift
is applied to the image with the following rules:
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 = leave unchanged. 1 = fully saturate the image.hsl_shift[2]
(lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 0.5 = leave unchanged. 1 = full lightness (make all pixels white).
This means that [-1, 0, 1]
will make the image completely white and [-1, 1, 0]
will make the image completely black.
In some cases, the NSImageName
doesn't match its string representation; one example of this is NSFolderImageName
, whose string representation would actually be 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
Natively wrap images such as tray, dock, and application icons.
Process: Main, Renderer
This class is not exported from the 'electron'
module. Il n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.
Méthodes d’instance
The following methods are available on instances of the NativeImage
class:
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.
The difference between getBitmap()
and toBitmap()
is that getBitmap()
does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed.
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
Double (facultatif) - 1.0 par défaut.
Retourne 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
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 (optional) - Defaults to the image's width.height
Integer (facultatif) - La 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é. They are translated into an algorithm-specific method that depends on the capabilities (CPU, GPU) of the underlying platform. It is possible for all three methods to be mapped to the same algorithm on a given platform.
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
Double (facultatif) - 1.0 par défaut.
Retourne Float
- Le ratio d'aspect de l'image.
If scaleFactor
is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()
Returns Float[]
- An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)
- Objet
options
scaleFactor
Double - The scale factor to add the image representation for.largeur
Integer (facultatif) - 0 par défaut. Required if a bitmap buffer is specified asbuffer
.height
Integer (facultatif) - 0 par défaut. Required if a bitmap buffer is specified asbuffer
.tampon
Buffer (facultatif) - Le tampon contenant les données de l'image brute.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 explicitly add different scale factor representations to an image. This can be called on empty images.
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.