Usar a API Notifications

A API browser.notifications permite criar notificações usando modelos e mostrar essas notificações aos usuários na bandeja do sistema:

Como elas aparecem

As notificações avançadas vêm em quatro tipos diferentes: básica, imagem, lista e progresso. Todas as notificações incluem um título, uma mensagem, um pequeno ícone exibido à esquerda da mensagem de notificação e um campo contextMessage, que é mostrado como um terceiro campo de texto em uma fonte de cor mais clara.

Uma notificação básica:

As notificações de lista mostram qualquer número de itens:

As notificações de imagem incluem uma prévia:

As notificações de progresso mostram uma barra de progresso:

Como eles se comportam

No ChromeOS, as notificações aparecem na bandeja do sistema de um usuário e permanecem lá até que ele as dispense. A bandeja do sistema mantém uma contagem de todas as novas notificações. Quando um usuário vê as notificações na bandeja do sistema, a contagem é redefinida para zero.

As notificações podem receber uma prioridade entre -2 e 2. Prioridades menores que 0 são mostradas na central de notificações do ChromeOS e geram um erro em outras plataformas. A prioridade padrão é 0. As prioridades maiores que 0 são mostradas para aumentar a duração, e mais notificações de alta prioridade podem ser exibidas na bandeja do sistema.

A configuração priority não afeta a ordem das notificações no macOS.

Além de mostrar informações, todos os tipos de notificação podem incluir até dois itens de ação. Quando os usuários clicam em um item de ação, a extensão pode responder com a ação apropriada. Por exemplo, quando o usuário clica em Responder, o app de e-mail é aberto e o usuário pode concluir a resposta:

Como desenvolvê-las

Para usar essa API, chame o método notifications.create(), transmitindo os detalhes da notificação usando o parâmetro options:

await browser.notifications.create(id, options);

O notifications.NotificationOptions precisa incluir um notifications.TemplateType, que define os detalhes de notificação disponíveis e como eles são exibidos.

Criar uma notificação básica

Todos os tipos de modelo (basic, image, list e progress) precisam incluir uma notificação title e message, além de um iconUrl, que é um link para um pequeno ícone exibido à esquerda da mensagem de notificação.

Confira um exemplo de modelo de basic:

var opt = {
  type: "basic",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon"
}

Usar uma imagem

O tipo de modelo image também inclui um imageUrl, que é um link para uma imagem visualizada na notificação. As imagens não são mostradas aos usuários no macOS.

var opt = {
  type: "image",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  imageUrl: "url_to_preview_image"
}

Criar uma notificação de lista

O modelo list mostra items em formato de lista. Observação: apenas o primeiro item é mostrado aos usuários no macOS.

var opt = {
  type: "list",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  items: [{ title: "Item1", message: "This is item 1."},
          { title: "Item2", message: "This is item 2."},
          { title: "Item3", message: "This is item 3."}]
}```

### Create progress notification {: #progress }

The `progress` template displays a progress bar where current progress ranges from 0 to 100. On macOS the progress bar displays as a percentage value in the notification title instead of in the progress bar.

```js
var opt = {
  type: "progress",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  progress: 42
}

Detectar e responder a eventos

Todas as notificações podem incluir listeners e manipuladores de eventos que respondem a ações do usuário (consulte browser.events). Por exemplo, você pode escrever um manipulador de eventos para responder a um evento notifications.onButtonClicked.

Listener de eventos:

browser.notifications.onButtonClicked.addListener(replyBtnClick);

Manipulador de eventos:

function replyBtnClick {
    //Write function to respond to user action.
}

Considere incluir listeners e gerenciadores de eventos no service worker para que as notificações apareçam mesmo quando a extensão não estiver em execução.