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

• 系統匣圖示預設使用 StatusNotifierItem，當使用者的桌面環境無法使用時，則會改用 GtkStatusIcon。
• 當系統匣圖示收到使用者觸發時會發出 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 | string)
• guid string (選用) Windows - 將 GUID 指派給系統匣圖示。如果可執行檔已簽署且簽名主旨行包含組織，則 GUID 會永久與該簽名相關聯。即使可執行檔的路徑變更，系統匣圖示在系統匣中的位置等作業系統層級設定仍會保留。如果可執行檔未經過程式碼簽署，則 GUID 會永久與可執行檔的路徑相關聯。變更可執行檔的路徑會中斷系統匣圖示的建立，且必須使用新的 GUID。然而，強烈建議僅在與程式碼簽署的可執行檔搭配使用時才使用 GUID 參數。如果應用程式定義了多個系統匣圖示，則每個圖示都必須使用個別的 GUID。

建立與 image 關聯的新系統匣圖示。

實例事件

Tray 模組會發出下列事件

事件：'click'

返回：

• event KeyboardEvent
• bounds Rectangle - 系統匣圖示的範圍。
• position Point - 事件的位置。

當系統匣圖示被點擊時發出。

請注意，在 Linux 上，當系統匣圖示收到觸發時會發出此事件，這不一定是滑鼠左鍵點擊。

事件：'right-click' macOS Windows

返回：

• event KeyboardEvent
• bounds Rectangle - 系統匣圖示的範圍。

當右鍵點擊系統匣圖示時發出。

事件：'double-click' macOS Windows

返回：

• event KeyboardEvent
• bounds Rectangle - 系統匣圖示的範圍。

當雙擊系統匣圖示時發出。

事件：'middle-click' Windows

返回：

• event KeyboardEvent
• bounds Rectangle - 系統匣圖示的範圍。

當滑鼠中鍵點擊系統匣圖示時發出。

事件：'balloon-show' Windows

當系統匣氣球顯示時發出。

事件：'balloon-click' Windows

當點擊系統匣氣球時發出。

事件：'balloon-closed' Windows

當系統匣氣球因逾時或使用者手動關閉而關閉時發出。

事件：'drop' macOS

當任何拖曳的項目放到系統匣圖示上時發出。

事件：'drop-files' macOS

返回：

• event Event
• files string[] - 拖曳的檔案路徑。

當拖曳的檔案放到系統匣圖示上時發出。

事件：'drop-text' macOS

返回：

• event Event
• text string - 拖曳的文字字串。

當拖曳的文字放到系統匣圖示上時發出。

事件：'drag-enter' macOS

當拖曳作業進入系統匣圖示時發出。

事件：'drag-leave' macOS

當拖曳作業離開系統匣圖示時發出。

事件：'drag-end' macOS

當拖曳作業在系統匣上結束或在其他位置結束時發出。

事件：'mouse-up' macOS

返回：

• event KeyboardEvent
• position Point - 事件的位置。

當滑鼠從點擊系統匣圖示釋放時發出。

注意：如果您已使用 tray.setContextMenu 為您的系統匣設定關聯選單，則不會發出此訊息，這是由於 macOS 層級的限制所致。

事件：'mouse-down' macOS

返回：

• event KeyboardEvent
• position Point - 事件的位置。

當滑鼠點擊系統匣圖示時發出。

事件：'mouse-enter' macOS Windows

返回：

• event KeyboardEvent
• position Point - 事件的位置。

當滑鼠進入系統匣圖示時發出。

事件：'mouse-leave' macOS Windows

返回：

• event KeyboardEvent
• position Point - 事件的位置。

當滑鼠離開系統匣圖示時發出。

事件：'mouse-move' macOS Windows

返回：

• event KeyboardEvent
• position Point - 事件的位置。

當滑鼠在系統匣圖示中移動時發出。

實例方法

Tray 類別具有下列方法

tray.destroy()

立即銷毀系統匣圖示。

tray.setImage(image)

• image (NativeImage | string)

設定與此系統匣圖示關聯的 image。

tray.setPressedImage(image) macOS

• image (NativeImage | string)

在 macOS 上按下時，設定與此系統匣圖示關聯的 image。

tray.setToolTip(toolTip)

• toolTip string

設定此系統匣圖示的懸停文字。

tray.setTitle(title[, options]) macOS

• title string
• options Object (選用)
  • fontType 字串 (選填) - 要顯示的字體變體，可以是 monospaced 或 monospacedDigit。monospaced 在 macOS 10.15+ 版本可用。如果留空，標題將使用預設的系統字體。

設定在狀態列中托盤圖示旁邊顯示的標題 (支援 ANSI 顏色)。

tray.getTitle() macOS

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

tray.setIgnoreDoubleClickEvents(ignore) macOS

• ignore 布林值

設定是否忽略雙擊事件的選項。忽略這些事件可讓您偵測托盤圖示的每一次單擊。

此值預設為 false。

tray.getIgnoreDoubleClickEvents() macOS

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

tray.displayBalloon(options) Windows

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

顯示托盤氣球。

tray.removeBalloon() Windows

移除托盤氣球。

tray.focus() Windows

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

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

• menu 選單 (選填)
• position Point (選填) - 彈出位置。

彈出托盤圖示的內容選單。當傳入 menu 時，將顯示 menu 而不是托盤圖示的內容選單。

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

tray.closeContextMenu() macOS Windows

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

tray.setContextMenu(menu)

• menu 選單 | null

設定此圖示的內容選單。

tray.getBounds() macOS Windows

回傳 Rectangle

此托盤圖示的 bounds (邊界) 為 Object。

tray.isDestroyed()

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