跳到主要內容

nativeImage

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

程序： 主程序、 渲染程序

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

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

例如，當建立 Tray 或設定 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，將其標記為 2 倍縮放比例的高解析度影像。

例如，如果 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 通道組成。範本影像不適合用作獨立影像，通常會與其他內容混合以建立所需的最終外觀。

最常見的情況是將範本影像用於選單列 (Tray) 圖示，使其可以適應淺色和深色選單列。

若要將影像標記為範本影像，其基本檔名應以單字 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

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

nativeImage.createFromBuffer(buffer[, options])​

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

傳回 NativeImage

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

nativeImage.createFromDataURL(dataURL)​

  • dataURL 字串

傳回 NativeImage

從 dataUrl 建立新的 NativeImage 實例，dataUrl 是 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])​

歷史記錄
  • 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 上有效。