mirror of
https://github.com/electron/electron.git
synced 2026-04-10 03:01:51 -04:00
docs: add Menu module tutorials (#47761)
* docs: add `Menu` module tutorials * link API docs to new tutorials * removed unreferenced fiddles * add wording for new types * fix import sort errors * delete accelerator.md * fixes Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com> Co-authored-by: Erick Zhao <ezhao@slack-corp.com>
This commit is contained in:
trop[bot]
@@ -1,83 +1,86 @@
|
||||
---
|
||||
title: Tray
|
||||
description: This guide will take you through the process of creating
|
||||
a Tray icon with its own context menu to the system's notification area.
|
||||
title: Tray Menu
|
||||
description: Create a Tray icon with its own menu in the system's notification area.
|
||||
slug: tray
|
||||
hide_title: true
|
||||
---
|
||||
|
||||
# Tray
|
||||
# Tray Menu
|
||||
|
||||
## Overview
|
||||
This guide will take you through the process of creating an icon with its own context menu to the
|
||||
system tray.
|
||||
|
||||
<!-- ✍ Update this section if you want to provide more details -->
|
||||
* On macOS, the icon will be located on the top right corner of your screen in the
|
||||
[menu bar extras](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#Menu-bar-extras)
|
||||
area.
|
||||
* On Windows, the icon will be located in the [notification area](https://learn.microsoft.com/en-us/windows/win32/shell/notification-area)
|
||||
at the end of the taskbar.
|
||||
* On Linux, the location of the Tray will differ based on your desktop environment.
|
||||
|
||||
This guide will take you through the process of creating a
|
||||
[Tray](../api/tray.md) icon with
|
||||
its own context menu to the system's notification area.
|
||||
## Creating a Tray icon
|
||||
|
||||
On MacOS and Ubuntu, the Tray will be located on the top
|
||||
right corner of your screen, adjacent to your battery and wifi icons.
|
||||
On Windows, the Tray will usually be located in the bottom right corner.
|
||||
The tray icon for your Electron app needs to be created programmatically with an instance of
|
||||
the [Tray](../api/tray.md#new-trayimage-guid) class. The class constructor requires a single
|
||||
instance of a [NativeImage](../api/native-image.md#class-nativeimage) or a path to a compatible icon
|
||||
file.
|
||||
|
||||
## Example
|
||||
> [!NOTE]
|
||||
> File formats vary per operating system. For more details, see the
|
||||
> [Platform Considerations](../api/tray.md#platform-considerations) section of the Tray API documentation.
|
||||
|
||||
### main.js
|
||||
## Minimizing to tray
|
||||
|
||||
First we must import `app`, `Tray`, `Menu`, `nativeImage` from `electron`.
|
||||
In order to keep the app and the system tray icon alive even when all windows are closed, you need to
|
||||
have a listener for the [`window-all-closed`](../api/app.md#event-window-all-closed) event on the
|
||||
`app` module. The base Electron templates generally listen for this event but quit the app on
|
||||
Windows and Linux to emulate standard OS behavior.
|
||||
|
||||
```js
|
||||
const { app, Tray, Menu, nativeImage } = require('electron')
|
||||
```
|
||||
|
||||
Next we will create our Tray. To do this, we will use a
|
||||
[`NativeImage`](../api/native-image.md) icon,
|
||||
which can be created through any one of these
|
||||
[methods](../api/native-image.md#methods).
|
||||
Note that we wrap our Tray creation code within an
|
||||
[`app.whenReady`](../api/app.md#appwhenready)
|
||||
as we will need to wait for our electron app to finish initializing.
|
||||
|
||||
```js title='main.js'
|
||||
let tray
|
||||
|
||||
app.whenReady().then(() => {
|
||||
const icon = nativeImage.createFromPath('path/to/asset.png')
|
||||
tray = new Tray(icon)
|
||||
|
||||
// note: your contextMenu, Tooltip and Title code will go here!
|
||||
```js title='Setting up minimize to tray'
|
||||
app.on('window-all-closed', () => {
|
||||
// having this listener active will prevent the app from quitting.
|
||||
})
|
||||
```
|
||||
|
||||
Great! Now we can start attaching a context menu to our Tray, like so:
|
||||
## Attaching a context menu
|
||||
|
||||
```js @ts-expect-error=[8]
|
||||
const contextMenu = Menu.buildFromTemplate([
|
||||
{ label: 'Item1', type: 'radio' },
|
||||
{ label: 'Item2', type: 'radio' },
|
||||
{ label: 'Item3', type: 'radio', checked: true },
|
||||
{ label: 'Item4', type: 'radio' }
|
||||
])
|
||||
You can attach a context menu to the Tray object by passing in a [Menu](../api/menu.md) instance
|
||||
into the [`tray.setContextMenu`](../api/tray.md#traysetcontextmenumenu) function.
|
||||
|
||||
tray.setContextMenu(contextMenu)
|
||||
> [!NOTE]
|
||||
> Unlike with regular [context menus](./context-menu.md), Tray context menus don't need to be
|
||||
> manually instrumented using the `menu.popup` API. Instead, the Tray object handles click events
|
||||
> for you (although various click-related events exist on the API for advanced use cases).
|
||||
|
||||
```js title='Creating a Tray menu that can quit the app'
|
||||
const { nativeImage } = require('electron/common')
|
||||
const { app, Tray, Menu } = require('electron/main')
|
||||
|
||||
// save a reference to the Tray object globally to avoid garbage collection
|
||||
let tray
|
||||
|
||||
// 16x16 red circle data URL
|
||||
const icon = nativeImage.createFromDataURL('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACTSURBVHgBpZKBCYAgEEV/TeAIjuIIbdQIuUGt0CS1gW1iZ2jIVaTnhw+Cvs8/OYDJA4Y8kR3ZR2/kmazxJbpUEfQ/Dm/UG7wVwHkjlQdMFfDdJMFaACebnjJGyDWgcnZu1/lrCrl6NCoEHJBrDwEr5NrT6ko/UV8xdLAC2N49mlc5CylpYh8wCwqrvbBGLoKGvz8Bfq0QPWEUo/EAAAAASUVORK5CYII=')
|
||||
|
||||
// The Tray can only be instantiated after the 'ready' event is fired
|
||||
app.whenReady().then(() => {
|
||||
tray = new Tray(icon)
|
||||
const contextMenu = Menu.buildFromTemplate([
|
||||
{ role: 'quit' }
|
||||
])
|
||||
tray.setContextMenu(contextMenu)
|
||||
})
|
||||
```
|
||||
|
||||
The code above will create 4 separate radio-type items in the context menu.
|
||||
To read more about constructing native menus, click
|
||||
[here](../api/menu.md#menubuildfromtemplatetemplate).
|
||||
> [!TIP]
|
||||
> To learn more about crafting menus in Electron, see the [Menus](./menus.md#building-menus) guide.
|
||||
|
||||
Finally, let's give our tray a tooltip and a title.
|
||||
> [!WARNING]
|
||||
> The `enabled` and `visibility` properties are not available for top-level menu items in the tray on macOS.
|
||||
|
||||
```js @ts-type={tray:Electron.Tray}
|
||||
tray.setToolTip('This is my application')
|
||||
tray.setTitle('This is my title')
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
After you start your electron app, you should see the Tray residing
|
||||
in either the top or bottom right of your screen, depending on your
|
||||
operating system.
|
||||
|
||||
```fiddle docs/fiddles/native-ui/tray
|
||||
## Runnable Fiddle demo
|
||||
|
||||
Below is a runnable example of attaching various menu items to the Tray's context menu that help
|
||||
control app state and interact with the Tray API itself.
|
||||
|
||||
```fiddle docs/fiddles/menus/tray-menu
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user