Skip to main content

任务栏定制

🌐 Taskbar Customization

概述​

🌐 Overview

Electron 提供了用于在 Windows 任务栏中配置应用图标的 API。该 API 支持仅限 Windows 的功能，例如 创建 JumpList、自定义缩略图和工具栏、图标叠加 以及所谓的 “闪烁窗口”效果，同时也支持跨平台功能，如 最近的文件 和 申请进展。

🌐 Electron has APIs to configure the app's icon in the Windows taskbar. This API supports both Windows-only features like creation of a JumpList, custom thumbnails and toolbars, icon overlays, and the so-called "Flash Frame" effect, and cross-platform features like recent documents and application progress.

JumpList​

Windows 允许应用定义自定义的上下文菜单，当用户在任务栏上右键单击应用图标时会显示该菜单。该上下文菜单称为 JumpList。你可以在 JumpList 的 Tasks 类别中指定自定义操作，如从 MSDN 引用：

🌐 Windows allows apps to define a custom context menu that shows up when users right-click the app's icon in the taskbar. That context menu is called JumpList. You specify custom actions in the Tasks category of JumpList, as quoted from MSDN:

Applications define tasks based on both the program's features and the key things a user is expected to do with them. Tasks should be context-free, in that the application does not need to be running for them to work. They should also be the statistically most common actions that a normal user would perform in an application, such as compose an email message or open the calendar in a mail program, create a new document in a word processor, launch an application in a certain mode, or launch one of its subcommands. An application should not clutter the menu with advanced features that standard users won't need or one-time actions such as registration. Do not use tasks for promotional items such as upgrades or special offers.

It is strongly recommended that the task list be static. It should remain the same regardless of the state or status of the application. While it is possible to vary the list dynamically, you should consider that this could confuse the user who does not expect that portion of the destination list to change.

Taskbar JumpList

注意：上面的截图是 Microsoft Edge 一般任务的示例

与 macOS 中真正的菜单栏不同，Windows 中的用户任务更像是应用快捷方式。例如，当用户点击一个任务时，程序将以指定的参数执行。

🌐 Unlike the dock menu in macOS which is a real menu, user tasks in Windows work like application shortcuts. For example, when a user clicks a task, the program will be executed with specified arguments.

要为你的应用设置用户任务，你可以使用 app.setUserTasks API。

🌐 To set user tasks for your application, you can use app.setUserTasks API.

示例​

🌐 Examples

设置用户任务​

🌐 Set user tasks

从 教程入门代码 的一个可用应用开始，用以下几行更新 main.js 文件：

🌐 Starting with a working application from the tutorial starter code, update the main.js file with the following lines:

const { app } = require('electron')

app.setUserTasks([
  {
    program: process.execPath,
    arguments: '--new-window',
    iconPath: process.execPath,
    iconIndex: 0,
    title: 'New Window',
    description: 'Create a new window'
  }
])
清除任务列表​

🌐 Clear tasks list

要清空你的任务列表，你需要在 main.js 文件中调用 app.setUserTasks 并传入一个空数组。

🌐 To clear your tasks list, you need to call app.setUserTasks with an empty array in the main.js file.

const { app } = require('electron')

app.setUserTasks([])

注意：即使关闭你的应用，用户任务仍会显示，因此为任务指定的图标和程序路径应一直存在，直到你的应用被卸载。

缩略图工具栏​

🌐 Thumbnail Toolbars

在 Windows 上，你可以向应用窗口的任务栏布局添加带有指定按钮的缩略图工具栏。它为用户提供了一种在不恢复或激活窗口的情况下访问特定窗口命令的方式。

🌐 On Windows, you can add a thumbnail toolbar with specified buttons to a taskbar layout of an application window. It provides users with a way to access a particular window's command without restoring or activating the window.

引用MSDN的话：

🌐 As quoted from MSDN:

此工具栏是熟悉的标准工具栏常用控件。它最多可以包含七个按钮。每个按钮的 ID、图片、工具提示和状态都在一个结构中定义，然后传递给任务栏。应用可以根据当前状态显示、启用、禁用或隐藏缩略图工具栏上的按钮。

例如，Windows Media Player 可能会提供标准的媒体传输控制按钮，如播放、暂停、静音和停止。

Thumbnail toolbar

注意：上面的截图是 Windows Media Player 缩略图工具栏的示例

要在你的应用中设置缩略图工具栏，你需要使用 BrowserWindow.setThumbarButtons

🌐 To set thumbnail toolbar in your application, you need to use BrowserWindow.setThumbarButtons

示例​

🌐 Examples

设置缩略图工具栏​

🌐 Set thumbnail toolbar

从 教程入门代码 的一个可用应用开始，用以下几行更新 main.js 文件：

🌐 Starting with a working application from the tutorial starter code, update the main.js file with the following lines:

const { BrowserWindow, nativeImage } = require('electron')

const path = require('node:path')

const win = new BrowserWindow()

win.setThumbarButtons([
  {
    tooltip: 'button1',
    icon: nativeImage.createFromPath(path.join(__dirname, 'button1.png')),
    click () { console.log('button1 clicked') }
  }, {
    tooltip: 'button2',
    icon: nativeImage.createFromPath(path.join(__dirname, 'button2.png')),
    flags: ['enabled', 'dismissonclick'],
    click () { console.log('button2 clicked.') }
  }
])
清除缩略图工具栏​

🌐 Clear thumbnail toolbar

要清除缩略图工具栏按钮，你需要在 main.js 文件中调用 BrowserWindow.setThumbarButtons 并传入一个空数组。

🌐 To clear thumbnail toolbar buttons, you need to call BrowserWindow.setThumbarButtons with an empty array in the main.js file.

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()
win.setThumbarButtons([])

任务栏中的图标叠加​

🌐 Icon Overlays in Taskbar

在 Windows 上，任务栏按钮可以使用小型覆盖图来显示应用状态。

🌐 On Windows, a taskbar button can use a small overlay to display application status.

引用MSDN的话：

🌐 As quoted from MSDN:

图标覆盖层作为状态的上下文通知，旨在消除需要在单独的通知区域状态图标中向用户传达该信息的需求。例如，当前在通知区域显示的 Microsoft Outlook 新邮件状态，现在可以通过任务栏按钮上的覆盖图标来指示。同样地，你必须在开发周期中决定哪种方法最适合你的应用。覆盖图标旨在提供重要的、长期存在的状态或通知，例如网络状态、即时消息状态或新邮件状态。用户不应看到不断变化的覆盖或动画。

Overlay on taskbar button

注意：上方的截图是任务栏按钮叠加的示例

要为窗口设置覆盖图标，你需要使用 BrowserWindow.setOverlayIcon API。

🌐 To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.

示例​

🌐 Example

从 教程入门代码 的一个可用应用开始，用以下几行更新 main.js 文件：

🌐 Starting with a working application from the tutorial starter code, update the main.js file with the following lines:

const { BrowserWindow, nativeImage } = require('electron')

const win = new BrowserWindow()

win.setOverlayIcon(nativeImage.createFromPath('path/to/overlay.png'), 'Description for overlay')

闪光帧​

🌐 Flash Frame

在 Windows 上，你可以高亮任务栏按钮来吸引用户的注意。这类似于 macOS 中弹跳 Dock 图标的效果。

🌐 On Windows, you can highlight the taskbar button to get the user's attention. This is similar to bouncing the dock icon in macOS.

引用MSDN的话：

🌐 As quoted from MSDN:

通常，窗口会闪烁以提醒用户该窗口需要注意，但它当前没有键盘焦点。

要闪烁 BrowserWindow 的任务栏按钮，你需要使用 BrowserWindow.闪烁窗口 API。

🌐 To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.

示例​

🌐 Example

从 教程入门代码 的一个可用应用开始，用以下几行更新 main.js 文件：

🌐 Starting with a working application from the tutorial starter code, update the main.js file with the following lines:

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

win.once('focus', () => win.flashFrame(false))
win.flashFrame(true)

注意：别忘了调用 win.flashFrame(false) 来关闭闪光灯。 在上述示例中，它是在窗口获得焦点时调用的， 但你也可以使用超时或其他事件来禁用它。