nativeImage

Создание значков панели задач, док-станции и приложения с использованием файлов PNG или JPG.

Процесс: Основной, Рендеринг

В Electron для API, принимающих изображения, можно передавать пути к файлам или экземпляры NativeImage. Пустое изображение будет использовано при передаче null.

Например, при создании значка панели задач или установке значка окна можно передать путь к файлу изображения в качестве 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)

Или считать изображение из буфера обмена, что возвращает NativeImage:

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

Поддерживаемые форматы​

В настоящее время поддерживаются форматы изображений PNG и JPEG. Рекомендуется PNG из-за поддержки прозрачности и без потерь сжатия.

В Windows также можно загружать значки ICO из путей к файлам. Для наилучшего качества изображения рекомендуется включить следующие размеры в:

• Маленький значок
  • 16x16 (масштаб DPI 100%)
  • 20x20 (масштаб DPI 125%)
  • 24x24 (масштаб DPI 150%)
  • 32x32 (масштаб DPI 200%)
• Большой значок
  • 32x32 (масштаб DPI 100%)
  • 40x40 (масштаб DPI 125%)
  • 48x48 (масштаб DPI 150%)
  • 64x64 (масштаб DPI 200%)
  • 256x256

Проверьте раздел Требования к размеру в этой статье.

Изображение высокого разрешения​

На платформах с поддержкой высокого разрешения, таких как дисплеи Apple Retina, можно добавить @2x после базового имени файла изображения, чтобы отметить его как изображение высокого разрешения.

Например, если icon.png — обычное изображение стандартного разрешения, то icon@2x.png будет обрабатываться как изображение высокого разрешения с удвоенной плотностью DPI.

Если вы хотите одновременно поддерживать дисплеи с различной плотностью DPI, вы можете поместить изображения с разными размерами в одну папку и использовать имя файла без суффиксов DPI. Например:

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)

Также поддерживаются следующие суффиксы для DPI:

• @1x
• @1.25x
• @1.33x
• @1.4x
• @1.5x
• @1.8x
• @2x
• @2.5x
• @3x
• @4x
• @5x

Шаблонное изображение​

Шаблонные изображения состоят из черного цвета и альфа-канала. Шаблонные изображения не предназначены для использования в качестве самостоятельных изображений и обычно смешиваются с другими данными для создания желаемого конечного вида.

Наиболее распространённый случай — использование шаблонных изображений для значка строки меню, чтобы он мог адаптироваться к светлой и тёмной строке меню.

Примечание: Шаблонные изображения поддерживаются только в macOS.

Для маркировки изображения как шаблонного, имя файла должно заканчиваться словом Template. Например:

• xxxTemplate.png
• xxxTemplate@2x.png

Методы​

В модуле nativeImage имеются следующие методы, все из которых возвращают экземпляр класса NativeImage:

nativeImage.createEmpty()​

Возвращает NativeImage

Создаёт пустой экземпляр NativeImage.

nativeImage.createThumbnailFromPath(path, maxSize) macOS Windows​

• path строка - путь к файлу, из которого мы намерены создать миниатюру.
• maxSize Размер - максимальная ширина и высота (положительные числа), которые может иметь возвращаемая миниатюра. Реализация для Windows проигнорирует maxSize.height и масштабирует высоту в соответствии с maxSize.width.

Возвращает Promise<NativeImage> - заполненное предварительным просмотром миниатюры файла, которое представляет собой NativeImage.

nativeImage.createFromPath(path)​

• path строка

Возвращает 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 Буфер
• options Объект
  • width Целое число
  • height Целое число
  • scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает NativeImage

Создаёт новый экземпляр NativeImage из buffer, содержащего сырые пиксельные данные растрового изображения, возвращённые toBitmap(). Конкретный формат зависит от платформы.

nativeImage.createFromBuffer(buffer[, options])​

• buffer Буфер
• options Объект (необязательно)
  • width Целое число (необязательно) - Требуется для растровых буферов.
  • height Целое число (необязательно) - Требуется для растровых буферов.
  • scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает NativeImage

Создаёт новый экземпляр NativeImage из buffer. Сначала пытается декодировать как PNG или JPEG.

nativeImage.createFromDataURL(dataURL)​

• dataURL строка

Возвращает NativeImage

Создаёт новый экземпляр NativeImage из dataURL.

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

• imageName строка
• hslShift массив чисел (необязательно)

Возвращает NativeImage

Создаёт новый экземпляр NativeImage из NSImage, который отображается по заданному имени изображения. См. System Icons для списка возможных значений.

hslShift применяется к изображению по следующим правилам:

• hsl_shift[0] (оттенок): Абсолютное значение оттенка для изображения — 0 и 1 соответствуют 0 и 360 на цветовом круге оттенка (красный).
• hsl_shift[1] (насыщенность): Смещение насыщенности для изображения со следующими значениями: 0 = удалить весь цвет. 0,5 = оставить без изменений. 1 = полностью насытить изображение.
• hsl_shift[2] (светлота): Смещение светлоты для изображения со следующими значениями: 0 = удалить всю светлоту (сделать все пиксели чёрными). 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​

Встроенная обертка для изображений, таких как значки панели задач, док-станции и приложения.

Процесс: Основной, Рендеринг
Этот класс не экспортируется из модуля 'electron'. Он доступен только в качестве значения возврата других методов API Electron.

Методы экземпляра​

Следующие методы доступны для экземпляров класса NativeImage:

image.toPNG([options])​

• options Объект (необязательно)
  • scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает Buffer - Буфер, содержащий данные изображения в формате PNG.

image.toJPEG(quality)​

• quality Целое число - От 0 до 100.

Возвращает Buffer - Буфер, содержащий данные изображения в формате JPEG.

image.toBitmap([options])​

• options Объект (необязательно)
  • scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает Buffer - Буфер, содержащий копию необработанных пиксельных данных растрового изображения.

image.toDataURL([options])​

• options Объект (необязательно)
  • scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает string - Данные URL изображения.

image.getBitmap([options])​

• options Объект (необязательно)
  • scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает Buffer - Буфер, содержащий необработанные пиксельные данные растрового изображения.

Разница между getBitmap() и toBitmap() заключается в том, что getBitmap() не копирует данные растрового изображения, поэтому необходимо использовать возвращённый буфер немедленно в текущем цикле событий; в противном случае данные могут быть изменены или уничтожены.

image.getNativeHandle() macOS​

Возвращает Buffer - Буфер, хранящий указатель C на базовый родной дескриптор изображения. В macOS возвращается указатель на экземпляр NSImage.

Обратите внимание, что возвращённый указатель является слабым указателем на базовое родное изображение, а не копией, поэтому необходимо убедиться, что связанный экземпляр nativeImage сохраняется.

image.isEmpty()​

Возвращает boolean - пустое ли изображение.

image.getSize([scaleFactor])​

• scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает Размер.

Если scaleFactor передано, это вернёт размер, соответствующий представлению изображения, наиболее точно соответствующему переданному значению.

image.setTemplateImage(option)​

• option булево значение

Помечает изображение как шаблонное изображение.

image.isTemplateImage()​

Возвращает boolean - является ли изображение шаблонным.

image.crop(rect)​

• rect Прямоугольник - Область изображения для обрезки.

Возвращает NativeImage - обрезанное изображение.

image.resize(options)​

• options Объект
  • width Целое число (необязательно) - По умолчанию ширина изображения.
  • height Целое число (необязательно) - По умолчанию высота изображения.
  • quality строка (необязательно) - Желаемое качество масштабируемого изображения. Возможные значения good, better, или best. По умолчанию best. Эти значения отражают желаемый компромисс между качеством и скоростью. Они переводятся в алгоритм-специфичный метод, который зависит от возможностей (CPU, GPU) базовой платформы. Возможно, что все три метода будут отображаться одним алгоритмом на данной платформе.

Возвращает NativeImage - изменённое изображение.

Если указаны только height или width, то текущее соотношение сторон сохранится в изменённом изображении.

image.getAspectRatio([scaleFactor])​

• scaleFactor Вещественное число (необязательно) - По умолчанию 1.0.

Возвращает Float - коэффициент масштабирования изображения.

Если scaleFactor передано, это вернёт соотношение сторон, соответствующее представлению изображения, наиболее точно соответствующему переданному значению.

image.getScaleFactors()​

Возвращает Float[] - массив всех коэффициентов масштабирования, соответствующих представлениям для данного nativeImage.

image.addRepresentation(options)​

• options Объект
  • scaleFactor Вещественное число - Коэффициент масштабирования для добавления представления изображения.
  • width Целое число (необязательно) - По умолчанию 0. Требуется, если буфер растрового изображения указан как buffer.
  • height Целое число (необязательно) - По умолчанию 0. Требуется, если буфер растрового изображения указан как buffer.
  • buffer Буфер (необязательно) - Буфер, содержащий необработанные данные изображения.
  • dataURL строка (необязательно) - URL данных, содержащий закодированное в формате base 64 PNG или JPEG изображение.

Добавляет представление изображения для определенного коэффициента масштабирования. Это может быть использовано для явного добавления представлений изображения с различными коэффициентами масштабирования к изображению. Этот метод может быть вызван для пустых изображений.

Свойства экземпляра​

nativeImage.isMacTemplateImage macOS​

Свойство boolean, определяющее, считается ли изображение шаблонным изображением.

Обратите внимание, что это свойство действует только в macOS.