跳到主要內容

Tray

類別：Tray​

將圖示和關聯選單新增到系統的通知區域。

程序： 主程序

Tray 是 EventEmitter。

const { app, Menu, Tray } = require('electron')

let tray = null
app.whenReady().then(() => {
  tray = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' },
    { label: 'Item3', type: 'radio', checked: true },
    { label: 'Item4', type: 'radio' }
  ])
  tray.setToolTip('This is my application.')
  tray.setContextMenu(contextMenu)
})

平台考量

Linux

  • Tray 圖示預設使用 StatusNotifierItem，當使用者的桌面環境中無法使用時，將改用 GtkStatusIcon。
  • 當 tray 圖示收到使用者啟用時，會發出 click 事件，但 StatusNotifierItem 規格並未指定哪個動作會導致啟用，對於某些環境來說，可能是滑鼠左鍵單擊，但對於某些環境來說，可能是滑鼠左鍵雙擊。
  • 為了使對個別 MenuItem 所做的變更生效，您必須再次呼叫 setContextMenu。例如
const { app, Menu, Tray } = require('electron')

let appIcon = null
app.whenReady().then(() => {
  appIcon = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' }
  ])

  // Make a change to the context menu
  contextMenu.items[1].checked = false

  // Call this again for Linux because we modified the context menu
  appIcon.setContextMenu(contextMenu)
})

MacOS

  • 傳遞給 Tray 建構函式的圖示應為範本圖片。
  • 為了確保您的圖示在 Retina 顯示器上不會有顆粒感，請確保您的 @2x 圖片為 144dpi。
  • 如果您正在捆綁您的應用程式（例如，使用 webpack 進行開發），請確保檔案名稱沒有被破壞或雜湊處理。檔案名稱需要以 Template 結尾，且 @2x 圖片需要與標準圖片具有相同的檔案名稱，否則 MacOS 將不會神奇地反轉您圖片的顏色或使用高密度圖片。
  • 16x16 (72dpi) 和 32x32@2x (144dpi) 對於大多數圖示來說效果良好。

Windows

  • 建議使用 ICO 圖示以獲得最佳視覺效果。

new Tray(image, [guid])​

  • image (NativeImage | 字串)
  • guid 字串 (選用) Windows - 將 GUID 指派給 tray 圖示。如果可執行檔已簽署且簽名在主旨行中包含組織，則 GUID 將永久與該簽名關聯。即使可執行檔的路徑變更，作業系統層級設定（例如系統 tray 中 tray 圖示的位置）仍會持續存在。如果可執行檔未進行程式碼簽署，則 GUID 將永久與可執行檔的路徑關聯。變更可執行檔的路徑將會中斷 tray 圖示的建立，且必須使用新的 GUID。但是，強烈建議僅在搭配程式碼簽署的可執行檔時才使用 GUID 參數。如果應用程式定義多個 tray 圖示，則每個圖示都必須使用不同的 GUID。

建立與 image 關聯的新 tray 圖示。

實例事件​

Tray 模組發出以下事件

事件：'click'​

傳回

當 tray 圖示被點擊時發出。

請注意，在 Linux 上，當 tray 圖示收到啟用時，會發出此事件，這不一定是滑鼠左鍵單擊。

事件：'right-click' macOS Windows​

傳回

當 tray 圖示被滑鼠右鍵點擊時發出。

事件：'double-click' macOS Windows​

傳回

當 tray 圖示被滑鼠雙擊時發出。

事件：'middle-click' Windows​

傳回

當 tray 圖示被滑鼠中鍵點擊時發出。

事件：'balloon-show' Windows​

當 tray 提示框顯示時發出。

事件：'balloon-click' Windows​

當 tray 提示框被點擊時發出。

事件：'balloon-closed' Windows​

當 tray 提示框因逾時而關閉或使用者手動關閉時發出。

事件：'drop' macOS​

當任何拖曳的項目被放到 tray 圖示上時發出。

事件：'drop-files' macOS​

傳回

  • event 事件
  • files 字串[] - 已放下檔案的路徑。

當拖曳的檔案被放到 tray 圖示中時發出。

事件：'drop-text' macOS​

傳回

  • event 事件
  • text 字串 - 放下的文字字串。

當拖曳的文字被放到 tray 圖示中時發出。

事件：'drag-enter' macOS​

當拖曳操作進入 tray 圖示時發出。

事件：'drag-leave' macOS​

當拖曳操作離開 tray 圖示時發出。

事件：'drag-end' macOS​

當拖曳操作在 tray 上結束或在另一個位置結束時發出。

事件：'mouse-up' macOS​

傳回

當滑鼠從點擊 tray 圖示後放開時發出。

請注意：如果您已使用 tray.setContextMenu 為您的 Tray 設定關聯選單，則不會發出此事件，這是 macOS 層級的限制所致。

事件：'mouse-down' macOS​

傳回

當滑鼠點擊 tray 圖示時發出。

事件：'mouse-enter' macOS Windows​

傳回

當滑鼠進入 tray 圖示時發出。

事件：'mouse-leave' macOS Windows​

傳回

當滑鼠離開 tray 圖示時發出。

事件：'mouse-move' macOS Windows​

傳回

當滑鼠在 tray 圖示中移動時發出。

實例方法​

Tray 類別具有以下方法

tray.destroy()​

立即銷毀 tray 圖示。

tray.setImage(image)​

設定與此 tray 圖示關聯的 image。

tray.setPressedImage(image) macOS​

設定在 macOS 上按下時與此 tray 圖示關聯的 image。

tray.setToolTip(toolTip)​

  • toolTip 字串

設定此 tray 圖示的懸停文字。

tray.setTitle(title[, options]) macOS​

  • title 字串
  • options 物件 (選用)
    • fontType 字串 (選用) - 要顯示的字型系列變體，可以是 monospaced 或 monospacedDigit。monospaced 在 macOS 10.15+ 中可用。留空時，標題會使用預設系統字型。

設定顯示在狀態列中 tray 圖示旁邊的標題（支援 ANSI 顏色）。

tray.getTitle() macOS​

傳回 string - 狀態列中 tray 圖示旁邊顯示的標題

tray.setIgnoreDoubleClickEvents(ignore) macOS​

  • ignore 布林值

設定選項以忽略雙擊事件。忽略這些事件可讓您偵測 tray 圖示的每個個別點擊。

此值預設設定為 false。

tray.getIgnoreDoubleClickEvents() macOS​

傳回 boolean - 是否將忽略雙擊事件。

tray.displayBalloon(options) Windows​

  • options 物件
    • icon (NativeImage | 字串) (選用) - 當 iconType 為 custom 時要使用的圖示。
    • iconType 字串 (選用) - 可以是 none、info、warning、error 或 custom。預設為 custom。
    • title 字串
    • content 字串
    • largeIcon 布林值 (選用) - 應使用圖示的大型版本。預設為 true。對應到 NIIF_LARGE_ICON。
    • noSound 布林值 (選用) - 不播放關聯的聲音。預設為 false。對應到 NIIF_NOSOUND。
    • respectQuietTime 布林值 (選用) - 如果目前使用者處於「靜音時段」，則不顯示提示框通知。預設為 false。對應到 NIIF_RESPECT_QUIET_TIME。

顯示 tray 提示框。

tray.removeBalloon() Windows​

移除 tray 提示框。

tray.focus() Windows​

將焦點傳回工作列通知區域。當通知區域圖示完成其 UI 操作時，應使用此訊息。例如，如果圖示顯示快速鍵選單，但使用者按下 ESC 取消它，請使用 tray.focus() 將焦點傳回通知區域。

tray.popUpContextMenu([menu, position]) macOS Windows​

  • menu Menu (選用)
  • position Point (選用) - 彈出位置。

彈出 tray 圖示的關聯選單。當傳遞 menu 時，將顯示 menu 而不是 tray 圖示的關聯選單。

position 僅在 Windows 上可用，預設為 (0, 0)。

tray.closeContextMenu() macOS Windows​

關閉由 tray.setContextMenu() 設定的開啟關聯選單。

tray.setContextMenu(menu)​

  • menu Menu | null

設定此圖示的關聯選單。

tray.getBounds() macOS Windows​

傳回 Rectangle

此 tray 圖示的 bounds 作為 Object。

tray.isDestroyed()​

傳回 boolean - tray 圖示是否已銷毀。