跳转到主要内容

nativeImage

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

进程：主进程, 渲染进程

信息

如果您想在启用了上下文隔离的渲染进程中调用此 API，请将 API 调用放在您的预加载脚本中，并使用 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 来将其标记为 2x 缩放的高分辨率图像。

例如，如果 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 string - 要从中创建缩略图的文件的路径。
  • size Size - 缩略图所需的宽度和高度（正数）。

返回 Promise<NativeImage> - 以文件的缩略图预览图像（一个 NativeImage）进行 fulfilled。

注意

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

nativeImage.createFromPath(path)​

  • path string - 要从中创建图像的文件的路径。

返回 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 Number (可选) - 默认为 1.0。

返回 NativeImage

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

nativeImage.createFromBuffer(buffer[, options])​

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

返回 NativeImage

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

nativeImage.createFromDataURL(dataURL)​

  • dataURL string

返回 NativeImage

从 dataUrl（一个 base64 编码的 Data URL 字符串）创建一个新的 NativeImage 实例。

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

  • imageName string
  • 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 Number (可选) - 默认为 1.0。

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

image.toJPEG(quality)​

  • quality Integer - 介于 0 到 100 之间。

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

image.toBitmap([options])​

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

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

image.toDataURL([options])​

历史
  • options Object (可选)
    • scaleFactor Number (可选) - 默认为 1.0。

返回 string - 图像的 Data URL。

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

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

image.toBitmap() 的旧别名。

image.getNativeHandle() macOS​

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

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

image.isEmpty()​

返回 boolean - 图像是否为空。

image.getSize([scaleFactor])​

  • scaleFactor Number (可选) - 默认为 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 Integer (可选) - 默认为图像的宽度。
    • height Integer (可选) - 默认为图像的高度。
    • quality string (可选) - 调整图像的所需质量。可能的值包括 good、better 或 best。默认为 best。这些值表示期望的质量/速度权衡。它们会被转换为特定于算法的方法，该方法取决于底层平台的性能（CPU、GPU）。在特定平台上，所有三种方法都可能映射到相同的算法。

返回 NativeImage - 调整后的图像。

如果仅指定了 height 或 width，则在调整后的图像中将保留原始宽高比。

image.getAspectRatio([scaleFactor])​

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

返回 Number - 图像的宽高比（宽度除以高度）。

如果传递了 scaleFactor，则返回与最接近传入值匹配的图像表示相对应的宽高比。

image.getScaleFactors()​

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

image.addRepresentation(options)​

  • options Object
    • scaleFactor Number (可选) - 要为其添加图像表示的缩放因子。
    • width Integer (可选) - 默认为 0。如果 buffer 指定为位图缓冲区，则必需。
    • height Integer (可选) - 默认为 0。如果 buffer 指定为位图缓冲区，则必需。
    • buffer Buffer (可选) - 包含原始图像数据的缓冲区。
    • dataURL string (可选) - 包含 base64 编码的 PNG 或 JPEG 图像的数据 URL。

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

实例属性​

nativeImage.isMacTemplateImage macOS​

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

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