nativeImage
使用 PNG 或 JPG 文件创建托盘、dock和应用程序图标。
The nativeImage
module provides a unified interface for manipulating system images. These can be handy if you want to provide multiple scaled versions of the same icon or take advantage of macOS template images.
Electron APIs that take image files accept either file paths or NativeImage
instances. An empty and transparent image will be used when null
is passed.
For example, when creating a Tray or setting a BrowserWindow's icon, you can either pass an image file path as a string:
const { BrowserWindow, Tray } = require('electron')
const tray = new Tray('/Users/somebody/images/icon.png')
const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })
or generate a NativeImage
instance from the same file:
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 })
支持的格式
Currently, PNG
and JPEG
image formats are supported across all platforms. PNG
is recommended because of its support for transparency and lossless compression.
在 Windows 平台下, 你同样可以从文件路径中加载ICO
格式的 icons 对象。 For best visual quality, we recommend including at least the following sizes:
- 小图标
- 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
Check the Icon Scaling section in the Windows App Icon Construction reference.
EXIF metadata is currently not supported and will not be taken into account during image encoding and decoding.
高分辨率
On platforms that support high pixel density displays (such as Apple Retina), you can append @2x
after image's base filename to mark it as a 2x scale high resolution image.
For example, if icon.png
is a normal image that has standard resolution, then icon@2x.png
will be treated as a high resolution image that has double Dots per Inch (DPI) density.
If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes within Electron. 例如:
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
Template Image macOS
On macOS, template images consist of black and an alpha channel. 模板图片不是单独使用的, 它通常与其他内容混合以创建期望的最终效果
The most common case is to use template images for a menu bar (Tray) icon, so it can adapt to both light and dark menu bars.
To mark an image as a template image, its base filename should end with the word Template
(e.g. xxxTemplate.png
). You can also specify template images at different DPI densities (e.g. xxxTemplate@2x.png
).
方法
The nativeImage
module has the following methods, all of which return an instance of the NativeImage
class:
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 - path to a file that we intend to construct an image out of.
返回 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
Integerheight
IntegerscaleFactor
Number (可选) - 默认值为 1.0。
返回 NativeImage
从 buffer
中创建一个新的 NativeImage
实例,其中包含由 toBitmap()
返回的原始位图 像素数据。 具体格式取决于平台。
nativeImage.createFromBuffer(buffer[, options])
buffer
Buffer
返回 NativeImage
从 buffer
创建新的 NativeImage
实例。 尝试先解码为 PNG 或 JPEG
nativeImage.createFromDataURL(dataURL)
dataURL
string
返回 NativeImage
Creates a new NativeImage
instance from dataUrl
, a base 64 encoded Data URL string.
nativeImage.createFromNamedImage(imageName[, hslShift])
macOS
imageName
stringhslShift
number[] (可选)
返回 NativeImage
Creates a new NativeImage
instance from the NSImage
that maps to the given image name. See Apple's NSImageName
documentation for a list of possible values.
使用以下规则将hslShift
应用于图像:
hsl_shift[0]
(hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).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])
返回 Buffer
-一个包含图像 PNG
编码数据的 Buffer 。
image.toJPEG(quality)
quality
Integer - 在 0 - 100 之间
返回 Buffer
-一个包含图像 JPEG
编码数据的 Buffer 。
image.toBitmap([options])
返回 Buffer
-一个包含图像的原始位图像素数据副本的 Buffer 。
image.toDataURL([options])
Returns string
- The Data URL of the image.
image.getBitmap([options])
返回 Buffer
-一个包含图像原始位图像素数据的 Buffer 。
getBitmap()
和 toBitmap()
的不同之处在于,getBitmap()
不会拷贝位图数据,所以你必须在返回 Buffer 后立刻使用它,否则数据可能会被更改或销毁
image.getNativeHandle()
macOS
返回 Buffer
-一个 Buffer , 它将 C 指针存储在图像的基础本机句柄上。 On macOS, a pointer to NSImage
instance is returned.
请注意, 返回的指针是指向基础本机映像而不是副本的弱指针, 因此 必须 确保关联的 nativeImage
实例保留在周围。
image.isEmpty()
返回 boolean
- 图像是否为空。
image.getSize([scaleFactor])
scaleFactor
Number (可选) - 默认值为 1.0。
Returns Size.
如果传递了 scaleFactor
,将返回与图像表示最接近的传递值对应的大小。
image.setTemplateImage(option)
option
boolean
Marks the image as a macOS template image.
image.isTemplateImage()
Returns boolean
- Whether the image is a macOS template image.
image.crop(rect)
rect
Rectangle -要裁剪的图像区域.
返回 NativeImage
-裁剪的图像。
image.resize(options)
选项
对象width
Integer (可选) - 默认值为图片宽度height
Integer (可选) - 默认值为图片高度.quality
string (optional) 所要设置的图片质量。 Possible values includegood
,better
, orbest
. 默认值为best
. 这些值表示期望的 质量/速度 的权衡。 他们被转换为某个特定算法, 取决于基础平台的能力 (CPU, GPU)。 这三种方法都可以在指定的平台上映射到相同的算法。
返回 NativeImage
-裁剪的图像。
如果只指定height
或width
,那么当前的长宽比将保留在缩放图像中。
image.getAspectRatio([scaleFactor])
scaleFactor
Number (可选) - 默认值为 1.0。
Returns Number
- The image's aspect ratio (width divided by height).
如果传递了 scaleFactor
,将返回与图像表示最接近的传递值对应的大小。
image.getScaleFactors()
Returns Number[]
- An array of all scale factors corresponding to representations for a given NativeImage
.
image.addRepresentation(options)
选项
对象scaleFactor
Number (可选) - 要添加图像的缩放系数。width
Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer
, 则为必填项height
Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer
, 则为必填项buffer
Buffer (可选) - 包含原始图像数据的缓冲区.dataURL
string (可选) - data URL 可以为 base 64 编码的 PNG 或 JPEG 图像.
为特定比例因子添加图像表示。 This can be used to programmatically add different scale factor representations to an image. 这种可以调用在空图像上。
实例属性
nativeImage.isMacTemplateImage
macOS
A boolean
property that determines whether the image is considered a template image.
请注意,此属性仅对 macOS 有影响。