nativeImage

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

信息

如果要在启用了上下文隔离的渲染进程中调用此 API，请将 API 调用放在你的 preload 脚本中，并使用 expose 它，通过 contextBridge API。

nativeImage 模块提供了一个统一的接口来操作系统图像。如果你想提供相同图标的多个缩放版本，或者利用 macOS 模板图像，这些图像会很有用。

接受图像文件的 Electron API 可以接受文件路径或 NativeImage 实例。传递 null 时将使用一个空且透明的图像。

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

主进程
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 实例

主进程
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 })

支持的格式

目前，所有平台都支持 PNG 和 JPEG 图像格式。由于其对透明度和无损压缩的支持，建议使用 PNG。

在 Windows 上，你还可以从文件路径加载 ICO 图标。为了获得最佳的视觉质量，我们建议包含以下至少尺寸

小图标
- 16x16 (100% DPI 缩放)
- 20x20 (125% DPI 缩放)
- 24x24 (150% DPI 缩放)
- 32x32 (200% DPI 缩放)
大图标
- 32x32 (100% DPI 缩放)
- 40x40 (125% DPI 缩放)
- 48x48 (150% DPI 缩放)
- 64x64 (200% DPI 缩放)
- 256x256

请查看 Windows App Icon Construction 参考中的图标缩放部分。

注意

目前不支持 EXIF 元数据，并且在图像编码和解码期间不会考虑它。

高分辨率图像

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

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

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

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

主进程
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

模板图像 macOS

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

最常见的情况是为菜单栏（托盘）图标使用模板图像，以便它可以适应亮色和暗色菜单栏。

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

方法

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

`nativeImage.createEmpty()`

返回 NativeImage

创建一个空的 NativeImage 实例。

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

path 字符串 - 我们打算从中构建缩略图的文件的路径。
size Size - 缩略图所需的宽度和高度（正数）。

返回 Promise<NativeImage> - 成功后返回文件的缩略图预览图像，这是一个 NativeImage。

注意

Windows 实现将忽略 size.height 并根据 size.width 缩放高度。

`nativeImage.createFromPath(path)`

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

返回 NativeImage

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

const { nativeImage } = require('electron')

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

`nativeImage.createFromBitmap(buffer, options)`

buffer Buffer
options Object
- width Integer
- height Integer
- scaleFactor 数字 (可选) - 默认值为 1.0。

返回 NativeImage

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

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

buffer Buffer
options Object (可选)
- width 整数 (可选) - 对于位图缓冲区是必需的。
- height 整数 (可选) - 对于位图缓冲区是必需的。
- scaleFactor 数字 (可选) - 默认值为 1.0。

返回 NativeImage

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

`nativeImage.createFromDataURL(dataURL)`

dataURL 字符串

返回 NativeImage

从 dataUrl 创建一个新的 NativeImage 实例，这是一个 base 64 编码的 Data URL 字符串。

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

imageName 字符串
hslShift 数字数组 (可选)

返回 NativeImage

从映射到给定图像名称的 NSImage 创建一个新的 NativeImage 实例。请参阅 Apple 的 NSImageName 文档和 SF Symbols 以获取可能的列表。

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 应替换为来自此列表的任何值。

对于 SF Symbols，用法如下

const image = nativeImage.createFromNamedImage('square.and.pencil')

其中 'square.and.pencil' 是来自 SF Symbols app 的符号名称。

类: NativeImage

原生包装图像，例如托盘、Dock 和应用程序图标。

进程：主进程，渲染进程
此类未从 'electron' 模块导出。它仅作为 Electron API 中其他方法的返回值可用。

实例方法

NativeImage 类实例上可用的方法如下

`image.toPNG([options])`

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

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

`image.toJPEG(quality)`

quality 整数 - 介于 0 - 100 之间。

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

`image.toBitmap([options])`

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

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

`image.toDataURL([options])`

历史

版本(s)	更改
None	`nativeImage.toDataURL` 将保留 PNG 色彩空间

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

返回 string - 图像的 Data URL。

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

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

image.toBitmap() 的遗留别名。

`image.getNativeHandle()` macOS

返回 Buffer - 存储底层本机图像的 C 指针的 Buffer。在 macOS 上，将返回指向 NSImage 实例的指针。

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

`image.isEmpty()`

返回 boolean - 图像是否为空。

`image.getSize([scaleFactor])`

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

返回 Size。

如果传递了 scaleFactor，这将返回与传递值最匹配的图像表示形式对应的尺寸。

`image.setTemplateImage(option)`

option 布尔值

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

`image.isTemplateImage()`

返回 布尔值 - 是否为 macOS 模板图像。

`image.crop(rect)`

rect 矩形 - 要裁剪的图像区域。

返回 NativeImage - 裁剪后的图像。

`image.resize(options)`

options Object
- width 整数 (可选) - 默认为图像的宽度。
- height 整数 (可选) - 默认为图像的高度。
- quality 字符串 (可选) - 重置图像所需的质量。可能的值包括 good、better 或 best。默认值为 best。这些值表示期望的质量/速度权衡。它们被转换为特定于算法的方法，该方法取决于底层平台的性能（CPU、GPU）。在给定平台上，所有三种方法都可能映射到相同的算法。

返回 NativeImage - 重置大小后的图像。

如果仅指定 height 或 width，则重置大小后的图像将保留当前的纵横比。

`image.getAspectRatio([scaleFactor])`

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

返回 数字 - 图像的纵横比（宽度除以高度）。

如果传递了 scaleFactor，则此函数将返回与传递值最匹配的图像表示形式对应的纵横比。

`image.getScaleFactors()`

返回 数字[] - 与给定 NativeImage 的表示形式对应的所有缩放因子的数组。

`image.addRepresentation(options)`

options Object
- scaleFactor 数字 (可选) - 要添加图像表示形式的缩放因子。
- width 整数 (可选) - 默认为 0。如果指定了 buffer 作为 buffer，则需要此参数。
- height 整数 (可选) - 默认为 0。如果指定了 buffer 作为 buffer，则需要此参数。
- buffer Buffer (可选) - 包含原始图像数据的缓冲区。
- dataURL 字符串 (可选) - 包含 base 64 编码的 PNG 或 JPEG 图像的数据 URL。

为特定缩放因子添加图像表示形式。这可用于以编程方式将不同的缩放因子表示形式添加到图像中。可以在空图像上调用此函数。

实例属性

`nativeImage.isMacTemplateImage` macOS

一个 布尔值 属性，用于确定图像是否被视为模板图像。

请注意，此属性仅在 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