Integração com o ambiente desktop

Diferentes sistemas operacionais possuem diferentes formas de integrar aplicacões desktop em seus ambientes. Por exemplo, no Windows, as aplicações podem inserir atalhos no JumpList da barra de tarefas, no Mac, aplicações podem implementar um menu customizado na dock.

Este guia explica como integrar suas aplicações no ambiente desktop com a API do Electron.

Documentos Recentes (Windows & macOS)

O Windows e o macOS disponibilizam um acesso fácil para a lista de arquivos abertos recentemente pela aplicação através do JumpList ou Dock Menu respectivamente.

JumpList:

Dock menu da Aplicação:

Para adicionar um arquivo para os documentos recentes, você pode usar a API app.addRecentDocument:

var app = require('app')
app.addRecentDocument('/Users/USERNAME/Desktop/work.type')

E você pode usar a API app.clearRecentDocuments para limpar a lista de documentos recentes.

app.clearRecentDocuments()

Notas para Windows

A fim de ser possível usar estas funcionalidades no Windows, sua aplicação deve estar registrada como um handler daquele tipo de documento, caso contrário, o arquivo não será exibido no JumpList mesmo depois de você ter adicionado isto. Você pode encontrar qualquer coisa sobre o registro da aplicacão em Application Registration.aspx).

Quando um usuário clica em um arquivo na JumpList, uma nova instância da sua aplicacão deve ser iniciada com o caminho do arquivo adicionado como um argumento de linha de comando.

Notas para macOS

Quando um arquivo for requisitado pelo menu de documentos recentes, o evento open-file do módulo app irá ser emitido.

Dock Menu customizado (macOS)

macOS permite que desenvolvedores especifiquem um menu customizado para a dock, que normalmente contém alguns atalhos para as funcionalidades mais utilizadas da sua aplicação.

Dock menu do Terminal.app:

Para criar seu Dock Menu customizado, você pode usar a API app.dock.setMenu, ela está disponível apenas no macOS:

const {app, Menu} = require('electron')

const dockMenu = Menu.buildFromTemplate([
  {label: 'New Window', click () { console.log('New Window') }},
  {label: 'New Window with Settings',
    submenu: [
      {label: 'Basic'},
      {label: 'Pro'}
    ]
  },
  {label: 'New Command...'}
])
app.dock.setMenu(dockMenu)

Tarefas do Usuário (Windows)

No Windows você pode especificar ações customizadas na categoria Tarefas do JumpList, esse texto foi copiado do 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.

Tarefas do Internet Explorer:

Ao contrário do Menu Dock no macOS que é um verdadeiro menu, tarefas do usuário no Windows funcionam como atalhos, de uma forma que quando o usuário clica em uma tarefa, um programa deve ser executado com os argumentos especificados.

Para setar tarefas do usuário para sua aplicação, você pode usar a API app.setUserTasks:

var app = require('app')
app.setUserTasks([
  {
    program: process.execPath,
    arguments: '--new-window',
    iconPath: process.execPath,
    iconIndex: 0,
    title: 'New Window',
    description: 'Create a new window'
  }
])

Para limpar sua lista de tarefas, apenas chame app.setUserTasks com um array vazio.

app.setUserTasks([])

As tarefas do usuário são exibidas mesmo depois da aplicação ser fechada, então o ícone e o caminho do programa especificado pela tarefa deve existir até sua aplicação ser desinstalada.

Miniaturas na Barra de Ferramentas

No Windows você pode adicionar uma miniatura na barra de ferramentas com botões específicos para a janela e barra de tarefas para aplicação. Isso provê ao usuário uma forma de acessar um comando específico para janela sem ser necessário restaurar ou ativar a janela.

Isto é ilustrado no MSDN:

This toolbar is simply the familiar standard toolbar common control. It has a maximum of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, which is then passed to the taskbar. The application can show, enable, disable, or hide buttons from the thumbnail toolbar as required by its current state.

For example, Windows Media Player might offer standard media transport controls such as play, pause, mute, and stop.

Miniaturas da barra de tarefas do Windows Media Player:

Você pode usar BrowserWindow.setThumbarButtons para criar miniaturas na barra de ferramentas para sua aplicação.

var BrowserWindow = require('browser-window')
var path = require('path')
var win = new BrowserWindow({
  width: 800,
  height: 600
})
win.setThumbarButtons([
  {
    tooltip: 'button1',
    icon: path.join(__dirname, 'button1.png'),
    click: function () { console.log('button2 clicked') }
  },
  {
    tooltip: 'button2',
    icon: path.join(__dirname, 'button2.png'),
    flags: ['enabled', 'dismissonclick'],
    click: function () { console.log('button2 clicked.') }
  }
])

Para limpar os botões na miniatura da barra de ferramentas, apenas chame BrowserWindow.setThumbarButtons com um array vazio.

win.setThumbarButtons([])

Unity Launcher Shortcuts (Linux)

No Unity, você pode adicionar entradas customizadas para estes lançadores modificando o arquivo .desktop, veja Adding Shortcuts to a Launcher.

Launcher shortcuts do Audacious:

Barra de Progresso na Barra de Tarefas (Windows & Unity)

No Windows o botão na barra de tarefas pode ser usado para exibir uma barra de progresso. Isto permite que a janela exiba informação sobre o progresso de algum processo sem a necessidade do usuário mudar de janela.

A Unity DE também tem uma funcionalidade parecida que permite especificar uma barra de progresso no ícone do lançador.

Barra de Progresso no botão da barra de tarefas:

Barra de progresso no Unity launcher:

Para adicionar uma barra de progresso para uma janela, você pode ver a API: BrowserWindow.setProgressBar:

var window = new BrowserWindow()
window.setProgressBar(0.5)

Representação do arquivo na janela (macOS)

No macOS, uma janela pode possuir a representação de um arquivo na barra de título, permitindo que ao usuário acionar um Command-Click ou Control-Click sobre o título da janela, uma pop-up de navegação entre arquivos é exibida.

Você também pode inserir um estado de edição na janela para que o ícone do arquivo possa indicar se o documento nesta janela foi modificado.

Menu popup da representação de arquivo:

Para inserir o arquivo de representacão da janela, você pode usar as API BrowserWindow.setRepresentedFilename e BrowserWindow.setDocumentEdited:

var window = new BrowserWindow()
window.setRepresentedFilename('/etc/passwd')
window.setDocumentEdited(true)