nativeImage

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

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 应用程序图标构造参考文档中的*图标缩放*部分。

注意

目前不支持 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> - 包含文件缩略图预览图像的 Promise，该图像是 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 对象
- width 整数
- height 整数
- scaleFactor 数字 (可选) - 默认为 1.0。

返回 NativeImage

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

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

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

返回 NativeImage

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

`nativeImage.createFromDataURL(dataURL)`

dataURL 字符串

返回 NativeImage

从 dataUrl (一个 Base64 编码的数据 URL 字符串) 创建一个新的 NativeImage 实例。

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

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

返回 NativeImage

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

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

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

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

实例方法

NativeImage 类的实例提供以下方法

`image.toPNG([options])`

options 对象 (可选)
- scaleFactor 数字 (可选) - 默认为 1.0。

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

`image.toJPEG(quality)`

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

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

`image.toBitmap([options])`

options 对象 (可选)
- scaleFactor 数字 (可选) - 默认为 1.0。

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

`image.toDataURL([options])`

历史

版本	变更
None	`nativeImage.toDataURL` 将保留 PNG 颜色空间

options 对象 (可选)
- scaleFactor 数字 (可选) - 默认为 1.0。

返回 string - 图像的数据 URL。

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

options 对象 (可选)
- 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()`

返回 boolean - 图像是否是 macOS 模板图像。

`image.crop(rect)`

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

返回 NativeImage - 裁剪后的图像。

`image.resize(options)`

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

返回 NativeImage - 调整大小后的图像。

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

`image.getAspectRatio([scaleFactor])`

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

返回 Number - 图像的纵横比 (宽度除以高度)。

如果传递 scaleFactor，这将返回与最接近传递值的图像表示相对应的纵横比。

`image.getScaleFactors()`

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

`image.addRepresentation(options)`

options 对象
- scaleFactor 数字 (可选) - 添加图像表示的缩放因子。
- width 整数 (可选) - 默认为 0。如果指定 buffer 为位图缓冲区，则必需。
- height 整数 (可选) - 默认为 0。如果指定 buffer 为位图缓冲区，则必需。
- buffer Buffer (可选) - 包含原始图像数据的缓冲区。
- dataURL 字符串 (可选) - 包含 Base64 编码的 PNG 或 JPEG 图像的数据 URL。

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

实例属性

`nativeImage.isMacTemplateImage` macOS

一个 boolean 属性，确定图像是否被视为模板图像。

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