Системный трей и док-панель

Deno.Tray помещает значок в системную область уведомлений (дополнительные элементы строки меню в macOS, системный трей в Windows, AppIndicator в Linux). Deno.dock — это синглтон, управляющий отображением приложения в док-панели / на панели задач: значком-уведомлением, анимацией, видимостью и пользовательским меню.

В обоих случаях меню использует тип Deno.MenuItem.

Deno.Tray

const icon = await Deno.readFile("./icons/tray.png");

const tray = new Deno.Tray();
tray.setIcon(icon);
tray.setTooltip("My App");

tray.setMenu([
  { item: { label: "Open", id: "open", enabled: true } },
  { item: { label: "Quit", id: "quit", enabled: true } },
]);

tray.addEventListener("menuclick", (e) => {
  if (e.detail.id === "open") win.show();
  if (e.detail.id === "quit") Deno.exit(0);
});

Жизненный цикл

Значок остается в системной области уведомлений, пока вы не вызовете tray.destroy() (или пока процесс не завершится). Можно создать несколько значков, что удобно для индикаторов приложений, которым нужны отдельные элементы управления.

tray.destroy();

Tray также является Disposable, поэтому его можно использовать с using:

{
  using tray = new Deno.Tray();
  // ...
} // automatically destroyed at scope exit

Настройка значка

tray.setIcon(pngBytes); // bytes, not a path
tray.setIconDark(darkPngBytes); // optional dark-mode variant
tray.setIconDark(null); // clear the dark icon

Передавайте байты в формате PNG, а не путь к файлу. Прочитайте файл самостоятельно:

const png = await Deno.readFile("./icons/tray.png");
tray.setIcon(png);

Укажите отдельный значок для темного режима с помощью setIconDark, если нужен контрастный вариант для темных строк меню (macOS 10.14+, современные дистрибутивы Linux). Если отдельный значок не указан, в обоих режимах используется один и тот же.

Для наилучшего результата используйте изображение в стиле шаблона (преимущественно непрозрачный силуэт с прозрачным фоном) небольшого размера: 22×22 логических пикселя для macOS, 16×16 для Windows.

Всплывающая подсказка

tray.setTooltip("My App: 3 unread");
tray.setTooltip(null); // remove tooltip

Контекстное меню

Щелчок правой кнопкой мыши по значку в системном трее открывает меню, заданное с помощью setMenu. Элементы имеют ту же структуру Deno.MenuItem, что и меню приложения и контекстные меню:

tray.setMenu([
  { item: { label: "Open", id: "open", enabled: true } },
  "separator",
  {
    item: {
      label: "Settings…",
      id: "settings",
      accelerator: "CmdOrCtrl+,",
      enabled: true,
    },
  },
  "separator",
  {
    item: {
      label: "Quit",
      id: "quit",
      accelerator: "CmdOrCtrl+Q",
      enabled: true,
    },
  },
]);

tray.addEventListener("menuclick", (e) => {
  switch (e.detail.id) {
    case "open":
      win.show();
      break;
    case "settings":
      showSettings();
      break;
    case "quit":
      Deno.exit(0);
      break;
  }
});

tray.setMenu(null); // remove the menu without destroying the tray

Подменю работают так же, как в меню приложения.

События щелчка

tray.addEventListener("click", () => win.show());
tray.addEventListener("dblclick", () => openSettings());

Событие click возникает при щелчке основной кнопкой мыши. Событие dblclick возникает при двойном щелчке. На платформах, где щелчок правой кнопкой мыши используется для открытия контекстного меню (то есть везде), эти события вызываются только при щелчке левой кнопкой.

Всплывающие панели

Чтобы реализовать классический сценарий приложения в строке меню, щелкайте по значку в системном трее, чтобы открывать и закрывать небольшое плавающее окно под ним, а затем используйте attachPanel():

const tray = new Deno.Tray();
tray.setIcon(await Deno.readFile("./icons/tray.png"));

const panel = tray.attachPanel({
  url: `http://127.0.0.1:${port}/panel`,
  width: 360,
  height: 480,
});

panel.window.bind("doThing", async () => {/* … */});

Возвращаемый объект Deno.TrayPanel переключает видимость панели при щелчке по значку, отображается под ним и скрывается при потере фокуса. Строку можно передать как сокращенную запись для { url }. TrayPanelOptions также принимает hideOnBlur (по умолчанию — true) и функцию обратного вызова position для переопределения расположения (например, для панели задач, расположенной у нижнего края экрана).

panel.show();
panel.hide();
panel.toggle();
console.log(panel.visible);
panel.destroy(); // detach and close the panel window
panel.window; // the underlying BrowserWindow: bind(), executeJs(), etc.

Панель — это удобная обертка над базовыми средствами. Для полного контроля создайте собственные frameless + noActivate BrowserWindow и задайте их расположение с помощью Tray.getBounds():

const bounds = tray.getBounds(); // { x, y, width, height } | null
if (bounds) {
  popover.setPosition(bounds.x, bounds.y + bounds.height);
  popover.show();
}

getBounds() возвращает экранный прямоугольник значка или null, если платформа не может сообщить его координаты. В Linux нельзя получить координаты значка, поэтому прикрепленная панель отображается в прежнем месте, а не рядом со значком.

Поддержка платформ

Значки системного трея зависят от наличия в ОС области уведомлений. Соответствующие бэкенды поддерживают системный трей в следующих системах:

• macOS: элементы меню состояния (NSStatusItem).
• Windows: системный трей (NotifyIcon).
• Linux: AppIndicator / KStatusNotifierItem. Требуется среда рабочего стола, в которой они отображаются. Большинство сред это поддерживает, но в некоторых минимальных конфигурациях i3 могут понадобиться дополнительные компоненты, такие как swaync, или настройка polybar.

Если бэкенд не может создать значок в системном трее, базовый trayId конструктора будет равен 0, а последующие вызовы не будут выполнять никаких действий (без предупреждения). Проверьте tray.trayId !== 0, если нужно предусмотреть корректный альтернативный вариант.

Deno.dock

Deno.dock — это синглтон, предоставляющий средства управления док-панелью / панелью задач приложения. Методы доступны на разных платформах, но работают по-разному: операции, предназначенные только для macOS, ничего не делают в Windows и Linux (они завершаются без ошибок, а не вызывают исключение).

Значок-уведомление

Deno.dock.setBadge("3"); // short text on the dock / taskbar icon
Deno.dock.setBadge(null); // clear (null or empty string)

Устанавливает текстовый значок на значке док-панели (macOS) или панели задач (Windows); в Linux добавляет его в начало заголовка окна в фокусе. Значки обычно короткие, например, отображают количество; ОС обрезает длинные строки.

Анимация

Deno.dock.bounce(); // single bounce / flash
Deno.dock.bounce(true); // bounce continuously until the app is focused

Запускает анимацию значка док-панели (macOS), мигает кнопкой на панели задач (Windows) или устанавливает признак срочности для окна в фокусе (Linux). Необязательный аргумент critical (по умолчанию — false) определяет, будет ли анимация однократной или непрерывной.

Видимость

Deno.dock.setVisible(false); // remove the app from the dock
Deno.dock.setVisible(true); // restore it

Только для macOS; управляет политикой активации приложения. Скрытое приложение не отображается в док-панели или переключателе окон Cmd-Tab — именно это нужно приложению, работающему только в строке меню. Приложение продолжает работать и может по-прежнему показывать окна; пользователи могут открыть его через Spotlight или значок в системном трее. В Windows и Linux метод ничего не делает.

Меню

Deno.dock.setMenu([
  { item: { label: "New Window", id: "new", enabled: true } },
  { item: { label: "Quit", id: "quit", enabled: true } },
]);
Deno.dock.setMenu(null); // remove the menu

Deno.dock.addEventListener("menuclick", (e) => {
  if (e.detail.id === "quit") Deno.exit(0);
});

Только для macOS; пользовательское меню, открывающееся щелчком правой кнопкой мыши по значку в док-панели. Щелчки передаются как события menuclick объекту Deno.dock.

Событие повторного открытия

В macOS щелчок по значку в док-панели, когда у приложения нет видимых окон, вызывает событие reopen. Стандартное поведение «показать последнее скрытое окно» подавляется, поэтому вы сами решаете, что делать:

Deno.dock.addEventListener("reopen", (e) => {
  if (!e.detail.hasVisibleWindows) win.show();
});

Сценарий: фоновое приложение только со значком в системном трее

Чтобы запустить фоновый процесс, отображаемый только в системной области уведомлений (без док-панели и главного окна):

Deno.dock.setVisible(false); // macOS: hide the app from the dock
win.hide(); // hide the implicit startup window

const tray = new Deno.Tray();
tray.setIcon(await Deno.readFile("./icons/tray.png"));
tray.setTooltip("My App");
tray.setMenu([
  { item: { label: "Show window", id: "show", enabled: true } },
  { item: { label: "Quit", id: "quit", enabled: true } },
]);

tray.addEventListener("menuclick", (e) => {
  if (e.detail.id === "show") win.show();
  if (e.detail.id === "quit") Deno.exit(0);
});

Стартовое окно создается при запуске двоичного файла; скрыв его, вы сможете показывать окно позднее без задержки на запуск.