跳到主要内容

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

支持的格式

目前,所有平台都支持 PNGJPEG 图像格式。建议使用 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
  • options Object
    • width 整数
    • height 整数
    • scaleFactor 数字(可选)- 默认为 1.0。

返回 NativeImage

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

nativeImage.createFromBuffer(buffer[, options])

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

返回 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])

  • 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])

历史记录
  • options Object(可选)
    • scaleFactor 数字(可选)- 默认为 1.0。

返回 string - 图像的 Data URL

image.getBitmap([options])

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

返回 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)

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

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

如果仅指定了 heightwidth,则调整大小后的图像将保留当前宽高比。

image.getAspectRatio([scaleFactor])

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

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

如果传递了 scaleFactor,则这将返回与最接近传递值的图像表示形式相对应的宽高比。

image.getScaleFactors()

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

image.addRepresentation(options)

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

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

实例属性

nativeImage.isMacTemplateImage macOS

一个 boolean 属性,用于确定图像是否被视为 模板图像

请注意,此属性仅在 macOS 上有效。