nativeImage
Создает иконки приложения, в том числе для системного лотка (Windows), дока (macOS), используя файлы PNG и 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.
Например, при создании вкладки в области уведомлений или установке иконки окна можно задать путь к файлу изображения в виде 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)
Поддерживаемые форматы
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:
- Мелкие значки
- 16x16 (100% DPI scale)
- 20x20 (125% DPI scale)
- 24x24 (150% DPI scale)
- 32x32 (200% DPI scale)
- Большие значки
- 32x32 (100% DPI scale)
- 40x40 (125% DPI scale)
- 48x48 (150% DPI scale)
- 64x64 (200% DPI scale)
- 256x256
Проверьте раздел Size requirements в этой статье.
Изображения с высоким разрешением
На платформах, имеющих поддержку высокого DPI, таких как дисплеи Apple Retina, вы можете добавить @2x
после имени файла изображения, чтобы пометить его как изображение с высоким разрешением.
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. Например:
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
Шаблон изображения
Template images consist of black and an alpha channel. Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.
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.
Внимание: Шаблонные изображения поддерживаются только на macOS.
To mark an image as a template image, its filename should end with the word Template
. Например:
xxxTemplate.png
xxxTemplate@2x.png
Методы
Модуль nativeImage
имеет следующие методы, все из которых возвращают экземпляр класса NativeImage
:
nativeImage.createEmpty()
Возвращает NativeImage
Создает пустой экземпляр NativeImage
.
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
Возвращает NativeImage
Создает новый экземпляр NativeImage
из файла, расположенного по адресу path
. Этот метод возвращает пустое изображение, если путь path
не существует, не может быть прочитан или является некорректным.
const nativeImage = require('electron').nativeImage
const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)
nativeImage.createFromBitmap(buffer, options)
buffer
Buffer
Возвращает 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
Возвращает NativeImage
Создает новый NativeImage
из buffer
. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)
dataURL
string
Возвращает NativeImage
Создает новый NativeImage
из dataURL
.
nativeImage.createFromNamedImage(imageName[, hslShift])
macOS
imageName
stringhslShift
number[] (опционально)
Возвращает NativeImage
Создает новый экземпляр NativeImage
из NSImage, который сопоставляется с заданным именем изображения. Смотрите System Icons
для получения списка возможных значений.
hslShift
применяется к изображению со следующими правилами:
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 = оставить без изменений. 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 = оставить без изменений. 1 = полная яркость (сделать все точки белыми).
Это означает, что [-1, 0, 1]
сделает изображение полностью белым, а [-1, 1, 0]
сделает изображение полностью чёрным.
В некоторых случаях NSImageName
не соответствует строковому представлению; одним из примеров может служить NSFolderImageName
, строковое представление которого будет NSFolder
. Поэтому вам нужно определить правильное представление строк для вашего изображения, перед тем как его передавать. Это можно сделать следующим образом:
echo -e '#import <Cocoa/Cocoa.h>\nint main() { NSLog(@"%@", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
где SYSTEM_IMAGE_NAME
следует заменить любым значением из этого списка.
Класс: NativeImage
Встроенная упаковка изображений, таких как область уведомлений, док-станция и значки приложений.
Process: Main, Renderer
This class is not exported from the 'electron'
module. Он доступен только в качестве возвращаемого значения других методов в Electron API.
Методы экземпляра
Для экземпляров класса NativeImage
доступны следующие методы:
image.toPNG([options])
Возвращает Buffer
- A Buffer, который содержит закодированные данные изображения PNG
.
image.toJPEG(quality)
quality
Integer - Качество От 0 до 100.
Возвращает Buffer
- A Buffer, который содержит закодированные данные изображения JPEG
.
image.toBitmap([options])
Возвращает Buffer
- Buffer, который содержит копию сырых данных растровых пикселей изображения.
image.toDataURL([options])
Возвращает string
- данные URL изображения.
image.getBitmap([options])
Возвращает Buffer
- Buffer, который содержит сырые данные растровых пикселей изображения.
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
Возвращает Buffer
- Buffer в котором хранится указатель C на базовый собственный дескриптор изображения. На macOS возвращается указатель на экземпляр NSImage
.
Обратите внимание, что возвращаемый указатель - это слабый указатель на исходное изображение, а не на копию, поэтому вы должны убедиться, что связанный с ним экземпляр NativeImage
находится рядом.
image.isEmpty()
Возвращает boolean
- признак того что изображение пустое.
image.getSize([scaleFactor])
scaleFactor
Number (optional) - Defaults to 1.0.
Возвращает 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
Помечает изображение как шаблон изображения.
image.isTemplateImage()
Возвращает boolean
- признак того что изображение является шаблоном.
image.crop(rect)
rect
Rectangle - область изображения до которой нужно обрезать.
Возвращает NativeImage
- обрезанное изображение.
image.resize(options)
Возвращает NativeImage
- измененый размер изображения.
Если указаны только height
или width
, то текущее соотношение сторон будет сохранено в изображении.
image.getAspectRatio([scaleFactor])
scaleFactor
Number (optional) - Defaults to 1.0.
Возвращает Number
- пропорции изображения.
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.
Свойства экземпляра
nativeImage.isMacTemplateImage
macOS
Свойство boolean
определяет, считается ли изображение шаблоном.
Пожалуйста, обратите внимание, что это свойство влияет только на macOS.