Conteúdo de notificação do aplicativo

As notificações de aplicativos são notificações flexíveis com texto, imagens e botões/entradas. Este artigo descreve os elementos da interface do usuário que podem ser usados em uma notificação de aplicativo e fornece exemplos de código para gerar o formato XML para uma notificação de aplicativo.

Note

O termo "notificação de brinde" será substituído por "notificação do aplicativo". Ambos os termos se referem ao mesmo recurso do Windows, mas com o tempo eliminaremos gradualmente o uso de "toast notification" na documentação.

Como Começar

As notificações do aplicativo são definidas com uma carga XML que é definida pelo esquema de notificação do aplicativo. Atualmente, há três maneiras de gerar a carga XML para uma notificação de aplicativo. Os exemplos de código neste artigo demonstram todos os três métodos:

As APIs Microsoft.Windows.AppNotifications.Builder - Introduzidas no Windows App SDK 1.2, esse namespace fornece APIs que permitem que você crie facilmente a carga XML para uma notificação programaticamente sem ter que se preocupar com as especificidades do formato XML. Exemplos de código usando essas APIs estão nas guias rotuladas como "SDK de Aplicativo Windows".
A Microsoft.Toolkit.Uwp.Notifications sintaxe do construtor - Essas APIs fazem parte do Kit de Ferramentas da Comunidade UWP e fornecem suporte para aplicativos UWP. Embora essas APIs também possam ser usadas para aplicativos do SDK de aplicativos Windows e continuem a ter suporte, recomendamos que novas implementações usem as APIs Microsoft.Windows.AppNotifications.Builder . Para usar as APIs do Kit de Ferramentas da Comunidade, adicione o pacote nuget de Notificações do Kit de Ferramentas da Comunidade UWP ao seu projeto. Os exemplos de C# fornecidos neste artigo usam a versão 7.0.0 do pacote NuGet. Exemplos de código usando essas APIs estão nas guias rotuladas "Kit de Ferramentas da Comunidade do Windows".
XML bruto - Se preferir, você pode criar seu próprio código personalizado para gerar cadeias de caracteres XML no formato necessário. Os exemplos de XML bruto estão nas guias rotuladas como "XML".

Instale o Visualizador de notificações. Esta aplicação gratuita do Windows ajuda a criar notificações interativas de aplicações, fornecendo uma pré-visualização instantânea das notificações tipo 'toast' enquanto as edita, semelhante ao modo de exibição do editor/design XAML do Visual Studio. Veja Visualizador de Notificações para obter mais informações ou descarregar o Visualizador de Notificações da Loja.

Este artigo aborda apenas a criação do conteúdo de notificação do aplicativo. Para obter informações sobre como enviar uma notificação depois de gerar a carga XML, consulte Enviar uma notificação de aplicativo local.

Estrutura de notificação do aplicativo

Alguns componentes importantes e de alto nível de uma carga XML de notificação de aplicativo incluem:

: o atributo lançamento desse elemento define quais argumentos serão passados de volta para o seu aplicativo quando o utilizador clicar no toast, permitindo-lhe criar um deep link para o conteúdo correto que o toast estava a exibir. Para saber mais, consulte Enviar uma notificação de aplicação local.
visual: Este elemento representa a parte visual da notificação, incluindo o vínculo genérico que contém texto e imagens.
ações: Este elemento representa a componente interativa do toast, incluindo entradas e ações.
de áudio: Este elemento especifica o áudio reproduzido quando a notificação pop-up é mostrada ao utilizador.

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", "9813")

    .AddText("Some text")

    .AddButton(new AppNotificationButton("Archive")
        .AddArgument("action", "archive"))

    .SetAudioUri(new Uri("ms-appx:///Sound.mp3"));

var builder = new ToastContentBuilder()
    .AddArgument("conversationId", 9813)

    .AddText("Some text")

    .AddButton(new ToastButton()
        .SetContent("Archive")
        .AddArgument("action", "archive"))

    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast launch='conversationId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Some text</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
    <actions>
        <action content='Archive' arguments='action=archive'/>
    </actions>
</toast>

Aqui está uma representação visual do conteúdo da notificação do aplicativo:

Área de atribuição

A área de atribuição está na parte superior da notificação do aplicativo. A partir do Windows 11, o nome e o ícone do seu aplicativo são exibidos nesta área. A área de atribuição também inclui um botão de fechar que permite ao usuário ignorar rapidamente a notificação e um menu de reticências que permite ao usuário desativar rapidamente as notificações do seu aplicativo ou ir para a página Configurações do Windows para as notificações do seu aplicativo. A área de atribuição é configurada pelo shell e não pode ser anulada no payload toast XML, embora a sua aplicação possa adicionar itens ao menu de contexto dessa área. Para obter mais informações, consulte Ações do menu de contexto.

Visual

Cada notificação de aplicativo deve especificar um elemento de visual , onde você deve fornecer uma associação de notificação do sistema genérica e que pode conter texto e imagens. Esses elementos serão renderizados em vários dispositivos Windows, incluindo desktop, telefones, tablets e Xbox.

Para todos os atributos suportados na seção visual e os seus elementos filho, consulte Esquema de notificação de aplicativo.

Elementos de texto

Cada notificação de aplicativo deve ter pelo menos um elemento de texto e pode conter dois elementos de texto adicionais, todos do tipo AdaptiveText.

Uma captura de tela de uma notificação de aplicativo com três linhas de texto. A linha superior do texto é negrito.

Desde a Atualização de Aniversário do Windows 10, pode controlar quantas linhas de texto são exibidas usando a propriedade HintMaxLines no texto. O padrão (e máximo) é de até 2 linhas de texto para o título e até 4 linhas (combinadas) para os dois elementos de descrição adicionais (o segundo e o terceiro AdaptiveText).

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", 9813)
    .AddText("Adaptive Tiles Meeting", new AppNotificationTextProperties().SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

var builder = new ToastContentBuilder()
    .AddArgument("meetingId", 9813)
    .AddText("Adaptive Tiles Meeting", hintMaxLines: 1)
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

<toast launch='meetingId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

Imagem em linha

Por padrão, as imagens são exibidas embutidas, após quaisquer elementos de texto, preenchendo toda a largura da área visual.

Uma captura de tela de uma notificação de aplicativo mostrando o posicionamento padrão da imagem, em linha, preenchendo toda a largura da área visual.

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

AppNotificationManager.Default.Show(builder.BuildNotification());

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image src='ms-appx:///Images/InlineImage.png'/>
        </binding>
    </visual>
</toast>

Substituição do logótipo da aplicação

Especificar um valor de posicionamento para "appLogoOverride" fará com que a imagem seja exibida num quadrado no lado esquerdo da área visual. O nome dessa propriedade reflete o comportamento em versões anteriores do Windows, onde a imagem substituiria a imagem padrão do logotipo do aplicativo. No Windows 11, o logotipo do aplicativo é exibido na área de atribuição, portanto, não é substituído pelo appLogoOverride posicionamento da imagem.

As dimensões da imagem são de 48x48 pixels a 100% de escala. Geralmente, recomendamos fornecer uma versão de cada ativo de ícone para cada fator de escala: 100%, 125%, 150%, 200%e 400%.

Uma captura de ecrã de uma notificação de aplicativo mostrando a colocação da imagem de substituição do logotipo do aplicativo num quadrado no lado esquerdo da área visual da notificação.

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/AppLogo.png'/>
        </binding>
    </visual>
</toast>

Recorte de dicas

As diretrizes de estilo da Microsoft recomendam representar imagens de perfil com uma imagem circular para fornecer uma representação consistente de pessoas entre aplicativos e o shell. Defina a propriedade HintCrop como Circle para renderizar a imagem com um corte circular.

Uma captura de ecrã de uma notificação de aplicativo mostrando o logótipo do aplicativo como uma sobreposição da imagem cortada em um círculo no lado esquerdo da área visual da notificação.

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), AppNotificationImageCrop.Circle);

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), ToastGenericAppLogoCrop.Circle);

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/Profile.png' hint-crop='circle'/>
        </binding>
    </visual>
</toast>

Imagem de herói

Novo na Atualização de Aniversário: As notificações do aplicativo podem exibir uma imagem destacada, uma ToastGenericHeroImage que aparece em destaque no banner de notificação e dentro da Central de Notificações. As dimensões da imagem são 364x180 pixels com escala de 100%.

Uma captura de tela de uma notificação de aplicativo mostrando o posicionamento da imagem do herói, acima da área de atribuição.

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Mary Anne</text>
            <text>Check out where we camped last night!</text>
            <image placement='hero' src='ms-appx:///Images/HeroImage.png'/>
        </binding>
    </visual>
</toast>

Restrições de tamanho de imagem

As imagens que você usa na notificação do sistema podem ser obtidas a partir de...

http://
ms-appx:///
ms-appdata:///

Para imagens da Web remotas http e https, há limites no tamanho do arquivo de cada imagem individual. Na Fall Creators Update (16299), aumentamos o limite para 3 MB em conexões normais e 1 MB em conexões limitadas. Antes disso, as imagens eram sempre limitadas a 200 KB.

Ligação normal	Ligação medida	Antes da atualização Fall Creators
3 MB	1 MB	200 kb

Se uma imagem exceder o tamanho do arquivo, ou falhar o download, ou expirar, a imagem será descartada e o restante da notificação será exibida.

Texto de atribuição

Novo na Atualização de aniversário: se você precisar fazer referência à fonte do seu conteúdo, poderá usar o texto de atribuição. Este texto é sempre exibido abaixo de quaisquer elementos de texto, mas acima de imagens embutidas. O texto usa um tamanho um pouco menor do que os elementos de texto padrão para ajudar a distinguir dos elementos de texto normais.

Em versões mais antigas do Windows que não suportam texto de atribuição, o texto será simplesmente exibido como outro elemento de texto (supondo que você ainda não tenha o máximo de três elementos de texto).

Uma captura de ecrã de uma notificação de toast mostrando o texto de atribuição

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetAttributionText("via SMS");
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddAttributionText("Via SMS");
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>  
  <visual>
    <binding template="ToastGeneric">
      <image src="ms-appx:///Images/HeroImage.png"/>
      <text>Mary Anne</text>
      <text>Check out where we camped last night!</text>
      <text placement="attribution">Via SMS</text>
    </binding>
  </visual>
</toast>

Carimbo temporal personalizado

Novidade na Atualização dos Criadores: É agora possível substituir o carimbo de data/hora fornecido pelo sistema pelo seu próprio carimbo de data/hora, que representa com precisão quando a mensagem/informação/conteúdo foi gerado. Esse carimbo de data/hora é visível na Central de Notificações.

Captura de ecrã de uma notificação no Centro de Notificações com um carimbo de data/hora personalizado

Para saber mais sobre como usar um carimbo de data/hora personalizado, consulte carimbos de data/hora personalizados em toasts.

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddCustomTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

<toast displayTimestamp='2017-04-15T12:45:00-07:00'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
        </binding>
    </visual>
</toast>

Barra de progresso

Novidade na Atualização dos Criadores: é possível apresentar uma barra de progresso na notificação da sua aplicação para manter o utilizador informado sobre o progresso de operações como transferências.

Uma captura de ecrã de uma notificação tipo toast mostrando uma barra de progresso.

Para saber mais sobre como usar uma barra de progresso em notificações de "toast", consulte barra de progresso do toast.

Headers

Novo node Atualização para Criadores: você pode agrupar notificações em cabeçalhos na Central de Notificações. Por exemplo, você pode agrupar mensagens de um bate-papo em grupo sob um cabeçalho, ou notificações de grupo de um tema comum sob um cabeçalho, ou mais.

Uma captura de tela de uma central de ações mostrando várias notificações para o aplicativo Visualizador de notificações organizado sob um cabeçalho rotulado

Para saber mais sobre como usar cabeçalhos, consulte Toast headers.

Conteúdo adaptativo

Novo na Atualização de Aniversário: Além do conteúdo especificado acima, pode-se também exibir conteúdo adaptativo adicional que fica visível quando o brinde é expandido.

Esse conteúdo adicional é especificado usando o Adaptive, sobre o qual você pode saber mais lendo a documentação do Adaptive Tiles.

Observe que qualquer conteúdo adaptável deve estar contido em um AdaptiveGroup. Caso contrário, não será renderizado usando adaptativo.

Colunas e elementos de texto

Aqui está um exemplo em que colunas e alguns elementos de texto adaptáveis avançados são usados. Como os elementos de texto estão dentro de um AdaptiveGroup, eles suportam propriedades de estilo adaptativo ricas.

Uma captura de tela de uma notificação toast mostrando grupos de elementos de texto alinhados à esquerda e à direita da área visual da notificação toast.

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support adaptive text elements.

new ToastContentBuilder()
    ...
    
    .AddVisualChild(new AdaptiveGroup()
    {
        Children =
        {
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "52 attendees",
                        HintStyle = AdaptiveTextStyle.Base
                    },
                    new AdaptiveText()
                    {
                        Text = "23 minute drive",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            },
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "1 Microsoft Way",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    },
                    new AdaptiveText()
                    {
                        Text = "Bellevue, WA 98008",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    }
                }
            }
        }
    });

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Reminder: Windows Launch Party</text>
      <text>4:00 PM, 10/21/2021</text>
      <group>
        <subgroup>
          <text hint-style="base">52 attendees</text>
          <text hint-style="captionSubtle">23 minute drive</text>
        </subgroup>
        <subgroup>
          <text hint-style="captionSubtle" hint-align="right">1 Microsoft Way</text>
          <text hint-style="captionSubtle" hint-align="right">Bellevue, WA 98008</text>
        </subgroup>
      </group>
    </binding>
  </visual>
</toast>

Buttons

Os botões tornam o seu aviso do tipo 'toast' interativo, permitindo que o utilizador execute ações rápidas na notificação do aplicativo sem interromper o seu fluxo de trabalho atual. Por exemplo, os utilizadores podem responder a uma mensagem diretamente de dentro de uma notificação ou eliminar um e-mail sem sequer abrir a aplicação de email. Os botões aparecem na parte expandida da sua notificação.

Para saber mais sobre como implementar botões de ponta a ponta, consulte Enviar notificação local.

Os botões podem ativar um aplicativo das seguintes maneiras:

O aplicativo é ativado em primeiro plano, com um argumento que pode ser usado para navegar até uma página/contexto específico.
Outro aplicativo é ativado via inicialização de protocolo.
A ativação em segundo plano é suportada explicitamente para aplicativos UWP. Para aplicações do Windows App SDK, a aplicação é sempre iniciada em primeiro plano. O aplicativo pode chamar AppInstance.GetActivatedEventArgs para detetar se a ativação foi iniciada por uma notificação e determinar, a partir dos argumentos passados, se deve iniciar totalmente o aplicativo em primeiro plano ou apenas manipular a notificação e sair.
Ações do sistema, como adiar ou descartar a notificação, são suportadas para aplicativos UWP e para o SDK de aplicativos do Windows. As APIs do AppNotificationBuilder não oferecem suporte a esse cenário, mas os aplicativos do SDK de Aplicativo Windows podem implementar esse cenário usando as APIs Microsoft.Windows.AppNotifications.Builder ou XML bruto.

Note

Você só pode ter até 5 botões (incluindo itens do menu de contexto que discutiremos mais tarde).

Uma captura de ecrã de uma notificação mostrando uma linha de texto seguida por uma fila com dois botões definidos por elementos de ação

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("New product in stock!")
        .AddButton(new AppNotificationButton("See more details")
            .AddArgument("action", "viewDetails"))
            .AddArgument("contentId", "351")
        .AddButton(new AppNotificationButton("Remind me later")
            .AddArgument("action", "remindLater"))
            .AddArgument("contentId", "351");

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("See more details")
        .AddArgument("action", "viewDetails"))

    .AddButton(new ToastButton()
        .SetContent("Remind me later")
        .AddArgument("action", "remindLater"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>New product in stock!</text>
        </binding>
    </visual>
      <actions>
          <action content='See more details' arguments='action=viewDetails;contentId=351'/>
          <action content='Remind me later' arguments='action=remindLater;contentId=351'/>
      </actions>
</toast>

Botões com ícones

Você pode adicionar ícones aos seus botões. Esses ícones são imagens de 16x16 pixels, transparentes e brancas, com uma escala de 100%%, e não devem ter qualquer preenchimento incluído na própria imagem. Se optar por fornecer ícones numa notificação de aviso, deverá fornecer ícones para TODOS os seus botões na notificação, pois transforma o estilo dos botões em botões com ícones.

Note

Para acessibilidade, certifique-se de incluir uma versão branca de contraste do ícone (um ícone preto para fundos brancos), para que, quando o usuário ativar o modo Branco de Alto Contraste, seu ícone fique visível. Para obter mais informações, consulte Suporte a notificações de bloco e pop-up parade idioma, escala e alto contraste.

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("Return books to the library.")
        .AddButton(new AppNotificationButton("Accept")
            .AddArgument("action", "accept")
            .SetIcon(new Uri("ms-appx:///Images/Accept.png")))
        .AddButton(new AppNotificationButton("Snooze")
            .AddArgument("action", "snooze")
            .SetIcon(new Uri("ms-appx:///Images/Snooze.png")))
        .AddButton(new AppNotificationButton("Dismiss")
            .AddArgument("action", "dismiss")
            .SetIcon(new Uri("ms-appx:///Images/Dismiss.png")));

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("Accept")
        .AddArgument("action", "accept")
        .SetImageUri(new Uri("ms-appx:///Images/Accept.png")))
    .AddButton(new ToastButton()
        .SetContent("Snooze")
        .AddArgument("action", "snooze")
        .SetImageUri(new Uri("ms-appx:///Images/Snooze.png")))
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss")
        .SetImageUri(new Uri("ms-appx:///Images/Dismiss.png")));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Return books to the library.</text>
        </binding>
    </visual>
    <actions>
        <action content='Accept' arguments='action=accept' imageUri='ms-appx:///Assets/Accept.png'/>
        <action content='Snooze' arguments='action=snooze' imageUri='ms-appx:///Assets/Snooze.png'/>
        <action content='Dismiss' arguments='action=dismiss' imageUri='ms-appx:///Assets/Dismiss.png'/>
    </actions>
</toast>

Novo no Windows 11 Update: você pode adicionar dicas de ferramentas aos seus ícones com a propriedade HintToolTip em XML. Isso é ideal se seus botões tiverem ícones, mas nenhum conteúdo, pois isso garantirá que você possa passar texto que o Narrador do Windows possa ler. No entanto, se o conteúdo estiver presente, o Narrador lerá o conteúdo, independentemente do que for passado na dica de ferramenta.

var button = new AppNotificationButton("Reply")
    .AddArgument("action", "reply");

if (AppNotificationButton.IsToolTipSupported())
{
    button.ToolTip = "Click to reply.";
}

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .AddButton(button);

// The Community Toolkit builder syntax does not currently support icon tooltips.

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Reply' arguments='action=reply' hint-toolTip='Click to reply'/>
    </actions>
</toast>

Botões com cores

Novo no Windows 11 Update: você pode adicionar cores vermelhas ou verdes aos botões, adicionando o atributo useButtonStyle ao elemento XML toast e o atributo hint-buttonStyle ao elemento XML de ação, conforme se vê abaixo.

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .AddText("Incoming Call - Mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///Images/Profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Video Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Video.png"))
        .AddArgument("videoId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Phone Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Call.png"))
        .AddArgument("callId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Hang Up")
        .SetButtonStyle(AppNotificationButtonStyle.Critical)
        .SetIcon(new Uri("ms-appx:///Images/HangUp.png"))
        .AddArgument("hangUpId", "123"));

// The WIndows Community Toolkit builder syntax does not currently support red and green button colors.

<toast scenario='incomingCall' useButtonStyle='true'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>Incoming Call - Mobile</text>
            <image src='ms-appx:///Images/InlineImage.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='' 
            arguments='videoId=123' 
            imageUri='ms-appx:///Images/Video.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Video Call'/>
        <action 
            content='' 
            arguments='callId=123' 
            imageUri='ms-appx:///Images/Call.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Phone Call'/>
        <action 
            content='' 
            arguments='hangUpId=123' 
            imageUri='ms-appx:///Images/HangUp.png' 
            hint-buttonStyle='Critical' 
            hint-toolTip='Hang Up'/>
    </actions>
</toast>

Novo node Atualização de Aniversário: Pode adicionar ações adicionais ao menu de contexto existente que aparece quando o utilizador clica com o botão direito do rato na sua notificação flutuante ou seleciona o ícone do menu de contexto.

Note

Em dispositivos mais antigos, essas ações adicionais do menu de contexto simplesmente aparecerão como botões normais na sua notificação.

As ações adicionais do menu de contexto que você adiciona (como "Silenciar bate-papo em grupo por 1 hora") aparecem acima das duas entradas padrão do sistema.

var builder = new AppNotificationBuilder()
    .AddText("Camping this weekend?")
    .SetAppLogoOverride(new Uri("ms-appx:///images/Reply.png"), AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Mute group chat for 1 hour")
        .AddArgument("action", "mute")
        .SetContextMenuPlacement());

Atualmente, a sintaxe do construtor do Windows Community Toolkit não oferece suporte a ações do menu de contexto, portanto, recomendamos o uso da sintaxe do inicializador.

ToastContent content = new ToastContent()
{
    ...
 
    Actions = new ToastActionsCustom()
    {
        ContextMenuItems =
        {
            new ToastContextMenuItem("Mute group chat for 1 hour", "action=muteId")
        }
    }
};

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Camping this weekend?</text>
            <image placement='appLogoOverride' src='ms-appx:///images/Reply.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action content='Mute group chat for 1 hour' arguments='action=mute' placement='contextMenu'/>
    </actions>
</toast>

Note

Itens adicionais do menu de contexto contribuem para o limite total de 5 botões em uma notificação do sistema.

A ativação de itens adicionais do menu de contexto é tratada de forma idêntica aos botões de notificações.

Inputs

As entradas são especificadas na região Ações da notificação da aplicação, o que significa que elas só ficam visíveis quando a notificação é expandida.

Caixa de texto de resposta rápida

Para habilitar uma caixa de texto de resposta rápida (por exemplo, em um aplicativo de mensagens), adicione uma entrada de texto e um botão e faça referência à ID do campo de entrada de texto para que o botão seja exibido ao lado do campo de entrada. O ícone opcional para o botão, se fornecido, deve ser uma imagem de 32x32 pixels sem preenchimento, pixels brancos definidos como transparentes e escala de 100%.

Uma captura de tela de uma notificação em formato de 'toast' com uma foto de perfil e algumas linhas de texto. Uma caixa de texto para digitar diretamente na notificação em formato de 'toast' está incluída, bem como um botão para enviar a resposta.

var builder = new AppNotificationBuilder()
    .AddTextBox("textBox", "Type a reply", "Reply")
    .AddButton(AppNotificationButton("Send")
        .AddArguments("action", "Send")
        .SetInputId("textBox"))
    .BuildNotification();

var builder = new ToastContentBuilder()
    .AddInputTextBox("tbReply", "Type a reply")
        .AddButton(new ToastButton()
        .SetContent("Reply")
        .SetTextBoxId("tbReply") // To place button next to text box, reference text box's id
        .SetImageUri(new Uri("Assets/Reply.png", UriKind.Relative))
        .AddArgument("action", "reply"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Send"
      arguments="action=reply&amp;convId=9318"
      hint-inputId="textBox"
      imageUri="Assets/Reply.png"/>
  </actions>
</toast>

Entradas com barra de botões

Você também pode ter uma (ou muitas) entradas com botões normais exibidos abaixo das entradas.

Uma captura de tela de uma notificação de aplicativo mostrando uma linha de texto, uma caixa de texto e uma linha com dois botões rotulados como

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support quick reply text boxes.

new ToastContentBuilder()
    ...
    
    .AddInputTextBox("tbReply", "Type a reply")

    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply"))

    .AddButton(new ToastButton()
        .SetContent("Video call")
        .AddArgument("action", "videoCall"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Reply"
      arguments="action=reply&amp;threadId=9218"/>
    <action
      content="Video call"
      arguments="action=videocall&amp;threadId=9218"
      activationType="foreground"/>
  </actions>
</toast>

Entrada de seleção

Além das caixas de texto, você também pode usar um menu de seleção.

Uma captura de tela de uma notificação de aplicativo mostrando uma linha de texto, uma entrada de seleção com

var builder = new AppNotificationBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddComboBox(new AppNotificationComboBox("time")
        .SetTitle("Select an item:")
        .AddItem("breakfast", "Breakfast")
        .AddItem("lunch", "Lunch")
        .AddItem("dinner", "Dinner")
        .SetSelectedItem("lunch"))
    .AddButton(new AppNotificationButton("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement())
    .AddButton(new AppNotificationButton("Call restaurant")
        .AddArgument("action", "videocall")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement());

var builder = new ToastContentBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddToastInput(new ToastSelectionBox("time")
    {
        DefaultSelectionBoxItemId = "lunch",
        Items =
            {
                new ToastSelectionBoxItem("breakfast", "Breakfast"),
                new ToastSelectionBoxItem("lunch", "Lunch"),
                new ToastSelectionBoxItem("dinner", "Dinner")
            }
    })
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218"))
    .AddButton(new ToastButton()
        .SetContent("Call restaurant")
        .AddArgument("action", "videoCall")
        .AddArgument("threadId", "9218"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>4th coffee?</text>
            <text>When do you plan to come in tomorrow?</text>
        </binding>
    </visual>
    <actions>
        <input id='time' type='selection' title='Select an item:' defaultInput='lunch'>
            <selection id='breakfast' content='Breakfast'/><selection id='dinner' content='Dinner'/>
            <selection id='lunch' content='Lunch'/>
        </input>
        <action content='Reply' arguments='action=reply;threadId=9218' placement='contextMenu'/>
        <action content='Call Restaurant' arguments='action=videocall;threadId=9218' placement='contextMenu'/>
    </actions>
</toast>

Snooze/dismiss

Usando um menu de seleção e dois botões, podemos criar uma notificação de lembrete que utiliza as ações de adiar e ignorar do sistema. Certifique-se de definir o cenário como "Lembrete" para que a notificação se comporte como um lembrete.

Uma captura de ecrã de uma notificação de aplicação com linhas de texto que descrevem a hora e a localização de uma reunião. Uma caixa de seleção tem

Vinculamos o botão de soneca à entrada do menu de seleção usando a propriedade SelectionBoxId no botão toast.

A sintaxe Microsoft.Windows.AppNotifications.Builder atualmente não suporta a ativação do sistema. Mas este cenário é suportado para aplicações do Windows App SDK, e pode criar notificações para este cenário usando as APIs Microsoft.Toolkit.Uwp.Notifications ou XML bruto.

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support system activation. 
// But this scenario is supported for Windows App SDK apps, and you can build notifications for this 
// scenario using the `Microsoft.Toolkit.Uwp.Notifications` APIs or raw XML.

new ToastContentBuilder()
    .SetToastScenario(ToastScenario.Reminder)
    
    ...
    
    .AddToastInput(new ToastSelectionBox("snoozeTime")
    {
        DefaultSelectionBoxItemId = "15",
        Items =
        {
            new ToastSelectionBoxItem("5", "5 minutes"),
            new ToastSelectionBoxItem("15", "15 minutes"),
            new ToastSelectionBoxItem("60", "1 hour"),
            new ToastSelectionBoxItem("240", "4 hours"),
            new ToastSelectionBoxItem("1440", "1 day")
        }
    })

    .AddButton(new ToastButtonSnooze() { SelectionBoxId = "snoozeTime" })
    .AddButton(new ToastButtonDismiss());

<toast>
  <visual>
    <binding template="ToastGeneric">
      <text hint-maxLines="1">Adaptive Tiles Meeting</text>
      <text>Conf Room 2001 / Building 135</text>
      <text>10:00 AM - 10:30 AM</text>
    </binding>
  </visual>
  <actions>
    <input id="snoozeTime" type="selection" defaultInput="15">
      <selection id="1" content="1 minute"/>
      <selection id="15" content="15 minutes"/>
      <selection id="60" content="1 hour"/>
      <selection id="240" content="4 hours"/>
      <selection id="1440" content="1 day"/>
    </input>
    <action activationType="system" arguments="snooze" hint-inputId="snoozeTime" content="" />
    <action activationType="system" arguments="dismiss" content=""/>
  </actions>
</toast>

Para usar o sistema adiar e descartar ações:

Especifique um ToastButtonSnooze ou ToastButtonDismiss
Opcionalmente, especifique uma cadeia de caracteres de conteúdo personalizada:
Se você não fornecer uma cadeia de caracteres, usaremos automaticamente cadeias de caracteres localizadas para "Snooze" e "Dismiss".
Opcionalmente, especifique o SelectionBoxId:
Se não quiser que o utilizador selecione um intervalo de adiamento e, em vez disso, pretender que a sua notificação seja adiada apenas uma vez para um intervalo de tempo definido pelo sistema (que seja consistente em todo o sistema operativo), então não construa nenhuma entrada <>.
Se quiser fornecer opções de intervalo de soneca: - Especifique SelectionBoxId na ação de soneca - Faça corresponder o ID da entrada com o SelectionBoxId da ação de soneca - Especifique o valor de ToastSelectionBoxItempara ser um inteiro não negativo que representa o intervalo de soneca em minutos.

Audio

O áudio personalizado sempre foi suportado em dispositivos móveis e é suportado na versão Desktop 1511 (build 10586) ou posterior. O áudio personalizado pode ser referenciado através dos seguintes caminhos:

ms-appx:///
ms-appdata:///

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioUri(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
</toast>

Como alternativa, pode-se escolher da lista de ms-winsoundeventsque sempre foram suportados em ambas as plataformas.

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioEvent(AppNotificationSoundEvent.Alarm, AppNotificationAudioLooping.Loop);

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-winsoundevent:Notification.Looping.Alarm"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-winsoundevent:Notification.Looping.Alarm' loop='true'/>
</toast>

Consulte a página do esquema de áudio para obter informações sobre áudio em notificações de apps. Para saber como enviar uma notificação de aplicativo que utiliza áudio personalizado, consulte áudio personalizado em toasts.

Scenarios

Para criar notificações importantes, alarmes, lembretes e notificações de chamadas recebidas, basta usar uma notificação normal do aplicativo com um Cenário valor atribuído a ele. O cenário ajusta alguns comportamentos para criar uma experiência de usuário consistente e unificada. Existem quatro valores possíveis de Cenário:

Reminder
Alarm
IncomingCall
Urgent

Reminders

No cenário de lembrete, a notificação permanecerá na tela até que o usuário a dispense ou tome uma ação. No Windows Mobile, a notificação da aplicação também será exibida já expandida. Um som de lembrete será reproduzido. Você deve fornecer pelo menos um botão na notificação do aplicativo. Caso contrário, a notificação será tratada como uma notificação normal.

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Reminder);

var builder = new ToastContentBuilder()
    .AddText("Notification text.")
    .SetToastScenario(ToastScenario.Reminder)

<toast scenario='reminder'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
</toast>

Alarmes

Os alarmes comportam-se da mesma forma que os lembretes, exceto que os alarmes irão adicionalmente repetir o áudio com um som de alarme padrão. Você deve fornecer pelo menos um botão na notificação do aplicativo. Caso contrário, a notificação será tratada como uma notificação normal.

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Alarm)
    .AddButton(new AppNotificationButton("Dismiss")
        .AddArgument("action", "dismiss"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .SetToastScenario(ToastScenario.Alarm)
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss"));

<toast scenario='alarm'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Dismiss' arguments='action=dismiss'/>
    </actions>
</toast>

Chamadas recebidas

As notificações de chamadas recebidas são exibidas pré-expandidas em um formato de chamada especial e permanecem na tela do usuário até serem descartadas. O áudio do toque será repetido por padrão. Em dispositivos Windows Mobile, eles exibem tela inteira.

Notificação de chamada recebida

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
    .AddText("incoming call - mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///images/profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Text reply")
        .SetToolTip("Text reply")
        .SetIcon(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new AppNotificationButton("Reminder")
        .SetToolTip("Reminder")
        .SetIcon(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new AppNotificationButton("Ignore")
        .SetToolTip("Ignore")
        .SetIcon(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new AppNotificationButton("Answer")
        .SetToolTip("Answer")
        .SetIcon(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

var builder = new ToastContentBuilder()
    .SetToastScenario(ToastScenario.IncomingCall)
    .AddText("Andrew Bares")
    .AddText("incoming call - mobile")
    .AddInlineImage(new Uri("ms-appx:///images/profile.png"), 
        "Andrew Bares",
        null,
        AdaptiveImageCrop.Circle)
    .AddButton(new ToastButton()
        .SetContent("Text reply")
        .SetImageUri(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Reminder")
        .SetImageUri(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Ignore")
        .SetImageUri(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Answer")
        .SetImageUri(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

<toast scenario='incomingCall'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>incoming call - mobile</text>
            <image src='ms-appx:///images/profile.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='Text reply' 
            arguments='textId=123' 
            imageUri='ms-appx:///images/reply.png' 
            hint-toolTip='Text reply'/>
        <action 
                content='Reminder' 
                arguments='reminderId=123' 
                imageUri='ms-appx:///images/reminder.png' 
                hint-toolTip='Reminder'/>
        <action 
                content='Ignore' 
                arguments='ignoreId=123' 
                imageUri='ms-appx:///images/ignore.png' 
                hint-toolTip='Ignore'/>
        <action 
            content='Answer' 
            arguments='answerId=123' 
            imageUri='ms-appx:///images/answer.png' 
            hint-toolTip='Answer'/>
    </actions>
</toast>

Notificações Importantes

Important

Requer: Você deve estar executando o Windows Insider Preview Build 22546 ou posterior para usar notificações importantes.

Notificações importantes permitem que os usuários tenham mais controle sobre quais aplicativos de 1ª e 3ª parte podem enviar notificações de aplicativos de alta prioridade (urgentes/importantes) que podem quebrar o Focus Assist (Não perturbe). Isso pode ser modificado nas configurações de notificações.

Uma captura de tela de uma notificação urgente do aplicativo que tem um ponto de exclamação na área de atribuição ao lado do nome do aplicativo. A imagem também mostra a notificação do aplicativo iniciado pelo sistema que fornece botões para o usuário permitir ou não notificações urgentes do aplicativo.

var builder = new AppNotificationBuilder()
    .AddText("Adaptive Tiles Meeting", 
        new AppNotificationTextProperties()
            .SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

if (AppNotificationBuilder.IsUrgentScenarioSupported())
{
    builder.SetScenario(AppNotificationScenario.Urgent);
}

// The builder syntax does not support important notifications yet.

<toast scenario='urgent'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

Localização e acessibilidade

Seus blocos e notificações de aplicativos podem carregar cadeias de caracteres e imagens personalizadas para idioma de exibição, fator de escala de exibição, alto contraste e outros contextos de tempo de execução. Para mais informações, veja Suporte a notificações de bloco e aviso emergente para idioma, escala e alto contraste.

Manuseio de ativação

Para saber como lidar com ativações de aplicações (o utilizador clicando na sua notificação ou botões na notificação), consulte Enviar notificação local.

Feedback

Esta página foi útil?

Last updated on 2025-11-19

Partilhar via

Conteúdo de notificação do aplicativo

Como Começar

Estrutura de notificação do aplicativo

Área de atribuição

Visual

Elementos de texto

Imagem em linha

Substituição do logótipo da aplicação

Recorte de dicas

Imagem de herói

Restrições de tamanho de imagem

Texto de atribuição

Carimbo temporal personalizado

Barra de progresso

Headers

Conteúdo adaptativo

Colunas e elementos de texto

Buttons

Botões com ícones

Botões com cores

Ações do menu de contexto

Inputs

Caixa de texto de resposta rápida

Entradas com barra de botões

Entrada de seleção

Snooze/dismiss

Audio

Scenarios

Reminders

Alarmes

Chamadas recebidas

Notificações Importantes

Localização e acessibilidade

Manuseio de ativação

Tópicos relacionados

Feedback

Recursos adicionais