452 lines
15 KiB
Markdown
452 lines
15 KiB
Markdown
# app
|
|
|
|
O módulo `app` é responsável por controlar o ciclo de vida do aplicativo.
|
|
|
|
O exemplo a seguir mostra como fechar o aplicativo quando a última janela é fechada:
|
|
|
|
```javascript
|
|
const app = require('electron').app;
|
|
app.on('window-all-closed', function() {
|
|
app.quit();
|
|
});
|
|
```
|
|
|
|
## Eventos
|
|
|
|
O objeto `app` emite os seguintes eventos:
|
|
|
|
### Evento: 'will-finish-launching'
|
|
|
|
Emitido quando o aplicativo finaliza a inicialização básica. No Windows e no Linux,
|
|
o evento `will-finish-launching` é o mesmo que o evento `ready`; No macOS,
|
|
esse evento representa a notificação `applicationWillFinishLaunching` do `NSApplication`.
|
|
Normalmente aqui seriam criados *listeners* para os eventos `open-file` e `open-url`, e inicializar o *crash reporter* e atualizador automático.
|
|
|
|
Na maioria dos casos, você deve fazer tudo no manipulador de eventos do `ready`.
|
|
|
|
### Evento: 'ready'
|
|
|
|
Emitido quando o Electron finaliza a inicialização.
|
|
|
|
### Evento: 'window-all-closed'
|
|
|
|
Emitido quando todas as janelas forem fechadas.
|
|
|
|
Este evento só é emitido quando o aplicativo não for fechar. Se o
|
|
usuário pressionou`Cmd + Q`, ou o desenvolvedor chamou `app.quit()`,
|
|
o Electron tentará primeiro fechar todas as janelas e então emitir o
|
|
evento `will-quit`, e neste caso o evento `window-all-closed` não
|
|
seria emitido.
|
|
|
|
### Evento: 'before-quit'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
|
|
Emitido antes que o aplicativo comece a fechar suas janelas.
|
|
Chamar `event.preventDefault()` irá impedir o comportamento padrão,
|
|
que é terminar o aplicativo.
|
|
|
|
### Evento: 'will-quit'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
|
|
Emitido quando todas as janelas foram fechadas e o aplicativo irá finalizar.
|
|
Chamar `event.preventDefault()` irá impedir o comportamento padrão,
|
|
que é terminar o aplicativo.
|
|
|
|
Veja a descrição do evento `window-all-closed` para as diferenças entre o
|
|
evento `will-quit` e `window-all-closed`.
|
|
|
|
### Evento: 'quit'
|
|
|
|
Emitido quando o aplicativo está finalizando.
|
|
|
|
### Evento: 'open-file' _macOS_
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `path` String
|
|
|
|
Emitido quando o usuário deseja abrir um arquivo com o aplicativo. O evento
|
|
`open-file` normalmente é emitido quando o aplicativo já está aberto e o S.O.
|
|
quer reutilizar o aplicativo para abrir o arquivo. `open-file` também é emitido
|
|
quando um arquivo é jogado no *dock* e o aplicativo ainda não está rodando.
|
|
Certifique-se de utilizar um *listener* para o evento `open-file` cedo na
|
|
inicialização do seu aplicativo para cuidar deste caso (antes mesmo do evento
|
|
`ready` ser emitido).
|
|
|
|
Você deve chamar `event.preventDefault()` se quiser cuidar deste caso.
|
|
|
|
No Windows, você deve fazer o *parse* do `process.argv` para pegar o
|
|
endereço do arquivo.
|
|
|
|
### Evento: 'open-url' _macOS_
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `url` String
|
|
|
|
Emitido quando o usuário deseja abrir uma URL com o aplicativo. O esquema deve
|
|
ser registrado para ser aberto pelo seu aplicativo.
|
|
|
|
Você deve chamar `event.preventDefault()` se quiser cuidar deste caso.
|
|
|
|
### Evento: 'activate' _macOS_
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `hasVisibleWindows` Boolean
|
|
|
|
Emitido quando o aplicativo é ativado, que normalmente acontece quando o ícone
|
|
do aplicativo no *dock* é clicado.
|
|
|
|
### Evento: 'browser-window-blur'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `window` BrowserWindow
|
|
|
|
Emitido quando uma [browserWindow](../../../docs/api/browser-window.md) fica embaçada.
|
|
|
|
### Evento: 'browser-window-focus'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `window` BrowserWindow
|
|
|
|
Emitido quando uma [browserWindow](../../../docs/api/browser-window.md) é focada.
|
|
|
|
### Evento: 'browser-window-created'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `window` BrowserWindow
|
|
|
|
Emitido quando uma nova [browserWindow](../../../docs/api/browser-window.md) é criada.
|
|
|
|
### Evento: 'certificate-error'
|
|
|
|
Returns:
|
|
|
|
* `event` Event
|
|
* `webContents` [WebContents](../../../docs/api/web-contents.md)
|
|
* `url` URL
|
|
* `error` String - O código de erro
|
|
* `certificate` Object
|
|
* `data` Buffer - dados codificados PEM
|
|
* `issuerName` String
|
|
* `callback` Function
|
|
|
|
Emitido quando há uma falha na verificação do `certificate` para a `url`,
|
|
para confiar no certificado, você deve impedir o comportamento padrão com
|
|
`event.preventDefault()` e chamar `callback(true)`.
|
|
|
|
```javascript
|
|
session.on('certificate-error', function(event, webContents, url, error, certificate, callback) {
|
|
if (url == "https://github.com") {
|
|
// Lógica de verificação.
|
|
event.preventDefault();
|
|
callback(true);
|
|
} else {
|
|
callback(false);
|
|
}
|
|
});
|
|
```
|
|
|
|
### Evento: 'select-client-certificate'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `webContents` [WebContents](../../../docs/api/web-contents.md)
|
|
* `url` URL
|
|
* `certificateList` [Objects]
|
|
* `data` Buffer - dados codificados PEM
|
|
* `issuerName` String - Nome Comum do Emissor
|
|
* `callback` Function
|
|
|
|
Emitido quando um certificado de cliente é requisitado.
|
|
|
|
A `url` corresponde à entrada de navegação requisitando o certificado do
|
|
cliente e `callback` precisa ser chamada com uma entrada filtrada da lista.
|
|
Usar `event.preventDefault()` impede o aplicativo de usar o primeiro certificado
|
|
da memória.
|
|
|
|
```javascript
|
|
app.on('select-client-certificate', function(event, webContents, url, list, callback) {
|
|
event.preventDefault();
|
|
callback(list[0]);
|
|
})
|
|
```
|
|
|
|
### Evento: 'login'
|
|
|
|
Retorna:
|
|
|
|
* `event` Event
|
|
* `webContents` [WebContents](../../../docs/api/web-contents.md)
|
|
* `request` Object
|
|
* `method` String
|
|
* `url` URL
|
|
* `referrer` URL
|
|
* `authInfo` Object
|
|
* `isProxy` Boolean
|
|
* `scheme` String
|
|
* `host` String
|
|
* `port` Integer
|
|
* `realm` String
|
|
* `callback` Function
|
|
|
|
Emitido quando `webContents` deseja fazer autenticação básica.
|
|
|
|
O comportamento padrão é cancelar todas as autenticações, para sobrescrever
|
|
isto, você deve impedir esse comportamento com `event.preventDefault()` e
|
|
chamar `callback(username, password)` com as credenciais.
|
|
|
|
```javascript
|
|
app.on('login', function(event, webContents, request, authInfo, callback) {
|
|
event.preventDefault();
|
|
callback('username', 'secret');
|
|
})
|
|
```
|
|
|
|
### Evento: 'gpu-process-crashed'
|
|
|
|
Emitido quando o processo da gpu falha.
|
|
|
|
## Métodos
|
|
|
|
O objeto `app` possui os seguintes métodos:
|
|
|
|
**Nota:** Alguns métodos só estão disponíveis em sistemas operacionais específicos e estão rotulados como tal.
|
|
|
|
### `app.quit()`
|
|
|
|
Tente fechar todas as janelas. O evento `before-quit` será emitido primeiro. Se todas
|
|
as janelas fecharem com sucesso, o evento `will-quit` será emitido e por padrão o
|
|
aplicativo irá terminar.
|
|
|
|
Este método garante que todos os manipuladores de evento `beforeunload` e `unload`
|
|
sejam corretamente executados. É possível que uma janela cancele o processo de
|
|
encerramento ao retornar `false` no manipulador de evento `beforeunload`.
|
|
|
|
### `app.exit(exitCode)`
|
|
|
|
* `exitCode` Integer
|
|
|
|
Finaliza imediatamente com `exitCode`.
|
|
|
|
Todas as janelas serão fechadas imediatamente sem perguntar ao usuário, e os eventos
|
|
`before-quit` e `will-quit` não serão emitidos.
|
|
|
|
### `app.getAppPath()`
|
|
|
|
Retorna o atual diretório do aplicativo.
|
|
|
|
### `app.getPath(name)`
|
|
|
|
* `name` String
|
|
|
|
Retorna um endereço para um diretório especial ou arquivo associado com `nome`.
|
|
Numa falha um `Error` é lançado.
|
|
|
|
Você pode requisitar os seguintes endereços pelo nome:
|
|
|
|
* `home` Diretório *home* do usuário.
|
|
* `appData` Diretório de dados do aplicativo por usuário, que por padrão aponta para:
|
|
* `%APPDATA%` no Windows
|
|
* `$XDG_CONFIG_HOME` ou `~/.config` no Linux
|
|
* `~/Library/Application Support` no macOS
|
|
* `userData` O diretório para guardar os arquivos de configuração do seu aplicativo, que por padrão é o diretório `appData` concatenado com o nome do seu aplicativo.
|
|
* `temp` Diretório temporário.
|
|
* `exe` O arquivo executável atual.
|
|
* `module` A biblioteca `libchromiumcontent`.
|
|
* `desktop` O diretório *Desktop* do usuário atual.
|
|
* `documents` Diretório "Meus Documentos" do usuário.
|
|
* `downloads` Diretório dos downloads do usuário.
|
|
* `music` Diretório de músicas do usuário.
|
|
* `pictures` Diretório de imagens do usuário.
|
|
* `videos` Diretório de vídeos do usuário.
|
|
|
|
### `app.setPath(name, path)`
|
|
|
|
* `name` String
|
|
* `path` String
|
|
|
|
Sobrescreve o `path` para um diretório especial ou arquivo associado com `name`.
|
|
Se o endereço especifica um diretório não existente, o diretório será criado por
|
|
este método. Numa falha um `Error` é lançado.
|
|
|
|
Você pode sobrescrever apenas endereços com um `name` definido em `app.getPath`.
|
|
|
|
Por padrão, *cookies* e *caches* de páginas web serão guardadas no diretório `userData`. Se você quiser mudar esta localização, você deve sobrescrever o
|
|
endereço `userData` antes que o evento `ready` do módulo `app` seja emitido.
|
|
|
|
### `app.getVersion()`
|
|
|
|
Retorna a versão do aplicativo carregado. Se nenhuma versão for encontrada no
|
|
arquivo `package.json` do aplicativo, a versão do pacote ou executável atual é
|
|
retornada.
|
|
|
|
### `app.getName()`
|
|
|
|
Retorna o nome do aplicativo atual, que é o nome no arquivo `package.json` do
|
|
aplicativo.
|
|
|
|
Normalmente o campo `name` do `package.json` é um nome curto em letras minúsculas,
|
|
de acordo com as especificações de módulos npm. Normalmente você deve também
|
|
especificar um campo `productName`, que é o nome completo em letras maiúsculas do
|
|
seu aplicativo, e que será preferido ao `name` pelo Electron.
|
|
|
|
### `app.getLocale()`
|
|
|
|
Retorna a localidade atual do aplicativo.
|
|
|
|
### `app.addRecentDocument(path)` _macOS_ _Windows_
|
|
|
|
* `path` String
|
|
|
|
Adiciona `path` à lista de documentos recentes.
|
|
|
|
Esta lista é gerenciada pelo S.O.. No Windows você pode visitar a lista pela
|
|
barra de tarefas, e no macOS você pode visita-la pelo *dock*.
|
|
|
|
### `app.clearRecentDocuments()` _macOS_ _Windows_
|
|
|
|
Limpa a lista de documentos recentes.
|
|
|
|
### `app.setUserTasks(tasks)` _Windows_
|
|
|
|
* `tasks` Array - Vetor de objetos `Task`
|
|
|
|
Adiciona `tasks` à categoria [Tasks][tasks] do JumpList no Windows.
|
|
|
|
`tasks` é um vetor de objetos `Task` no seguinte formato:
|
|
|
|
`Task` Object
|
|
* `program` String - Endereço do programa a ser executado, normalmente você deve especificar `process.execPath` que abre o programa atual.
|
|
* `arguments` String - Os argumentos de linha de comando quando `program` é executado.
|
|
* `title` String - A string a ser exibida em uma JumpList.
|
|
* `description` String - Descrição desta *task*.
|
|
* `iconPath` String - O endereço absoluto para um ícone a ser exibido em uma JumpList, que pode ser um arquivo arbitrário que contém um ícone. Normalmente você pode especificar `process.execPath` para mostrar o ícone do programa.
|
|
* `iconIndex` Integer - O índice do ícone do arquivo do icone. Se um arquivo de ícone consiste de dois ou mais ícones, defina este valor para identificar o ícone. Se o arquivo de ícone consiste de um ícone apenas, este valor é 0.
|
|
|
|
### `app.allowNTLMCredentialsForAllDomains(allow)`
|
|
|
|
* `allow` Boolean
|
|
|
|
Define dinamicamente se sempre envia credenciais para HTTP NTLM ou autenticação *Negotiate* - normalmente, o Electron irá mandar apenas credenciais NTLM/Kerberos para URLs que se enquadram em sites "Intranet Local" (estão no mesmo domínio que você).
|
|
Entretanto, esta detecção frequentemente falha quando redes corporativas são mal configuradas, então isso permite optar por esse comportamento e habilitá-lo para todas as URLs.
|
|
|
|
### `app.makeSingleInstance(callback)`
|
|
|
|
* `callback` Function
|
|
|
|
Este método faz da sua aplicação uma Aplicação de Instância Única - invés de permitir múltiplas instâncias do seu aplicativo rodarem, isto irá assegurar que apenas uma única instância do seu aplicativo rodará, e outras instâncias sinalizam esta instância e finalizam.
|
|
|
|
`callback` será chamado com `callback(argv, workingDirectory)` quando uma segunda instância tenha sido executada. `argv` é um vetor de argumentos de linha de comando da segunda instância, e `workingDirectory` é o atual endereço de seu diretório.
|
|
Normalmente aplicativos respondem à isso não minimizando sua janela primária e dando foco à ela.
|
|
|
|
É garantida a execução do `callback` após o evento `ready` do `app` ser emitido.
|
|
|
|
Este método retorna `false` caso seu processo seja a instância primária do aplicativo e seu aplicativo deve continuar carregando. E retorna `true` caso seu processo tenha enviado seus parâmetros para outra instância, e você deve imediatamente finalizar.
|
|
|
|
No macOS o sistema enforça instância única automaticamente quando usuários tentam abrir uma segunda instância do seu aplicativo no *Finder*, e os eventos `open-file` e `open-url` serão emitidos para isso. Entretanto, quando usuários inicializam seu aplicativo na linha de comando, o mecanismo de instância única do sistema será ignorado e você terá de utilizar esse método para assegurar-se de ter uma instância única.
|
|
|
|
Um exemplo de ativação da janela de primeira instância quando uma segunda instância inicializa:
|
|
|
|
```js
|
|
var myWindow = null;
|
|
|
|
var shouldQuit = app.makeSingleInstance(function(commandLine, workingDirectory) {
|
|
// Alguém tentou rodar uma segunda instância, devemos focar nossa janela
|
|
if (myWindow) {
|
|
if (myWindow.isMinimized()) myWindow.restore();
|
|
myWindow.focus();
|
|
}
|
|
return true;
|
|
});
|
|
|
|
if (shouldQuit) {
|
|
app.quit();
|
|
return;
|
|
}
|
|
|
|
// Cria myWindow, carrega o resto do aplicativo, etc...
|
|
app.on('ready', function() {
|
|
});
|
|
```
|
|
|
|
### `app.setAppUserModelId(id)` _Windows_
|
|
|
|
* `id` String
|
|
|
|
Muda o [Application User Model ID][app-user-model-id] para `id`.
|
|
|
|
### `app.commandLine.appendSwitch(switch[, value])`
|
|
|
|
Adiciona uma opção (com `value` opcional) à linha de comando do Chromium.
|
|
|
|
**Nota:** Isto não irá afetar `process.argv`, e é utilizado principalmente por desenvolvedores para controlar alguns comportamentos de baixo nível do Chromium.
|
|
|
|
### `app.commandLine.appendArgument(value)`
|
|
|
|
Adiciona um argumento à linha de comando do Chromium. O argumento será passado com aspas corretamente.
|
|
|
|
**Nota:** Isto não irá afetar `process.argv`.
|
|
|
|
### `app.dock.bounce([type])` _macOS_
|
|
|
|
* `type` String (opcional) - Pode ser `critical` ou `informational`. O padrão é
|
|
`informational`
|
|
|
|
Quando `critical` é passado, o ícone do *dock* irá pular até que o aplicativo se torne ativo ou a requisição seja cancelada.
|
|
|
|
Quando `informational` é passado, o ícone do *dock* irá pular por um segundo.
|
|
Entretanto, a requisição se mantém ativa até que o aplicativo se torne ativo ou a requisição seja cancelada.
|
|
|
|
Retorna um ID representando a requisição.
|
|
|
|
### `app.dock.cancelBounce(id)` _macOS_
|
|
|
|
* `id` Integer
|
|
|
|
Cancela o salto do `id`.
|
|
|
|
### `app.dock.setBadge(text)` _macOS_
|
|
|
|
* `text` String
|
|
|
|
Define a string a ser exibida na área de *badging* do *dock*.
|
|
|
|
### `app.dock.getBadge()` _macOS_
|
|
|
|
Retorna a string da *badge* do *dock*.
|
|
|
|
### `app.dock.hide()` _macOS_
|
|
|
|
Esconde o ícone do *dock*.
|
|
|
|
### `app.dock.show()` _macOS_
|
|
|
|
Exibe o ícone do *dock*.
|
|
|
|
### `app.dock.setMenu(menu)` _macOS_
|
|
|
|
* `menu` Menu
|
|
|
|
Define o [menu do dock][dock-menu] do aplicativo.
|
|
|
|
[dock-menu]:https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/customizing_docktile/concepts/dockconcepts.html#//apple_ref/doc/uid/TP30000986-CH2-TPXREF103
|
|
[tasks]:http://msdn.microsoft.com/en-us/library/windows/desktop/dd378460(v=vs.85).aspx#tasks
|
|
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx
|