nativeImage

使用 PNG 或 JPG 文件创建托盘、停靠栏和应用图标。

¥Create tray, dock, and application icons using PNG or JPG files.

[!重要] 如果你想从启用了上下文隔离的渲染进程调用此 API，请将 API 调用放在预加载脚本中，并使用 contextBridge API 对其进行 expose 操作。

¥[!IMPORTANT] If you want to call this API from a renderer process with context isolation enabled, place the API call in your preload script and expose it using the contextBridge API.

nativeImage 模块提供了用于操作系统映像的统一接口。如果你想提供同一图标的多个缩放版本或利用 macOS 模板图片，这些可以很方便。

¥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 API 接受文件路径或 NativeImage 实例。当 null 通过时，将使用一个空的透明图片。

¥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.

例如，当创建 Tray 或设置 BrowserWindow 的图标时，你可以将图片文件路径作为字符串传递：

¥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' })

或从同一文件生成 NativeImage 实例：

¥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 })

支持的格式

¥Supported Formats

目前，所有平台均支持 PNG 和 JPEG 图片格式。推荐使用 PNG，因为它支持透明和无损压缩。

¥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 图标。为了获得最佳视觉质量，我们建议至少包含以下尺寸：

¥On Windows, you can also load ICO icons from file paths. For best visual quality, we recommend including at least the following sizes:

小图标

¥Small icon
- 16x16（100% DPI 比例）
  
  ¥16x16 (100% DPI scale)
- 20x20（125% DPI 比例）
  
  ¥20x20 (125% DPI scale)
- 24x24（150% DPI 比例）
  
  ¥24x24 (150% DPI scale)
- 32x32（200% DPI 比例）
  
  ¥32x32 (200% DPI scale)
大图标

¥Large icon
- 32x32（100% DPI 比例）
  
  ¥32x32 (100% DPI scale)
- 40x40（125% DPI 比例）
  
  ¥40x40 (125% DPI scale)
- 48x48（150% DPI 比例）
  
  ¥48x48 (150% DPI scale)
- 64x64（200% DPI 比例）
  
  ¥64x64 (200% DPI scale)
- 256x256

检查 Windows 应用图标构建参考中的图标缩放部分。

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

注意

目前不支持 EXIF 元数据，并且在图片编码和解码过程中不会考虑 EXIF 元数据。

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

高分辨率图片

¥High Resolution Image

在支持高像素密度显示器的平台（例如 Apple Retina）上，你可以在图片的基本文件名后面附加 @2x，以将其标记为 2 倍比例的高分辨率图片。

¥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.

例如，如果 icon.png 是具有标准分辨率的普通图片，则 icon@2x.png 将被视为具有双倍每英寸点数 (DPI) 密度的高分辨率图片。

¥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.

如果想同时支持不同 DPI 密度的显示器，可以将不同尺寸的图片放在同一个文件夹中，并在 Electron 中使用不带 DPI 后缀的文件名。例如：

¥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. For example:

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 后缀：

¥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

模板图片 macOS

¥Template Image macOS

在 macOS 上，模板图片由黑色和 Alpha 通道组成。模板图片不打算用作独立图片，通常与其他内容混合以创建所需的最终外观。

¥On macOS, 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 (Tray) icon, so it can adapt to both light and dark menu bars.

要将图片标记为模板图片，其基本文件名应以单词 Template 结尾（例如 xxxTemplate.png）。你还可以指定不同 DPI 密度的模板图片（例如 xxxTemplate@2x.png）。

¥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).

方法

¥Methods

nativeImage 模块具有以下方法，所有这些方法都返回 NativeImage 类的实例：

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

`nativeImage.createEmpty()`

返回 NativeImage

¥Returns NativeImage

创建一个空的 NativeImage 实例。

¥Creates an empty NativeImage instance.

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

path 字符串 - 我们打算从中构建缩略图的文件的路径。

¥path string - path to a file that we intend to construct a thumbnail out of.
size 尺寸 - 缩略图所需的宽度和高度（正数）。

¥size Size - the desired width and height (positive numbers) of the thumbnail.

返回 Promise<NativeImage> - 满足文件的缩略图预览图片，即 NativeImage。

¥Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.

[!NOTE] Windows 实现将忽略 size.height，并根据 size.width 缩放高度。

¥[!NOTE] Windows implementation will ignore size.height and scale the height according to size.width.

`nativeImage.createFromPath(path)`

path 字符串 - 我们打算从中构建图片的文件的路径。

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

返回 NativeImage

¥Returns NativeImage

从位于 path 的图片文件（例如 PNG 或 JPEG）创建一个新的 NativeImage 实例。如果 path 不存在、无法读取或不是有效图片，则此方法返回空图片。

¥Creates a new NativeImage instance from an image file (e.g., PNG or JPEG) 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')

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

`nativeImage.createFromBitmap(buffer, options)`

buffer 缓冲

¥buffer Buffer
options 对象

¥options Object
- width 整数
  
  ¥width Integer
- height 整数
  
  ¥height Integer
- scaleFactor 数量（可选） - 默认为 1.0。
  
  ¥scaleFactor Number (optional) - Defaults to 1.0.

返回 NativeImage

¥Returns NativeImage

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

¥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 Buffer
options 对象（可选）

¥options Object (optional)
- width 整数（可选） - 位图缓冲区必需。
  
  ¥width Integer (optional) - Required for bitmap buffers.
- height 整数（可选） - 位图缓冲区必需。
  
  ¥height Integer (optional) - Required for bitmap buffers.
- scaleFactor 数量（可选） - 默认为 1.0。
  
  ¥scaleFactor Number (optional) - Defaults to 1.0.

返回 NativeImage

¥Returns NativeImage

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

¥Creates a new NativeImage instance from buffer. Tries to decode as PNG or JPEG first.

`nativeImage.createFromDataURL(dataURL)`

dataURL 字符串

¥dataURL string

返回 NativeImage

¥Returns NativeImage

从 dataUrl（一个 Base 64 编码的数据网址字符串）创建一个新的 NativeImage 实例。

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

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

imageName 字符串

¥imageName string
hslShift 数字[]（可选）

¥hslShift number[] (optional)

返回 NativeImage

¥Returns NativeImage

从映射到给定图片名称的 NSImage 创建新的 NativeImage 实例。有关可能值的列表，请参阅 Apple 的 NSImageName 文档。

¥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 按以下规则应用于图片：

¥The hslShift is applied to the image with the following rules:

hsl_shift[0]（色调）：图片的绝对色调值 - 0 和 1 映射到色调色轮（红色）上的 0 和 360。

¥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[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]（亮度）：图片的亮度变化，具有以下关键值：0 = 删除所有亮度（使所有像素变黑）。0.5 = 保持不变。1 = 全亮度（使所有像素变白）。

¥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).

这意味着 [-1, 0, 1] 将使图片全白，[-1, 1, 0] 将使图片全黑。

¥This means that [-1, 0, 1] will make the image completely white and [-1, 1, 0] will make the image completely black.

在某些情况下，NSImageName 与其字符串表示形式不匹配；其中一个例子是 NSFolderImageName，其字符串表示实际上是 NSFolder。因此，你需要在传递图片之前确定图片的正确字符串表示形式。这可以通过以下方式完成：

¥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

其中 SYSTEM_IMAGE_NAME 应替换为这个清单中的任何值。

¥where SYSTEM_IMAGE_NAME should be replaced with any value from this list.

类：NativeImage

¥Class: NativeImage

原生封装图片，例如托盘、停靠栏和应用图标。

¥Natively wrap images such as tray, dock, and application icons.

进程：主进程, 渲染器
该类不是从 'electron' 模块导出的。它仅可用作 Electron API 中其他方法的返回值。

¥Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.

实例方法

¥Instance Methods

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

¥The following methods are available on instances of the NativeImage class:

`image.toPNG([options])`

options 对象（可选）

¥options Object (optional)
- scaleFactor 数量（可选） - 默认为 1.0。
  
  ¥scaleFactor Number (optional) - Defaults to 1.0.

返回 Buffer - 包含图片的 PNG 编码数据的缓冲。

¥Returns Buffer - A Buffer that contains the image's PNG encoded data.

`image.toJPEG(quality)`

quality 整数 - 0 之间 - 100.

¥quality Integer - Between 0 - 100.

返回 Buffer - 包含图片的 JPEG 编码数据的缓冲。

¥Returns Buffer - A Buffer that contains the image's JPEG encoded data.

`image.toBitmap([options])`

options 对象（可选）

¥options Object (optional)
- scaleFactor 数量（可选） - 默认为 1.0。
  
  ¥scaleFactor Number (optional) - Defaults to 1.0.

返回 Buffer - 包含图片原始位图片素数据副本的缓冲。

¥Returns Buffer - A Buffer that contains a copy of the image's raw bitmap pixel data.

`image.toDataURL([options])`

History

Version(s)	Changes
None	`nativeImage.toDataURL` will preserve PNG colorspace

options 对象（可选）

¥options Object (optional)
- scaleFactor 数量（可选） - 默认为 1.0。
  
  ¥scaleFactor Number (optional) - Defaults to 1.0.

返回 string - 图片的数据网址。

¥Returns string - The Data URL of the image.

`image.getBitmap([options])` 已弃用

¥image.getBitmap([options]) Deprecated

options 对象（可选）

¥options Object (optional)
- scaleFactor 数量（可选） - 默认为 1.0。
  
  ¥scaleFactor Number (optional) - Defaults to 1.0.

image.toBitmap() 的旧版别名。

¥Legacy alias for image.toBitmap().

`image.getNativeHandle()` macOS

返回 Buffer - 存储指向图片底层原生句柄的 C 指针的缓冲。在 macOS 上，返回指向 NSImage 实例的指针。

¥Returns Buffer - A Buffer that stores C pointer to underlying native handle of the image. On macOS, a pointer to NSImage instance is returned.

请注意，返回的指针是指向底层原生映像的弱指针，而不是副本，因此你必须确保保留关联的 nativeImage 实例。

¥Notice that the returned pointer is a weak pointer to the underlying native image instead of a copy, so you must ensure that the associated nativeImage instance is kept around.

`image.isEmpty()`

返回 boolean - 图片是否为空。

¥Returns boolean - Whether the image is empty.

`image.getSize([scaleFactor])`

scaleFactor 数量（可选） - 默认为 1.0。

¥scaleFactor Number (optional) - Defaults to 1.0.

返回 Size。

¥Returns Size.

如果传递 scaleFactor，这将返回与传递值最匹配的图片表示形式对应的大小。

¥If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.

`image.setTemplateImage(option)`

option 布尔值

¥option boolean

将图片标记为 macOS 模板图片。

¥Marks the image as a macOS template image.

`image.isTemplateImage()`

返回 boolean - 图片是否为 macOS 模板图片。

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

`image.crop(rect)`

rect 长方形 - 要裁剪的图片区域。

¥rect Rectangle - The area of the image to crop.

返回 NativeImage - 裁剪后的图片。

¥Returns NativeImage - The cropped image.

`image.resize(options)`

options 对象

¥options Object
- width 整数（可选） - 默认为图片的宽度。
  
  ¥width Integer (optional) - Defaults to the image's width.
- height 整数（可选） - 默认为图片的高度。
  
  ¥height Integer (optional) - Defaults to the image's height.
- quality 字符串（可选） - 调整图片大小所需的质量。可能的值包括 good、better 或 best。默认为 best。这些值表示所需的质量/速度权衡。它们被转换为特定于算法的方法，该方法取决于底层平台的功能（CPU、GPU）。所有三种方法都可以映射到给定平台上的相同算法。
  
  ¥quality string (optional) - The desired quality of the resize image. Possible values include good, better, or best. The default is best. These values express a desired quality/speed tradeoff. 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.

返回 NativeImage - 调整大小的图片。

¥Returns NativeImage - The resized image.

如果仅指定 height 或 width，则当前宽高比将保留在调整大小的图片中。

¥If only the height or the width are specified then the current aspect ratio will be preserved in the resized image.

`image.getAspectRatio([scaleFactor])`

scaleFactor 数量（可选） - 默认为 1.0。

¥scaleFactor Number (optional) - Defaults to 1.0.

返回 Number - 图片的纵横比（宽度除以高度）。

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

如果传递了 scaleFactor，这将返回与传递值最匹配的图片表示对应的长宽比。

¥If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.

`image.getScaleFactors()`

返回 Number[] - 与给定 NativeImage 的表示相对应的所有比例因子的数组。

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

`image.addRepresentation(options)`

options 对象

¥options Object
- scaleFactor 数量（可选） - 添加图片表示的比例因子。
  
  ¥scaleFactor Number (optional) - The scale factor to add the image representation for.
- width 整数（可选） - 默认为 0。如果位图缓冲区指定为 buffer，则为必需。
  
  ¥width Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.
- height 整数（可选） - 默认为 0。如果位图缓冲区指定为 buffer，则为必需。
  
  ¥height Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.
- buffer Buffer (optional) - 包含原始图片数据的缓冲区。
  
  ¥buffer Buffer (optional) - The buffer containing the raw image data.
- dataURL 字符串（可选） - 包含 Base 64 编码的 PNG 或 JPEG 图片的数据 URL。
  
  ¥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 programmatically add different scale factor representations to an image. This can be called on empty images.

实例属性

¥Instance Properties

`nativeImage.isMacTemplateImage` macOS

确定图片是否被视为模板图片的 boolean 属性。

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

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

¥Please note that this property only has an effect on macOS.

支持的格式​

高分辨率图片​

模板图片 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​

支持的格式

高分辨率图片

模板图片 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