nativeImage

使用 PNG 或 JPG 檔案建立系統匣、停靠欄和應用程式圖示。

nativeImage 模組提供了一個統一的介面來操作系統映像。如果您想要提供同一圖示的多個縮放版本，或利用 macOS 範本映像，這些將會非常方便。

接受圖像檔案的 Electron API 接受檔案路徑或 NativeImage 實例。當傳遞 null 時，將使用空白且透明的圖像。

例如，在建立系統匣或設定 BrowserWindow 的圖示時，您可以傳遞圖像檔案路徑作為字串

主進程
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 實例

主進程
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 圖示。為了獲得最佳視覺品質，我們建議至少包含以下大小

小圖示
- 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 應用程式圖示建構參考中的「圖示縮放」章節。

注意

目前不支援 EXIF 元數據，且在圖像編碼和解碼期間不會將其納入考量。

高解析度影像

在支援高像素密度顯示器（例如 Apple Retina）的平台上，您可以在圖像的基本檔名後附加 @2x，將其標記為 2x 比例的高解析度圖像。

例如，如果 icon.png 是具有標準解析度的普通圖像，則 icon@2x.png 將被視為具有雙倍每英吋點數 (DPI) 密度的高解析度圖像。

如果您想要同時支援具有不同 DPI 密度的顯示器，您可以將不同大小的圖像放在同一個資料夾中，並在 Electron 中使用沒有 DPI 字尾的檔名。例如

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

範本圖像 macOS

在 macOS 上，範本圖像由黑色和一個 alpha 通道組成。範本圖像不應作為獨立圖像使用，通常會與其他內容混合以建立所需的最終外觀。

最常見的情況是將範本圖像用於選單列 (系統匣) 圖示，以便它可以適應淺色和深色選單列。

要將圖像標記為範本圖像，其基本檔名應以單字 Template 結尾 (例如 xxxTemplate.png)。您也可以指定不同 DPI 密度的範本圖像 (例如 xxxTemplate@2x.png)。

方法

nativeImage 模組具有下列方法，所有這些方法都會傳回 NativeImage 類別的實例

`nativeImage.createEmpty()`

傳回 NativeImage

建立空的 NativeImage 實例。

`nativeImage.createThumbnailFromPath(path, size)` macOS Windows

path 字串 - 我們打算從中建構縮圖的檔案路徑。
size Size - 縮圖所需的寬度和高度（正數）。

傳回 Promise<NativeImage> - 以檔案的縮圖預覽圖像兌現，這是 NativeImage。

注意：Windows 實作會忽略 size.height 並根據 size.width 調整高度。

`nativeImage.createFromPath(path)`

path 字串 - 我們打算從中建構圖像的檔案路徑。

傳回 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
options 物件
- width 整數
- height 整數
- scaleFactor 數字 (選用) - 預設為 1.0。

傳回 NativeImage

從包含 toBitmap() 傳回的原始點陣圖像素資料的 buffer 建立新的 NativeImage 實例。具體格式取決於平台。

`nativeImage.createFromBuffer(buffer[, options])`

buffer Buffer
options 物件 (選用)
- width 整數 (選用) - 點陣圖緩衝區為必要項。
- height 整數 (選用) - 點陣圖緩衝區為必要項。
- scaleFactor 數字 (選用) - 預設為 1.0。

傳回 NativeImage

從 buffer 建立新的 NativeImage 實例。嘗試先解碼為 PNG 或 JPEG。

`nativeImage.createFromDataURL(dataURL)`

dataURL 字串

傳回 NativeImage

從 dataUrl 建立新的 NativeImage 實例，這是一個 base 64 編碼的 Data URL 字串。

`nativeImage.createFromNamedImage(imageName[, hslShift])` macOS

imageName 字串
hslShift 數字陣列 (選用)

傳回 NativeImage

從對應至給定圖像名稱的 NSImage 建立新的 NativeImage 實例。請參閱 Apple 的 NSImageName 文件，以取得可能值的清單。

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 應替換為此列表中的任何值。

類別：NativeImage

原生包裝影像，例如系統匣、Dock 和應用程式圖示。

進程：主進程、渲染進程
這個類別不會從 'electron' 模組匯出。它僅作為 Electron API 中其他方法的傳回值提供。

實例方法

以下方法在 NativeImage 類別的實例上可用

`image.toPNG([options])`

options 物件 (選用)
- scaleFactor 數字 (選用) - 預設為 1.0。

返回 Buffer - 一個包含影像的 PNG 編碼資料的Buffer。

`image.toJPEG(quality)`

quality 整數 - 介於 0 - 100 之間。

返回 Buffer - 一個包含影像的 JPEG 編碼資料的Buffer。

`image.toBitmap([options])`

options 物件 (選用)
- scaleFactor 數字 (選用) - 預設為 1.0。

返回 Buffer - 一個包含影像的原始點陣圖像素資料副本的Buffer。

`image.toDataURL([options])`

歷史

版本	變更
>=32.0.0	`nativeImage.toDataURL` 將保留 PNG 色彩空間

options 物件 (選用)
- scaleFactor 數字 (選用) - 預設為 1.0。

返回 string - 影像的Data URL。

`image.getBitmap([options])`

options 物件 (選用)
- scaleFactor 數字 (選用) - 預設為 1.0。

返回 Buffer - 一個包含影像的原始點陣圖像素資料的Buffer。

getBitmap() 和 toBitmap() 之間的區別在於 getBitmap() 不會複製點陣圖資料，因此您必須在當前事件迴圈刻度中立即使用返回的 Buffer；否則，資料可能會被變更或銷毀。

`image.getNativeHandle()` macOS

返回 Buffer - 一個儲存影像底層原生控制代碼的 C 指標的Buffer。在 macOS 上，會返回指向 NSImage 實例的指標。

請注意，返回的指標是指向底層原生影像的弱指標，而不是副本，因此您必須確保相關聯的 nativeImage 實例被保留。

`image.isEmpty()`

返回 boolean - 影像是否為空。

`image.getSize([scaleFactor])`

scaleFactor 數字 (選用) - 預設為 1.0。

返回 Size。

如果傳入 scaleFactor，這將返回與最接近傳入值的影像表示相對應的大小。

`image.setTemplateImage(option)`

option 布林值

將影像標記為 macOS 範本影像。

`image.isTemplateImage()`

返回 boolean - 影像是否為 macOS 範本影像。

`image.crop(rect)`

rect Rectangle - 要裁剪的影像區域。

返回 NativeImage - 裁剪後的影像。

`image.resize(options)`

options 物件
- width 整數 (選用) - 預設為影像的寬度。
- height 整數 (選用) - 預設為影像的高度。
- quality 字串 (選用) - 調整大小的影像的所需品質。可能的值包括 good、better 或 best。預設值為 best。這些值表示所需的品質/速度折衷。它們被轉換為特定於演算法的方法，該方法取決於底層平台的功能（CPU、GPU）。所有三種方法都可能在給定平台上對應到相同的演算法。

返回 NativeImage - 調整大小的影像。

如果僅指定 height 或 width，則調整大小的影像中將保留當前縱橫比。

`image.getAspectRatio([scaleFactor])`

scaleFactor 數字 (選用) - 預設為 1.0。

返回 Number - 影像的縱橫比（寬度除以高度）。

如果傳入 scaleFactor，這將返回與最接近傳入值的影像表示相對應的縱橫比。

`image.getScaleFactors()`

返回 Number[] - 對於給定的 NativeImage，對應於表示的所有縮放因子的陣列。

`image.addRepresentation(options)`

options 物件
- scaleFactor 數字 (選用) - 要新增影像表示的縮放因子。
- width 整數 (選用) - 預設為 0。如果將點陣圖緩衝區指定為 buffer，則為必要。
- height 整數 (選用) - 預設為 0。如果將點陣圖緩衝區指定為 buffer，則為必要。
- buffer Buffer (選用) - 包含原始影像資料的緩衝區。
- dataURL 字串 (選用) - 包含 base 64 編碼的 PNG 或 JPEG 影像的資料 URL。

為特定的縮放因子新增影像表示。這可用於以程式方式將不同的縮放因子表示新增到影像。這可以在空影像上呼叫。

實例屬性

`nativeImage.isMacTemplateImage` macOS

一個 boolean 屬性，用於確定影像是否被視為範本影像。

請注意，此屬性僅在 macOS 上有效。

支援的格式​

高解析度影像​

範本圖像 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[, hslShift]) macOS​

類別：NativeImage​

實例方法​

image.toPNG([options])​

image.toJPEG(quality)​

image.toBitmap([options])​

image.toDataURL([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​

支援的格式

高解析度影像

範本圖像 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[, hslShift])` macOS

類別：NativeImage

實例方法

`image.toPNG([options])`

`image.toJPEG(quality)`

`image.toBitmap([options])`

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