mirror of
https://github.com/electron/electron.git
synced 2026-10-28 11:44:46 +08:00
Samuel AttardandClaude
ad3a896a52
* build: check the formatting of docs code blocks with oxfmt lint-roller 4 splits the old `lint-roller-markdown-standard` into an oxlint half and an oxfmt half. This wires up the second one: `lint:fmt-in-markdown` runs `lint-roller-markdown-oxfmt` over docs/ as part of `lint:docs`, using docs/.oxfmtrc.json, which matches the repo's .oxfmtrc.json except that docs snippets keep their semicolon-free style. `--fix` writes the formatted blocks back, and a block can opt out with `@noformat` in its info string. * docs: format code blocks with oxfmt Result of `lint-roller-markdown-oxfmt --fix` with docs/.oxfmtrc.json, plus the @ts-expect-error line anchors (and one Docusaurus highlight marker) that moved with the reformat. The Babel output sample in the ESM guide and the two excerpts of repo source in creating-api.md are marked @noformat, and the contentTracing example passes an async callback instead of wrapping an IIFE so that it does not need a leading semicolon. --------- Co-authored-by: Claude <noreply@anthropic.com>
80 lines
2.7 KiB
Markdown
80 lines
2.7 KiB
Markdown
---
|
|
title: Dock Menu
|
|
description: Configure your app's Dock presence on macOS.
|
|
slug: macos-dock
|
|
hide_title: true
|
|
---
|
|
|
|
# Dock Menu
|
|
|
|
On macOS, the [Dock](https://support.apple.com/en-ca/guide/mac-help/mh35859/mac) is an interface
|
|
element that displays open and frequently-used apps. While opened or pinned, each app has its own
|
|
icon in the Dock.
|
|
|
|
> [!NOTE]
|
|
> On macOS, the Dock is the entry point for certain cross-platform features like
|
|
> [Recent Documents](./recent-documents.md) and [Application Progress](./progress-bar.md).
|
|
> Read those guides for more details.
|
|
|
|
## Dock API
|
|
|
|
All functionality for the Dock is exposed via the [Dock](../api/dock.md) class exposed via
|
|
[`app.dock`](../api/app.md#appdock-macos-readonly) property. There is a single `Dock` instance per
|
|
Electron application, and this property only exists on macOS.
|
|
|
|
One of the main uses for your app's Dock icon is to expose additional app menus. The Dock menu is
|
|
triggered by right-clicking or <kbd>Ctrl</kbd>-clicking the app icon. By default, the app's Dock menu
|
|
will come with system-provided window management utilities, including the ability to show all windows,
|
|
hide the app, and switch between different open windows.
|
|
|
|
To set an app-defined custom Dock menu, pass any [Menu](../api/menu.md) instance into the
|
|
[`dock.setMenu`](../api/dock.md#docksetmenumenu-macos) API.
|
|
|
|
> [!NOTE]
|
|
> A [`badge`](../api/menu-item.md#menuitembadge-macos) on a `MenuItem` is not displayed in a Dock
|
|
> menu, though the same item shows it in an application menu.
|
|
|
|
> [!TIP]
|
|
> For best practices to make your Dock menu feel more native, see Apple's
|
|
> [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/dock-menus)
|
|
> page on Dock menus.
|
|
|
|
## Attaching a context menu
|
|
|
|
```js title='Setting a Dock menu'
|
|
const { app, BrowserWindow, Menu } = require('electron/main')
|
|
|
|
// dock.setMenu only works after the 'ready' event is fired
|
|
app.whenReady().then(() => {
|
|
const dockMenu = Menu.buildFromTemplate([
|
|
{
|
|
label: 'New Window',
|
|
click: () => {
|
|
const win = new BrowserWindow()
|
|
}
|
|
}
|
|
// add more menu options to the array
|
|
])
|
|
|
|
// Dock is undefined on platforms outside of macOS
|
|
// highlight-next-line
|
|
app.dock?.setMenu(dockMenu)
|
|
})
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Unlike with regular [context menus](./context-menu.md), Dock context menus don't need to be
|
|
> manually instrumented using the `menu.popup` API. Instead, the Dock object handles click events
|
|
> for you.
|
|
|
|
> [!TIP]
|
|
> To learn more about crafting menus in Electron, see the [Menus](./menus.md#building-menus) guide.
|
|
|
|
## Runnable Fiddle demo
|
|
|
|
Below is a runnable example of how you can use the Dock menu to create and close windows in your
|
|
Electron app.
|
|
|
|
```fiddle docs/fiddles/menus/dock-menu
|
|
```
|