nativeImage

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

Process: Main, Renderer

nativeImage 模块提供了一个用于操纵系统图像的统一接口。 如果您想要提供同一图标的多个缩放的 版本，或利用macOS 模板图像 ，这些都很方便。

在 Electron 内, 那些需要图片的 API 可以传递两种参数, 一种是文件路径, 一种是 NativeImage 实例对象。 传递 null 参数将使用空和透明的图像。

例如, 创建 系统托盘 或设置 窗口的图标, 你可能传递一个图片或文件路径字符串:

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 是因为它支持透明度和无损压缩。

在 Windows 平台下, 你同样可以从文件路径中加载ICO 格式的 icons 对象。 为了最好的质量，我们建议至少包括以下大小：

• 小图标
  • 16x16 (100% DPI scale)
  • 20x20 (125% DPI scale)
  • 24x24 (150% DPI scale)
  • 32x32 (200% DPI scale)
• 大图标
  • 32x32 (100% DPI scale)
  • 40x40 (125% DPI scale)
  • 48x48 (150% DPI scale)
  • 64x64 (200% DPI scale)
  • 256x256

在Windows 构造 Windows 应用的图标 文档了解更多关于 图标缩放.

note

EXIF 元数据目前不被支持，将在图像编码和解码期间将不会被考虑在内。

高分辨率

在具有高分辨率支持的平台 (如 Apple 视网膜显示器) 上, 可以在图像的基本文件名之后追加 @2x 以将其标记为高分辨率图像。

例如，如果 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 通道组成。 模板图片不是单独使用的, 它通常与其他内容混合以创建期望的最终效果

最常见的情况是使用模板图片作为菜单栏(系统托盘) 图标, 使它可以适应浅色和深色菜单栏。

要将图像标记为模板图像，其基础文件名应该以单词Template (例如 xxxTemplate.png)结尾。 您也可以在不同的 DPI 密度指定模板图像(例如， xxxTemplate@2x.png)。

方法

nativeImage 模块有以下方法，所有方法都返回 NativeImage 类的实例：

nativeImage.createEmpty()

返回 NativeImage

创建一个空的 NativeImage 实例。

nativeImage.createThumbnailFromPath(path, size) macOS Windows

• path string - 打算用来构建缩略图的文件路径
• size Size - 缩略图所需的宽度和高度 (正数)。

Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.

[!NOTE] Windows implementation will ignore size.height and scale the height according to size.width.

nativeImage.createFromPath(path)

• path sting - 构造图像的文件路径。

返回 NativeImage

Creates a new NativeImage instance from an image file (e.g., PNG or JPEG) located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image.

const { nativeImage } = require('electron')

const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)

nativeImage.createFromBitmap(buffer, options)

• buffer Buffer
• 选项 对象
  • width Integer
  • height Integer
  • scaleFactor Number (可选) - 默认值为 1.0。

返回 NativeImage

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

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创建一个新的 NativeImage 实例, base 64 编码的 Data URL 字符串。

nativeImage.createFromNamedImage(imageName[, hslShift]) macOS

• imageName string
• hslShift number[] (可选)

返回 NativeImage

从 NSImage 创建一个新的 NativeImage 实例映射到给定的图像名称。 请参阅Apple的 NSImageName文档以获取更多信息。

使用以下规则将hslShift应用于图像:

• hsl_shift[0] (hue)：图像的绝对色盘值：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

where SYSTEM_IMAGE_NAME should be replaced with any value from this list.

类: NativeImage

本机图像，如托盘、dock栏和应用图标。

Process: Main, Renderer
This class is not exported from the 'electron' module. 它只能作为 Electron API 中其他方法的返回值。

实例方法

以下方法可用于 NativeImage 类的实例:

image.toPNG([options])

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

Returns Buffer - A Buffer that contains the image's PNG encoded data.

image.toJPEG(quality)

• quality Integer - 在 0 - 100 之间

Returns Buffer - A Buffer that contains the image's JPEG encoded data.

image.toBitmap([options])

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

Returns Buffer - A Buffer that contains a copy of the image's raw bitmap pixel data.

image.toDataURL([options])

History

Version(s)	Changes
None	nativeImage.toDataURL will preserve PNG colorspace

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

返回 string - 图像的 Data URL

image.getBitmap([options]) Deprecated

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

Legacy alias for image.toBitmap().

image.getNativeHandle() macOS

Returns Buffer - A Buffer that stores C pointer to underlying native handle of the image. 在 macOS上返回一个 NSImage 实例的指针。

请注意, 返回的指针是指向基础本机映像而不是副本的弱指针, 因此 _ 必须 _ 确保关联的 nativeImage 实例保留在周围。

image.isEmpty()

返回 boolean - 图像是否为空。

image.getSize([scaleFactor])

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

Returns Size.

如果传递了 scaleFactor ，将返回与图像表示最接近的传递值对应的大小。

image.setTemplateImage(option)

• option boolean

标记图像为 macOS 模板图像。

image.isTemplateImage()

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

image.crop(rect)

• rect Rectangle - The area of the image to crop.

返回 NativeImage-裁剪的图像。

image.resize(options)

• 选项 对象
  • width Integer (可选) - 默认值为图片宽度
  • height Integer (可选) - 默认值为图片高度.
  • quality string (optional) 所要设置的图片质量。 可能的值包括 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)

• 选项 对象
  • scaleFactor Number (可选) - 要添加图像的缩放系数。
  • width Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer, 则为必填项
  • height Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer, 则为必填项
  • buffer Buffer (可选) - 包含原始图像数据的缓冲区.
  • dataURL string (可选) - data URL 可以为 base 64 编码的 PNG 或 JPEG 图像.

为特定比例因子添加图像表示。 这可以使用编程实现将不同的比例因子表示添加到图像中。 这种可以调用在空图像上。

实例属性

nativeImage.isMacTemplateImage macOS

决定图像是否被视为 模板图像 的 boolean 属性。

请注意，此属性仅对 macOS 有影响。