跳转到主内容

nativeImage

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

进程： 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 - 缩略图所需的宽度和高度 (正数)。

返回 Promise<NativeImage> - 文件的缩略图预览图像，包含类型是 NativeImage

注意：Windows 实现将忽略 size.height 并根据 size.width 缩放高度

nativeImage.createFromPath(path)​

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

返回 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
  • 选项 对象
    • 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

其中 SYSTEM_IMAGE_NAME 应替换为 this list里面的值

类: NativeImage​

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

Process: 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。

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

image.toDataURL([options])​

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

返回 string - 图像的 Data URL

image.getBitmap([options])​

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

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

getBitmap() 和 toBitmap() 的不同之处在于，getBitmap() 不会拷贝位图数据，所以你必须在返回 Buffer 后立刻使用它，否则数据可能会被更改或销毁

image.getNativeHandle() macOS​

返回 Buffer-一个 Buffer , 它将 C 指针存储在图像的基础本机句柄上。 在 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)​

返回 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 有影响。