nativeImage
Cria ícones de bandeija, dock e aplicações usando arquivos PNG ou JPG.
In Electron, for the APIs that take images, you can pass either file paths or NativeImage
instances. An empty image will be used when null
is passed.
Por exemplo, quando for criar uma bandeija ou designar um ícone para uma janela, você pode passar um caminho de arquivo de imagem com 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)
Formatos Suportados
Currently PNG
and JPEG
image formats are supported. PNG
is recommended because of its support for transparency and lossless compression.
On Windows, you can also load ICO
icons from file paths. For best visual quality, it is recommended to include at least the following sizes in the:
- Ícone pequeno
- 16x16 (com escala de DPI com 100%)
- 20x20 (com escala de DPI com 125%)
- 24x24 (com escala de DPI com 150%)
- 32x32 (com escala de DPI com 200%)
- Ícone grande
- 32x32 (com escala de DPI com 100%)
- 40x40 (com escala de DPI com 150%)
- 48x48 (com escala de DPI com 150%)
- 64x64 (com escala de DPI com 200%)
- 256x256
Confira a seção Size requirements nesse artigo.
Imagem em Alta Resolução
Em plataformas que possuem suporte para high-DPI como a tela Retina da Apple, você pode acrescentar @2x
depois do nome base da imagem para marcar-la como imagem de alta resolução.
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.
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. Como por exemplo:
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)
The following suffixes for DPI are also supported:
@1x
@1.25x
@1.33x
@1.4x
@1.5x
@1.8x
@2x
@2.5x
@3x
@4x
@5x
Modelo de Imagem
Template images consist of black and an alpha channel. Imagens padrão não são destinadas a serem usadas sozinhas, e geralmente são acompanhadas por outros conteúdos para criar a aparência final desejada.
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.
Nota: Imagens padrão são suportadas somente no macOS.
To mark an image as a template image, its filename should end with the word Template
. Como por exemplo:
xxxTemplate.png
xxxTemplate@2x.png
Métodos
O módulo nativeImage
possui os seguintes métodos, todos os quais retornam uma instância da classe NativeImage
:
nativeImage.createEmpty()
Retorna NativeImage
Cria uma instância NativeImage
vazia.
nativeImage.createThumbnailFromPath(path, size)
macOS Windows
path
string - path to a file that we intend to construct a thumbnail out of.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: The Windows implementation will ignore size.height
and scale the height according to size.width
.
nativeImage.createFromPath(path)
path
string
Retorna NativeImage
Cria uma nova instância NativeImage
de um arquivo localizado em path
. Esse método retorna uma imagem vazia se path
não existir, não poder ser lido, ou não ser uma imagem válida.
const nativeImage = require('electron').nativeImage
const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)
nativeImage.createFromBitmap(buffer, options)
buffer
Buffer
Retorna 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- Objeto
options
(opcional)width
Integer (opicional) - Necessário para buffers de bitmap.height
Integer (opicional) - Necessário para buffers de bitmap.scaleFactor
Number (optional) - Defaults to 1.0.
Retorna NativeImage
Cria uma nova instância NativeImage
a partir do buffer
. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)
dataURL
string
Retorna NativeImage
Cria uma nova instância NativeImage
a partir do dataURL
.
nativeImage.createFromNamedImage(imageName[, hslShift])
macOS
imageName
stringhslShift
number[] (optional)
Retorna NativeImage
Cria uma nova instância de NativeImage
a partir de NSImage o qual direciona para o dado nome da Imagem. Veja System Icons
para uma lista dos possíveis valores.
O hslShift
é aplicado à imagem com as seguintes regras:
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).
Isso significa que [-1, 0, 1]
irá deixar a imagem totalmente branca e [-1, 1, 0]
irá deixar a imagem totalmente preta.
In some cases, the NSImageName
doesn't match its string representation; one example of this is NSFolderImageName
, whose string representation would actually be NSFolder
. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:
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.
Class: NativeImage
Natively wrap images such as tray, dock, and application icons.
Process: Main, Renderer
This class is not exported from the 'electron'
module. Ele é somente disponibilizado como um valor de retorno de outros métodos na API Electron.
Métodos de Instância
Os seguintes métodos estão disponíveis nas instâncias da classe NativeImage
:
image.toPNG([options])
- Objeto
options
(opcional)scaleFactor
Number (optional) - Defaults to 1.0.
Retorna Buffer
- Um Buffer que contém os dados codificados de PNG
da imagem.
image.toJPEG(quality)
quality
Integer - Between 0 - 100.
Retorna Buffer
- Um Buffer que contém os dados codificados de JPG
da imagem.
image.toBitmap([options])
- Objeto
options
(opcional)scaleFactor
Number (optional) - Defaults to 1.0.
Retorna Buffer
- Um Buffer que contém uma copia dos dados de bitmap crus (sem alterações) da imagem.
image.toDataURL([options])
- Objeto
options
(opcional)scaleFactor
Number (optional) - Defaults to 1.0.
Retorna string
- Os dados de URL da imagem.
image.getBitmap([options])
- Objeto
options
(opcional)scaleFactor
Number (optional) - Defaults to 1.0.
Retorna Buffer
- Um Buffer que contém os dados de bitmap crus (sem alterações) da imagem.
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()
no macOS
Returns Buffer
- A Buffer that stores C pointer to underlying native handle of the image. On macOS, a pointer to NSImage
instance would be returned.
Perceba que o ponteiro retornado é um ponteiro fraco para a imagem nativa subjacente invés de uma cópia, então você deve se certificar de que a instância nativeImage
esteja próxima.
image.isEmpty()
Returns boolean
- Whether the image is empty.
image.getSize([scaleFactor])
scaleFactor
Number (optional) - Defaults to 1.0.
Retorna 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
Marca a imagem como uma imagem padrão.
image.isTemplateImage()
Retorna boolean
- sendo a imagem uma imagem padrão ou não.
image.crop(rect)
rect
Rectangle - A área da imagem a ser cortada.
Retorna NativeImage
- A imagem cortada.
image.resize(options)
Retorna NativeImage
- A imagem redimensionada.
Se apenas o height
ou o width
forem definidos então a atual proporção de tela da imagem será preservada na imagem redimensionada.
image.getAspectRatio([scaleFactor])
scaleFactor
Number (optional) - Defaults to 1.0.
Retorna Number
- A proporção de tela da imagem.
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 explicitly add different scale factor representations to an image. This can be called on empty images.
Propriedades da Instância
nativeImage.isMacTemplateImage
no macOS
A boolean
property that determines whether the image is considered a template image.
Please note that this property only has an effect on macOS.