メインコンテンツへ飛ぶ

Tray

クラス: Tray​

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

Process: Main

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)
})

[!WARNING] Electron's built-in classes cannot be subclassed in user code. For more information, see the FAQ.

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

Linux

  • Tray アイコンはデフォルトで StatusNotifierItem を使用しますが、これがユーザーのデスクトップ環境で利用できない場合は代わりに 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 (optional) Windows macOS - A unique string used to identify the tray icon. Must adhere to UUID format.

Windows

On Windows, if the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. システム tray の tray アイコンの位置など OS レベルの設定は、実行ファイルのパスが変わっても維持されます。 実行形式がコード署名されていない場合は、GUID が実行形式のパスへ永続的に関連付けられます。 実行形式のパスを変更すると、tray アイコンの作成は破棄され、新しい GUID を使用する必要があります。 ただし、この GUID 引数はコード署名された実行形式のみと組み合わせて使用することを強く推奨します。 アプリが複数の tray アイコンを定義している場合は、それぞれのアイコンで別々の GUID を使用する必要があります。

MacOS

On macOS, the guid is a string used to uniquely identify the tray icon and allow it to retain its position between relaunches. Using the same string for a new tray item will create it in the same position as the previous tray item to use the string.

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] This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.

イベント: '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 アイコンのホバーテキストを設定します。 Setting the text to an empty string will remove the tooltip.

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) (optional) - Icon to use when iconType is 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 (optional) - The pop up position.

tray アイコンのコンテキストメニューをポップアップ表示します。 menu が渡されると、tray アイコンのコンテキストメニューの代わりに menu を表示します。

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

tray.closeContextMenu() macOS Windows​

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

tray.setContextMenu(menu)​

  • menu Menu | null

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

tray.getBounds() macOS Windows​

Returns Rectangle

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

tray.getGUID() macOS Windows​

Returns string | null - The GUID used to uniquely identify the tray icon and allow it to retain its position between relaunches, or null if none is set.

tray.isDestroyed()​

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