nativeImage¶

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

[!IMPORTANT] 如果你想在启用上下文隔离的渲染进程中调用此 API，请将 API 调用放在预加载脚本中，并使用 contextBridge API 将其暴露。

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

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

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

Main Process

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 实例：

Main Process

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 支持透明度和无损压缩，因此推荐使用 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 应用图标构建参考中的 图标缩放 部分。

:::note

目前不支持 EXIF 元数据，在图像编码和解码过程中也不会考虑它。

:::

高分辨率图像¶

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

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

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

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

Main Process

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 通道组成。模板图像不打算作为独立图像使用，通常与其他内容混合以创建所需的最终外观。

最常见的情况是将模板图像用于菜单栏（Tray）图标，使其能够适应浅色和深色菜单栏。

要将图像标记为模板图像，其基础文件名应以单词 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。

[!NOTE] 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[, options])` macOS¶

imageName string
options Object | number[]（可选）- 如果 options 是数值数组（已弃用），则将其解析为 hslShift。如果它是一个对象，则可以指定以下属性：
hslShift number[]（可选）
pointSize Number（可选）- 默认为 30.0。
weight 'ultralight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black'（可选）- 默认为 regular。
scale 'small' | 'medium' | 'large'（可选）- 默认为 medium。

返回 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 应用的符号名称。

`nativeImage.createMenuSymbol(imageName)` macOS¶

imageName string

返回 NativeImage

从 SF Symbol 创建新的 NativeImage 实例，用于原生 Menu 中。有关可能值的列表，请参阅 SF Symbols。

const { nativeImage, MenuItem } = require('electron')

const item = new MenuItem({
  icon: nativeImage.createMenuSymbol('folder.badge.plus'),
  label: 'Create Folder'
})

类：NativeImage¶

以原生方式封装图像，例如托盘、Dock 和应用图标。

进程：Main、Renderer
此类不会从 '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。

返回 string - 图像的 Data URL。

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

options Object（可选）
scaleFactor Number（可选）- 默认为 1.0。
colorSpace ColorSpace（可选）- 输出像素数据的目标色彩空间。默认为 sRGB。传入图像的原始色彩空间以保留先前行为，或传入其他色彩空间以获取该空间中的像素值。

image.toBitmap() 的旧别名。

`image.getNativeHandle()` macOS¶

返回 Buffer - 一个 Buffer，存储指向图像底层原生句柄的 C 指针。在 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 (可选) - 包含 base 64 编码的 PNG 或 JPEG 图像的数据 URL。

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

实例属性¶

`nativeImage.isMacTemplateImage` macOS¶

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

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron

nativeImage¶

支持的格式¶

高分辨率图像¶

模板图像 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[, options]) macOS¶

nativeImage.createMenuSymbol(imageName) macOS¶

类：NativeImage¶

实例方法¶

image.toPNG([options])¶

image.toJPEG(quality)¶

image.toBitmap([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¶

`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[, options])` macOS¶

`nativeImage.createMenuSymbol(imageName)` macOS¶

`image.toPNG([options])`¶

`image.toJPEG(quality)`¶

`image.toBitmap([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¶