nativeImage

使用 PNG 或 JPG 文件创建托盘、dock和应用程序图标。

The nativeImage module provides a unified interface for manipulating system images. These can be handy if you want to provide multiple scaled versions of the same icon or take advantage of macOS template images.

Electron APIs that take image files accept either file paths or NativeImage instances. An empty and transparent image will be used when null is passed.

For example, when creating a Tray or setting a BrowserWindow's icon, you can either pass an image file path as a string:

Main Process
const { BrowserWindow, Tray } = require('electron')

const tray = new Tray('/Users/somebody/images/icon.png')
const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })

or generate a NativeImage instance from the same file:

Main Process
const { BrowserWindow, nativeImage, Tray } = require('electron')

const trayIcon = nativeImage.createFromPath('/Users/somebody/images/icon.png')
const appIcon = nativeImage.createFromPath('/Users/somebody/images/window.png')
const tray = new Tray(trayIcon)
const win = new BrowserWindow({ icon: appIcon })

支持的格式

Currently, PNG and JPEG image formats are supported across all platforms. PNG is recommended because of its support for transparency and lossless compression.

在 Windows 平台下, 你同样可以从文件路径中加载ICO 格式的 icons 对象。 For best visual quality, we recommend including at least the following sizes:

小图标
- 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

Check the Icon Scaling section in the Windows App Icon Construction reference.

note

EXIF metadata is currently not supported and will not be taken into account during image encoding and decoding.

高分辨率

On platforms that support high pixel density displays (such as Apple Retina), you can append @2x after image's base filename to mark it as a 2x scale 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 Dots per Inch (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 within Electron. 例如：

images/
├── icon.png
├── icon@2x.png
└── icon@3x.png

Main Process
const { Tray } = require('electron')
const appTray = new Tray('/Users/somebody/images/icon.png')

还支持以下DPI的后缀：

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

Template Image macOS

On macOS, template images consist of black and an alpha channel. 模板图片不是单独使用的, 它通常与其他内容混合以创建期望的最终效果

The most common case is to use template images for a menu bar (Tray) icon, so it can adapt to both light and dark menu bars.

To mark an image as a template image, its base filename should end with the word Template (e.g. xxxTemplate.png). You can also specify template images at different DPI densities (e.g. xxxTemplate@2x.png).

方法

The nativeImage module has the following methods, all of which return an instance of the NativeImage class:

`nativeImage.createEmpty()`

返回 NativeImage

创建一个空的 NativeImage 实例。

`nativeImage.createThumbnailFromPath(path, size)` macOS Windows

path string - 打算用来构建缩略图的文件路径
size Size - the desired width and height (positive numbers) of the thumbnail.

返回 Promise<NativeImage> - 文件的缩略图预览图像，包含类型是 NativeImage

Note: The Windows implementation will ignore size.height and scale the height according to size.width.

`nativeImage.createFromPath(path)`

path string - path to a file that we intend to construct an image out of.

返回 NativeImage

从位于 path 的文件创建新的 NativeImage 实例。如果 path 不存在，，无法读取或不是有效图像，方法将返回空图像, 。

const { nativeImage } = require('electron')

const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)

`nativeImage.createFromBitmap(buffer, options)`

buffer Buffer
选项 对象
- width Integer
- height Integer
- scaleFactor Number (可选) - 默认值为 1.0。

返回 NativeImage

从 buffer 中创建一个新的 NativeImage 实例，其中包含由 toBitmap()返回的原始位图像素数据。具体格式取决于平台。

`nativeImage.createFromBuffer(buffer[, options])`

buffer Buffer
options Object (可选)
- width Integer (可选) - 位图缓冲器所必需
- height Integer (可选) - 位图缓冲器所必需
- scaleFactor Number (可选) - 默认值为 1.0。

返回 NativeImage

从 buffer 创建新的 NativeImage 实例。尝试先解码为 PNG 或 JPEG

`nativeImage.createFromDataURL(dataURL)`

dataURL string

返回 NativeImage

Creates a new NativeImage instance from dataUrl, a base 64 encoded Data URL string.

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

imageName string
hslShift number[] (可选)

返回 NativeImage

Creates a new NativeImage instance from the NSImage that maps to the given image name. See Apple's NSImageName documentation for a list of possible values.

使用以下规则将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] (饱和度): 图像的饱和度调值，以下关键值： 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 应替换为 this list里面的值

类: NativeImage

本机图像，如托盘、dock栏和应用图标。

Process: Main, Renderer
此类不从 'electron' 模块导出. 它只能作为 Electron API 中其他方法的返回值。

实例方法

以下方法可用于 NativeImage 类的实例:

`image.toPNG([options])`

options Object (可选)
- scaleFactor Number (可选) - 默认值为 1.0。

返回 Buffer-一个包含图像 PNG 编码数据的 Buffer 。

`image.toJPEG(quality)`

quality Integer - 在 0 - 100 之间

返回 Buffer-一个包含图像 JPEG 编码数据的 Buffer 。

`image.toBitmap([options])`

options Object (可选)
- scaleFactor Number (可选) - 默认值为 1.0。

返回 Buffer-一个包含图像的原始位图像素数据副本的 Buffer 。

`image.toDataURL([options])`

options Object (可选)
- scaleFactor Number (可选) - 默认值为 1.0。

Returns string - The Data URL of the image.

`image.getBitmap([options])`

options Object (可选)
- scaleFactor Number (可选) - 默认值为 1.0。

返回 Buffer-一个包含图像原始位图像素数据的 Buffer 。

getBitmap() 和 toBitmap() 的不同之处在于，getBitmap() 不会拷贝位图数据，所以你必须在返回 Buffer 后立刻使用它，否则数据可能会被更改或销毁

`image.getNativeHandle()` macOS

返回 Buffer-一个 Buffer , 它将 C 指针存储在图像的基础本机句柄上。 On macOS, a pointer to NSImage instance is returned.

请注意, 返回的指针是指向基础本机映像而不是副本的弱指针, 因此必须确保关联的 nativeImage 实例保留在周围。

`image.isEmpty()`

返回 boolean - 图像是否为空。

`image.getSize([scaleFactor])`

scaleFactor Number (可选) - 默认值为 1.0。

Returns Size.

如果传递了 scaleFactor ，将返回与图像表示最接近的传递值对应的大小。

`image.setTemplateImage(option)`

option boolean

Marks the image as a macOS template image.

`image.isTemplateImage()`

Returns boolean - Whether the image is a macOS template image.

`image.crop(rect)`

rect Rectangle -要裁剪的图像区域.

返回 NativeImage-裁剪的图像。

`image.resize(options)`

选项 对象
- width Integer (可选) - 默认值为图片宽度
- height Integer (可选) - 默认值为图片高度.
- quality string (optional) 所要设置的图片质量。 Possible values include good, better, or best. 默认值为best. 这些值表示期望的质量/速度的权衡。他们被转换为某个特定算法, 取决于基础平台的能力 (CPU, GPU)。这三种方法都可以在指定的平台上映射到相同的算法。

返回 NativeImage-裁剪的图像。

如果只指定height或width，那么当前的长宽比将保留在缩放图像中。

`image.getAspectRatio([scaleFactor])`

scaleFactor Number (可选) - 默认值为 1.0。

Returns Number - The image's aspect ratio (width divided by height).

如果传递了 scaleFactor ，将返回与图像表示最接近的传递值对应的大小。

`image.getScaleFactors()`

Returns Number[] - An array of all scale factors corresponding to representations for a given NativeImage.

`image.addRepresentation(options)`

选项 对象
- scaleFactor Number (可选) - 要添加图像的缩放系数。
- width Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer, 则为必填项
- height Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer, 则为必填项
- buffer Buffer (可选) - 包含原始图像数据的缓冲区.
- dataURL string (可选) - data URL 可以为 base 64 编码的 PNG 或 JPEG 图像.

为特定比例因子添加图像表示。 This can be used to programmatically add different scale factor representations to an image. 这种可以调用在空图像上。

实例属性

`nativeImage.isMacTemplateImage` macOS

A boolean property that determines whether the image is considered a template image.

请注意，此属性仅对 macOS 有影响。

nativeImage

支持的格式​

高分辨率​

Template Image macOS​

方法​

nativeImage.createEmpty()​

nativeImage.createThumbnailFromPath(path, size) macOS Windows​

nativeImage.createFromPath(path)​

nativeImage.createFromBitmap(buffer, options)​

nativeImage.createFromBuffer(buffer[, options])​

nativeImage.createFromDataURL(dataURL)​

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

类: NativeImage​

实例方法​

image.toPNG([options])​

image.toJPEG(quality)​

image.toBitmap([options])​

image.toDataURL([options])​

image.getBitmap([options])​

image.getNativeHandle() macOS​

image.isEmpty()​

image.getSize([scaleFactor])​

image.setTemplateImage(option)​

image.isTemplateImage()​

image.crop(rect)​

image.resize(options)​

image.getAspectRatio([scaleFactor])​

image.getScaleFactors()​

image.addRepresentation(options)​

实例属性​

nativeImage.isMacTemplateImage macOS​

支持的格式

高分辨率

Template Image macOS

方法

`nativeImage.createEmpty()`

`nativeImage.createThumbnailFromPath(path, size)` macOS Windows

`nativeImage.createFromPath(path)`

`nativeImage.createFromBitmap(buffer, options)`

`nativeImage.createFromBuffer(buffer[, options])`

`nativeImage.createFromDataURL(dataURL)`

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

类: NativeImage

实例方法

`image.toPNG([options])`

`image.toJPEG(quality)`

`image.toBitmap([options])`

`image.toDataURL([options])`

`image.getBitmap([options])`

`image.getNativeHandle()` macOS

`image.isEmpty()`

`image.getSize([scaleFactor])`

`image.setTemplateImage(option)`

`image.isTemplateImage()`

`image.crop(rect)`

`image.resize(options)`

`image.getAspectRatio([scaleFactor])`

`image.getScaleFactors()`

`image.addRepresentation(options)`

实例属性

`nativeImage.isMacTemplateImage` macOS