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>
- 使用文件的缩略图预览图像来实现,这是一个 NativeImage。
注意:Windows 实现将忽略 size.height
,并根据 size.width
缩放高度。
nativeImage.createFromPath(path)
path
字符串 - 我们打算从中构建图像的文件的路径。
返回 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
返回 NativeImage
从 buffer
创建一个新的 NativeImage
实例,其中包含 toBitmap()
返回的原始位图像素数据。特定格式取决于平台。
nativeImage.createFromBuffer(buffer[, options])
buffer
Buffer
返回 NativeImage
从 buffer
创建一个新的 NativeImage
实例。首先尝试解码为 PNG 或 JPEG。
nativeImage.createFromDataURL(dataURL)
dataURL
字符串
返回 NativeImage
从 dataUrl
(base 64 编码的 Data URL 字符串)创建一个新的 NativeImage
实例。
nativeImage.createFromNamedImage(imageName[, hslShift])
macOS
imageName
字符串hslShift
number[](可选)
返回 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])
返回 Buffer
- 包含图像 PNG
编码数据的 Buffer。
image.toJPEG(quality)
quality
整数 - 介于 0 - 100 之间。
返回 Buffer
- 包含图像 JPEG
编码数据的 Buffer。
image.toBitmap([options])
返回 Buffer
- 包含图像原始位图像素数据副本的 Buffer。
image.toDataURL([options])
返回 string
- 图像的 Data URL。
image.getBitmap([options])
返回 Buffer
- 包含图像原始位图像素数据的 Buffer。
getBitmap()
和 toBitmap()
之间的区别在于 getBitmap()
不会复制位图数据,因此您必须在当前事件循环滴答中立即使用返回的 Buffer;否则数据可能会被更改或销毁。
image.getNativeHandle()
macOS
返回 Buffer
- 存储指向图像底层原生句柄的 C 指针的 Buffer。在 macOS 上,返回指向 NSImage
实例的指针。
请注意,返回的指针是指向底层原生图像的弱指针,而不是副本,因此您必须确保关联的 nativeImage
实例保持存在。
image.isEmpty()
返回 boolean
- 图像是否为空。
image.getSize([scaleFactor])
scaleFactor
数字(可选)- 默认为 1.0。
返回 Size。
如果传递了 scaleFactor
,则这将返回与最接近传递值的图像表示形式相对应的大小。
image.setTemplateImage(option)
option
boolean
将图像标记为 macOS 模板图像。
image.isTemplateImage()
返回 boolean
- 图像是否为 macOS 模板图像。
image.crop(rect)
rect
Rectangle - 要裁剪的图像区域。
返回 NativeImage
- 裁剪后的图像。
image.resize(options)
返回 NativeImage
- 调整大小后的图像。
如果仅指定了 height
或 width
,则调整大小后的图像将保留当前宽高比。
image.getAspectRatio([scaleFactor])
scaleFactor
数字(可选)- 默认为 1.0。
返回 Number
- 图像的宽高比(宽度除以高度)。
如果传递了 scaleFactor
,则这将返回与最接近传递值的图像表示形式相对应的宽高比。
image.getScaleFactors()
返回 Number[]
- 与给定 NativeImage
的表示形式相对应的所有缩放比例因子的数组。
image.addRepresentation(options)
为特定的缩放比例因子添加图像表示形式。这可用于以编程方式向图像添加不同的缩放比例因子表示形式。这可以在空图像上调用。
实例属性
nativeImage.isMacTemplateImage
macOS
一个 boolean
属性,用于确定图像是否被视为 模板图像。
请注意,此属性仅在 macOS 上有效。