nativeImage

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

进程： Main, Renderer

在 Electron 内, 那些需要图片的 API 可以传递两种参数, 一种是文件路径, 一种是 NativeImage 实例对象。 空的图片对象将被 null 参数替代

例如, 创建托盘或设置窗口图标时, 你可以传递 string 格式的图片路径

  1. const { BrowserWindow, Tray } = require('electron')
  3. const appIcon = new Tray('/Users/somebody/images/icon.png')
  4. const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })
  5. console.log(appIcon, win)

或者从粘贴板读取图片，将返回 NativeImage 对象：

  1. const { clipboard, Tray } = require('electron')
  2. const image = clipboard.readImage()
  3. const appIcon = new Tray(image)
  4. console.log(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

在这篇文章中查看 尺寸说明 的章节

高分辨率

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

比如， 如果 icon.png 是一个普通的标准分辨率的图片，而 icon@2x.png 将被视为具有两倍DPI密度的高分辨率图像

如果您想同时支持不同的DPI密度显示，您可以将不同大小的图像放置在同一文件夹中，并使用文件名而不需要DPI 后缀。 例如：

  1. images/
  2. ├── icon.png
  3. ├── icon@2x.png
  4. └── icon@3x.png
  1. const { Tray } = require('electron')
  2. const appIcon = new Tray('/Users/somebody/images/icon.png')
  3. console.log(appIcon)

还支持以下DPI的后缀：

  • @1x
  • @1.25x
  • @1.33x
  • @1.4x
  • @1.5x
  • @1.8x
  • @2x
  • @2.5x
  • @3x
  • @4x
  • @5x

模板图片

模板图像由黑色和透明通道组成。 模板图片不是单独使用的, 它通常与其他内容混合以创建期望的最终效果

最常见的情况是使用模板图像作为菜单栏图标，因此它可以适应浅色和深色菜单栏。

注意: 仅在 macOS 上支持Template image。

要将图像标记为模板图像，其文件名应以 Template 一词结尾。 例如：

  • xxxTemplate.png
  • xxxTemplate@2x.png

方法

nativeImage 模块具有以下方法, 它们都返回 nativeImage 类的实例:

nativeImage.createEmpty()

返回 NativeImage

创建一个空的 NativeImage 实例。

nativeImage.createThumbnailFromPath(path, size) macOS Windows

  • path string - 打算用来构建缩略图的文件路径
  • size Size - the desired width and height (positive numbers) of the thumbnail.

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

Note: The Windows implementation will ignore size.height and scale the height according to size.width.

nativeImage.createFromPath(path)

  • path string

返回 NativeImage

从位于 path 的文件创建新的 NativeImage 实例。 如果 path 不存在，，无法读取或不是有效图像，方法将返回空图像, 。

  1. const nativeImage = require('electron').nativeImage
  3. const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
  4. 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 实例。

nativeImage.createFromNamedImage(imageName[, hslShift]) macOS

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

返回 NativeImage

从映射到给定图像名称的 NSImage 创建一个 NativeImage 实例。 可用值列表详见 System Icons

使用以下规则将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 应替换为 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])

  • 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

将图像标记为模板图像。

image.isTemplateImage()

返回 boolean - 图像是否为模板图像。

image.crop(rect)

返回 NativeImage-裁剪的图像。

image.resize(options)

  • 选项 对象
    • width Integer (可选) - 默认值为图片宽度
    • height Integer (可选) - 默认值为图片高度.
    • quality string (optional) 所要设置的图片质量。 Possible values include good, better, or best. 默认值为best. 这些值表示期望的 质量/速度 的权衡。 他们被转换为某个特定算法, 取决于基础平台的能力 (CPU, GPU)。 这三种方法都可以在指定的平台上映射到相同的算法。

返回 NativeImage-裁剪的图像。

如果只指定height或width，那么当前的长宽比将保留在缩放图像中。

image.getAspectRatio([scaleFactor])

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

返回 Number - 图像的长宽比.

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

image.getScaleFactors()

Returns 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 属性，用于决定图像是否被认为是一个 template image.

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