メインコンテンツへ飛ぶ

Tray

クラス: Tray​

システムの通知領域にアイコンやコンテキスト メニューを追加します。

プロセス: メイン

Tray は EventEmitter です。

Creating a basic tray menu
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)
})

[!TIP] 参考: Tray メニューの実装方法に関する詳細なガイド。

[!WARNING] Electron 組み込みのクラスはユーザコードでサブクラス化できません。 詳細については、FAQ をご参照ください。

プラットフォームの考慮事項

Linux

  • Tray icon uses StatusNotifierItem by default, when it is not available in user's desktop environment the GtkStatusIcon will be used instead. If StatusNotifierItem is available, the first tray icon created will use SNI, while subsequently-created icons will use GtkStatusIcon.
  • click イベントは Tray アイコンがユーザーに活性化されたときに発生しますが、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' }
  ])

  // コンテキストメニューを変更する
  contextMenu.items[1].checked = false

  // Linux ではコンテキストメニューを変更したのでこれを呼び出し直します
  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 macOS - Tray アイコンの識別に使用する一意な文字列。 UUID 形式に準拠していなければなりません。

Windows

Windows では、実行形式が署名されていて署名の主体者が組織である場合は、GUID がその署名に恒久的に関連付けられます。 システム tray の tray アイコンの位置など OS レベルの設定は、実行ファイルのパスが変わっても維持されます。 実行形式がコード署名されていない場合は、GUID が実行形式のパスへ永続的に関連付けられます。 実行形式のパスを変更すると、tray アイコンの作成は破棄され、新しい GUID を使用する必要があります。 ただし、この GUID 引数はコード署名された実行形式のみと組み合わせて使用することを強く推奨します。 アプリが複数の tray アイコンを定義している場合は、それぞれのアイコンで別々の GUID を使用する必要があります。

MacOS

macOS では、guid は Tray アイコンを一意に識別し、再起動の間で位置を保持するために使用される文字列です。 新しい Tray アイテムに同じ文字列を使用すると、その文字列を使用していた前の Tray アイテムと同じ位置にその文字列が作成されます。

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 Event
  • files string[] - ドロップされたファイルのパス。

tray アイコン上にドラッグされたファイルがドロップされたときに発行されます。

イベント: 'drop-text' macOS​

戻り値:

  • event Event
  • text string - ドロップされたテキスト文字列。

tray アイコン上にドラッグされたテキストがドロップされたときに発行されます。

イベント: 'drag-enter' macOS​

ドラッグ操作が tray アイコン内に入ったときに発行されます。

イベント: 'drag-leave' macOS​

ドラッグ操作が tray アイコン内から出たときに発行されます。

イベント: 'drag-end' macOS​

ドラッグ操作が、tray 上か他の場所で終了したときに発行されます。

イベント: 'mouse-up' macOS​

戻り値:

tray アイコンをクリックしてマウスを離したときに発生します。

[!NOTE] macOS レベルの制約によるもので、tray.setContextMenu で Tray にコンテキストメニューを設定するとこれは発生しません。

イベント: '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 string

この tray アイコンのホバーテキストを設定します。 テキストを空文字列にセットすると、そのツールチップは削除されます。

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

  • title string
  • options Object (任意)
    • fontType string (任意) - 表示するフォントファミリのバリアント。 monospaced または monospacedDigit のどちらかです。 monospaced は macOS 10.15+ で使用可能です。空欄の場合、このタイトルはデフォルトのシステムフォントを使用します。

ステータスバー内の tray アイコンの隣に表示されるタイトル (ANSI カラーサポート) を設定します。

tray.getTitle() macOS​

戻り値 string - ステータスバーの tray アイコンの隣に表示されるタイトル

tray.setIgnoreDoubleClickEvents(ignore) macOS​

  • ignore boolean

ダブルクリックイベントを無視するオプションを設定します。 これらのイベントを無視することで tray アイコンそれぞれの独立したクリックを検知することを許可します。

この値はデフォルトで false にセットされます。

tray.getIgnoreDoubleClickEvents() macOS​

戻り値 boolean - ダブルクリックイベントが無視されているかどうか。

tray.displayBalloon(options) Windows​

  • options Object
    • icon (NativeImage | string) (任意) - iconType が custom のときに使うアイコン。
    • iconType string (任意) - none、info、warning、error、custom のいずれかにできます。 省略値は custom です。
    • title string
    • content string
    • largeIcon boolean (任意) - 大きなバージョンのアイコン。できればこちらを使用します。 省略値は true です。 NIIF_LARGE_ICON に対応します。
    • noSound boolean (任意) - 関連付けられたサウンドを再生しないようにします。 省略値は false です。 NIIF_NOSOUND に対応します。
    • respectQuietTime boolean (任意) - ユーザが現在 "おやすみモード" の場合、バルーン通知を表示しないようにします。 省略値は 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 が渡されると、tray アイコンのコンテキストメニューの代わりに menu を表示します。

position は Windows でのみ有効で、省略値は (0, 0) です。

tray.closeContextMenu() macOS Windows​

tray.setContextMenu() でセットすることで、開かれたコンテキストメニューを閉じます。

tray.setContextMenu(menu)​

  • menu Menu | null

このアイコンのコンテキストメニューを設定します。

tray.getBounds() macOS Windows​

戻り値 Rectangle

Object としてのこの tray アイコンの bounds。

tray.getGUID() macOS Windows​

戻り値 string | null - Tray アイコンを一意に識別し、再起動間でその位置を保持できるようにするために使用される GUID。何も設定されていない場合は null になります。

tray.isDestroyed()​

戻り値 boolean - tray アイコンが破棄されたかどうか。

プラットフォームの考慮事項​

Linux​

  • Tray icon uses StatusNotifierItem by default, when it is not available in user's desktop environment the GtkStatusIcon will be used instead.
  • click イベントは Tray アイコンがユーザーに活性化されたときに発生しますが、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' }
  ])

  // コンテキストメニューを変更する
  contextMenu.items[1].checked = false

  // Linux ではコンテキストメニューを変更したのでこれを呼び出し直します
  appIcon.setContextMenu(contextMenu)
})

macOS​

  • Tray のコンストラクタに渡すアイコンは テンプレート画像 でなければなりません。
  • Retina モニタでアイコンが粗くならないように、@2x の画像は 144dpi にしてください。
  • アプリケーションをバンドルしている場合 (開発用の webpack など)、ファイル名がマングルおよびハッシュ化されないようにしてください。 ファイル名は Template で終わる必要があり、@2x 画像は標準の画像と同じファイル名である必要があります。さもなくば、MacOS は自動で画像の色を反転させたり高密度画像を使用したりしません。
  • 16x16 (72dpi) と 32x32@2x (144dpi) を用意すれば、ほとんどのアイコンでうまく機能します。

Windows​

  • 最適な視覚効果を得るために ICO 形式のアイコンファイルの使用を推奨します。