Bandeja del Sistema (System Tray)

Tauri te permite crear y personalizar una bandeja del sistema para tu aplicación. Esto puede mejorar la experiencia del usuario al proporcionar un acceso rápido a acciones comunes.

Configuración

En primer lugar, actualiza tu Cargo.toml para incluir la feature necesaria para la bandeja del sistema.

src-tauri/Cargo.toml

tauri = { version = "2.0.0", features = [ "tray-icon" ] }

Uso

La API de la bandeja del sistema está disponible tanto en JavaScript como en Rust.

Crear un Ícono de Bandeja

JavaScript

Usa la función estática TrayIcon.new para crear un nuevo ícono de bandeja:

import { TrayIcon } from '@tauri-apps/api/tray';

const options = {
  // here you can add a tray menu, title, tooltip, event handler, etc
};

const tray = await TrayIcon.new(options);

Consulta TrayIconOptions para obtener más información sobre las opciones de personalización.

Rust

use tauri::tray::TrayIconBuilder;

tauri::Builder::default()
    .setup(|app| {
        let tray = TrayIconBuilder::new().build(app)?;
        Ok(())
    })

Consulta TrayIconBuilder para obtener más información sobre las opciones de personalización.

Cambiar el Ícono de Bandeja

Al crear la bandeja puedes usar el ícono de la aplicación como el ícono de la bandeja:

JavaScript

import { TrayIcon } from '@tauri-apps/api/tray';
import { defaultWindowIcon } from '@tauri-apps/api/app';

const options = {
  icon: await defaultWindowIcon(),
};

const tray = await TrayIcon.new(options);

Rust

let tray = TrayIconBuilder::new()
  .icon(app.default_window_icon().unwrap().clone())
  .build(app)?;

Agregar un Menú

Para adjuntar un menú que se muestre al hacer clic en la bandeja, puedes usar la opción menu.

Nota

Por defecto el menú se muestra tanto al hacer clic izquierdo como derecho.

Para evitar que el menú aparezca al hacer clic izquierdo, llama a la función de Rust show_menu_on_left_click(false) o establece la opción de JavaScript menuOnLeftClick en false.

JavaScript

import { TrayIcon } from '@tauri-apps/api/tray';
import { Menu } from '@tauri-apps/api/menu';

const menu = await Menu.new({
  items: [
    {
      id: 'quit',
      text: 'Quit',
    },
  ],
});

const options = {
  menu,
  menuOnLeftClick: true,
};

const tray = await TrayIcon.new(options);

Rust

use tauri::{
  menu::{Menu, MenuItem},
  tray::TrayIconBuilder,
};

let quit_i = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;
let menu = Menu::with_items(app, &[&quit_i])?;

let tray = TrayIconBuilder::new()
  .menu(&menu)
  .show_menu_on_left_click(true)
  .build(app)?;

Escuchar Eventos del Menú

JavaScript

En JavaScript puedes adjuntar un escuchador de eventos de clic directamente al elemento del menú:

• Usando un manejador de clic de menú compartido

  import { Menu } from '@tauri-apps/api/menu';
  
  function onTrayMenuClick(itemId) {
    // itemId === 'quit'
  }
  
  const menu = await Menu.new({
    items: [
      {
        id: 'quit',
        text: 'Quit',
        action: onTrayMenuClick,
      },
    ],
  });

• Usando un manejador de clic de menú dedicado

  import { Menu } from '@tauri-apps/api/menu';
  
  const menu = await Menu.new({
    items: [
      {
        id: 'quit',
        text: 'Quit',
        action: () => {
          console.log('quit pressed');
        },
      },
    ],
  });

Rust

Usa el método TrayIconBuilder::on_menu_event para adjuntar un escuchador de eventos de clic del menú de la bandeja:

use tauri::tray::TrayIconBuilder;

TrayIconBuilder::new()
  .on_menu_event(|app, event| match event.id.as_ref() {
    "quit" => {
      println!("quit menu item was clicked");
      app.exit(0);
    }
    _ => {
      println!("menu item {:?} not handled", event.id);
    }
  })

Escuchar Eventos de la Bandeja

El ícono de la bandeja emite eventos para los siguientes eventos del mouse:

• click: se activa cuando el cursor recibe un solo clic izquierdo, derecho o central, incluyendo información sobre si la presión del mouse fue liberada o no
• Double click: se activa cuando el cursor recibe un doble clic izquierdo, derecho o central
• Enter: se activa cuando el cursor entra en el área del ícono de la bandeja
• Move: se activa cuando el cursor se mueve alrededor del área del ícono de la bandeja
• Leave: se activa cuando el cursor sale del área del ícono de la bandeja

Nota

Linux: No soportado. El evento no se emite aunque el ícono se muestre y seguirá mostrando un menú contextual al hacer clic derecho.

JavaScript

import { TrayIcon } from '@tauri-apps/api/tray';

const options = {
  action: (event) => {
    switch (event.type) {
      case 'Click':
        console.log(
          `mouse ${event.button} button pressed, state: ${event.buttonState}`
        );
        break;
      case 'DoubleClick':
        console.log(`mouse ${event.button} button pressed`);
        break;
      case 'Enter':
        console.log(
          `mouse hovered tray at ${event.rect.position.x}, ${event.rect.position.y}`
        );
        break;
      case 'Move':
        console.log(
          `mouse moved on tray at ${event.rect.position.x}, ${event.rect.position.y}`
        );
        break;
      case 'Leave':
        console.log(
          `mouse left tray at ${event.rect.position.x}, ${event.rect.position.y}`
        );
        break;
    }
  },
};

const tray = await TrayIcon.new(options);

Consulta TrayIconEvent para obtener más información sobre el payload del evento.

Rust

use tauri::{
    Manager,
    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent}
};

TrayIconBuilder::new()
  .on_tray_icon_event(|tray, event| match event {
    TrayIconEvent::Click {
      button: MouseButton::Left,
      button_state: MouseButtonState::Up,
      ..
    } => {
      println!("left click pressed and released");
      // in this example, let's show and focus the main window when the tray is clicked
      let app = tray.app_handle();
      if let Some(window) = app.get_webview_window("main") {
        let _ = window.unminimize();
        let _ = window.show();
        let _ = window.set_focus();
      }
    }
    _ => {
      println!("unhandled event {event:?}");
    }
  })

Consulta TrayIconEvent para obtener más información sobre el tipo de evento.

Para obtener información detallada sobre la creación de menús, incluidos los elementos de menú, submenús y actualizaciones dinámicas, consulta la documentación del Menú de Ventana.