Dica de ensino

Uma dica didática é uma janela semipermanente e rica em conteúdo que fornece informações contextuais. Geralmente, é usada para informar, lembrar e ensinar os usuários sobre recursos novos e importantes que podem aprimorar a experiência.

Uma dica de ensino pode ser fechada automaticamente (light dismiss) ou exigir uma ação explícita para ser fechada. Uma dica de ensino pode direcionar para um elemento específico da interface do usuário com sua cauda e também pode ser usada sem cauda ou alvo.

Esse é o controle correto?

Use um controle TeachingTip para concentrar a atenção do usuário em atualizações e recursos novos ou importantes, lembrar um usuário de opções não essenciais que melhorariam sua experiência ou ensinar um usuário como uma tarefa deve ser concluída.

Como a dica de ensino é transitória, não seria o controle recomendado para avisar os usuários sobre erros ou alterações de status importantes.

Recommendations

As dicas não são permanentes e não devem conter informações ou opções críticas para a experiência de um aplicativo.
Tente evitar mostrar dicas de ensino com muita frequência. As dicas de ensino têm maior probabilidade de receber atenção individual quando são distribuídas ao longo de longas sessões ou em várias sessões.
As dicas precisam ser breves e o tópico deve ser claro. Pesquisas mostram que, em média, os usuários só leem de três a cinco palavras e compreendem somente duas a três palavras antes de decidir se querem interagir com uma dica.
A acessibilidade de uma dica de ensino no gamepad não é garantida. Para aplicativos que preveem entrada do gamepad, consulte interações de gamepad e controle remoto. É recomendável fazer o teste de acessibilidade de cada dica de ensino no gamepad com todas as configurações possíveis da interface do usuário do aplicativo.
Ao habilitar uma dica de ensino para escapar da raiz XAML, é recomendável também habilitar a propriedade IsLightDismissEnabled e definir o modo PreferredPlacement mais próximo do centro da raiz XAML.

Reconfigurar uma dica aberta de ensino

É possível reconfigurar alguns conteúdos e propriedades enquanto a dica de ensino está aberta. As alterações entrarão em vigor imediatamente. Outros conteúdos e propriedades, como a propriedade de ícone, os botões Ação e Fechar e a reconfiguração entre descarte leve e descarte explícito, exigirão que a dica de ensino precise ser fechada e reaberta para que alterações nessas propriedades entrem em vigor. Alterar o comportamento de ignorar de manual para light dismiss enquanto uma dica de ensino está aberta fará com que o botão Fechar seja removido antes que o comportamento de light dismiss seja habilitado e a dica pode ficar paralisada na tela.

Exemplos

Uma dica de ensino pode ter várias configurações, incluindo essas mais notáveis:

Uma dica de ensino pode direcionar um elemento específico da interface do usuário com sua cauda para aprimorar a clareza do contexto das informações que está apresentando.

Quando as informações apresentadas não pertencem a um elemento específico da interface do usuário, é possível remover a cauda e criar uma dica de ensino sem alvo.

Um aplicativo de exemplo com uma dica de ensino no canto inferior direito. O título da dica diz "Salvando automaticamente" e o subtítulo diz "Salvamos suas alterações conforme você vai - para que você nunca precise". Há um botão fechar no canto superior direito da dica de ensino.

Uma dica de ensino pode exigir que o usuário a ignore por meio do botão "X" no canto superior ou pelo botão "Fechar" na parte inferior. Além disso, uma dica de ensino pode ser habilitada com a função de fechamento automático. Nesse caso, não haverá um botão para ignorá-la e ela desaparecerá quando o usuário rolar a tela ou interagir com outros elementos do aplicativo. Por causa desse comportamento, dicas que desaparecem automaticamente são a melhor solução quando uma dica precisa ser colocada em uma área de rolagem.

Um aplicativo de exemplo com uma dica de ensino light-dismiss no canto inferior direito. O título da dica diz "Salvar automaticamente" e o subtítulo diz "Salvamos as suas alterações dinamicamente — para que você nunca precise se preocupar com isso".

Criar uma dica de ensino

APIs importantes:classe TeachingTip

Abra o aplicativo da Galeria do WinUI 3 e veja a Dica de Ensino em ação

Ícone da Galeria do WinUI 3 O aplicativo Da Galeria do WinUI 3 inclui exemplos interativos de controles e recursos do WinUI. Obtenha o aplicativo na Microsoft Store ou navegue pelo código-fonte em GitHub.

Aqui está o XAML para um controle de dica de ensino direcionado que demonstra o visual padrão do TeachingTip com título e subtítulo. Note que a dica de ensino pode aparecer em qualquer local na árvore de elementos ou no código subjacente. No exemplo a seguir, está localizada em um ResourceDictionary.

<Button x:Name="SaveButton" Content="Save">
    <Button.Resources>
        <TeachingTip x:Name="AutoSaveTip"
            Target="{x:Bind SaveButton}"
            Title="Save automatically"
            Subtitle="When you save your file to OneDrive, we save your changes as you go - so you never have to.">
        </TeachingTip>
    </Button.Resources>
</Button>

public MainPage()
{
    this.InitializeComponent();

    if(!HaveExplainedAutoSave())
    {
        AutoSaveTip.IsOpen = true;
        SetHaveExplainedAutoSave();
    }
}

Veja o resultado quando a página que contém o botão e a dica de ensino é mostrada:

No exemplo acima, as propriedades Título e Subtítulo são usadas para definir o título e o subtítulo da dica de ensino. A propriedade Target é definida como "SaveButton" para estabelecer a conexão visual entre si e o botão. Para mostrar a dica de ensino, sua propriedade IsOpen é definida como .

Dicas sem alvo

Nem todas as dicas estão associadas a um elemento na tela. Nesses cenários, não defina um destino e a dica de ensino será exibida nas bordas da raiz XAML. No entanto, é possível remover a cauda de uma dica de ensino e manter a posição em relação a um elemento da interface do usuário definindo a propriedade TailVisibility como "Recolhida". O exemplo a seguir mostra uma dica de ensino sem alvo.

<Button x:Name="SaveButton" Content="Save" />

<TeachingTip x:Name="AutoSaveTip"
    Title="Saving automatically"
    Subtitle="We save your changes as you go - so you never have to.">
</TeachingTip>

Neste exemplo, observe que TeachingTip está na árvore de elementos, e não em ResourceDictionary ou no code-behind. Isso não afeta o comportamento. TeachingTip só é exibido quando aberto e não ocupa espaço no layout.

Posição preferencial

A dica de ensino replica o comportamento de posicionamento FlyoutPlacementMode do submenu com a propriedade PreferredPlacement. O modo de posicionamento padrão tentará colocar uma dica interativa direcionada acima de seu alvo e uma dica interativa não direcionada centralizada na parte inferior da base XAML. Assim como no Flyout, se o modo de posicionamento preferido não deixar espaço para a dica instrutiva ser exibida, outro modo de posicionamento será escolhido automaticamente.

Para aplicativos que preveem entrada do gamepad, consulte interações de gamepad e controle remoto. É recomendável fazer o teste de acessibilidade de cada dica de ensino no gamepad com todas as configurações possíveis da interface do usuário do aplicativo.

Uma dica de ensino com alvo e PreferredPlacement definido como "BottomLeft" será exibida com a cauda centralizada na parte inferior do alvo. O corpo da dica de ensino ficará deslocado para a esquerda.

<Button x:Name="SaveButton" Content="Save">
    <Button.Resources>
        <TeachingTip x:Name="AutoSaveTip"
            Target="{x:Bind SaveButton}"
            Title="Saving automatically"
            Subtitle="We save your changes as you go - so you never have to."
            PreferredPlacement="BottomLeft">
        </TeachingTip>
    </Button.Resources>
</Button>

Um aplicativo de exemplo com um botão "Salvar" com uma dica de ensino dirigida a ele, posicionada abaixo do canto esquerdo. O título da dica diz "Salvamento automático" e o subtítulo diz "Salvamos as suas alterações automaticamente — para que você nunca precise se preocupar com isso". Há um botão para fechar no canto superior direito da dica de ensino.

Uma dica de ensino sem alvo, com PreferredPlacement definido como "BottomLeft", será exibida no canto inferior esquerdo da raiz XAML.

<Button x:Name="SaveButton" Content="Save" />

<TeachingTip x:Name="AutoSaveTip"
    Title="Saving automatically"
    Subtitle="We save your changes as you go - so you never have to."
    PreferredPlacement="BottomLeft">
</TeachingTip>

Um aplicativo de exemplo com uma dica de ensino no canto inferior esquerdo. O título da dica diz "Salvando automaticamente" e o subtítulo diz "Salvamos suas alterações conforme você vai - para que você nunca precise". Há um botão fechar no canto superior direito da dica de ensino.

O diagrama a seguir mostra o resultado dos 13 modos PreferredPlacement que podem ser definidos para dicas direcionadas de ensino. Ilustração contendo 13 dicas de ensino, cada uma demonstrando um modo de posicionamento direcionado diferente. Cada dica de ensino é rotulada com o modo que ela representa. A primeira palavra de um modo de posicionamento indica o lado do destino em que a dica de ensino aparecerá centralizada. A parte final da dica de ensino sempre estará localizada no centro desse lado do destino e apontará para o destino. Se houver uma segunda palavra no modo de posicionamento, o corpo da dica de ensino não será centralizado, mas será deslocado na direção especificada. Por exemplo, o modo de posicionamento "TopRight" fará com que a dica de ensino apareça acima do destino e deslocada para a direita, com sua parte final apontando para baixo no centro da borda superior do destino. Como o corpo é deslocado para a direita, a parte final está quase na borda mais à esquerda do corpo da dica de ensino, e a dica de ensino se estende além da borda direita do destino. O modo de posicionamento "Centralizado" é exclusivo e fará com que a parte final da dica de ensino seja posicionada no centro do destino e a dica de ensino seja centralizada sobre o a metade superior do destino.

O diagrama a seguir mostra o resultado de todos os 13 modos de colocação preferencial que podem ser configurados para dicas de ensino não direcionadas. Ilustração contendo nove dicas de ensino, cada uma demonstrando um modo de posicionamento diferente não direcionado. Cada dica de ensino é rotulada com o modo que representa. A primeira palavra de um modo de posicionamento indica o lado da raiz xaml na qual a dica de ensino aparecerá centralizada. Se houver uma segunda palavra no modo de posicionamento, a dica de ensino se posicionará em direção a esse canto especificado da raiz xaml. Por exemplo, o modo de posicionamento "TopRight" fará com que a dica de ensino apareça no canto superior direito da raiz xaml. Para modos de posicionamento não direcionados, a ordem das duas palavras não afeta o posicionamento. TopRight é equivalente a RightTop. O modo de posicionamento "Centro" é exclusivo e fará com que a dica de ensino apareça no centro vertical e horizontal da raiz xaml.

Adicionar uma margem de posicionamento

Você pode controlar até que ponto uma dica de ensino direcionada está separada de seu destino e até que ponto uma dica de ensino não direcionada é separada das bordas da raiz xaml usando a propriedade PlacementMargin . Assim como Margin, PlacementMargin tem quatro valores – esquerdo, direito, superior e inferior – para que apenas os valores relevantes sejam usados. Por exemplo, PlacementMargin.Left é usado quando o tooltip está à esquerda do alvo ou na borda esquerda da raiz XAML.

O exemplo a seguir mostra uma dica não direcionada com as margens esquerda, superior, direita e inferior do PlacementMargin todas definidas como 80.

<Button x:Name="SaveButton" Content="Save" />

<TeachingTip x:Name="AutoSaveTip"
    Title="Saving automatically"
    Subtitle="We save your changes as you go - so you never have to."
    PreferredPlacement="BottomLeft"
    PlacementMargin="80">
</TeachingTip>

Um aplicativo de exemplo com uma dica de ensino posicionada próxima ao canto inferior direito, mas não totalmente sobre ele. O título da dica diz "Salvamento automático" e o subtítulo diz "Salvamos as suas alterações automaticamente — para que você nunca precise se preocupar com isso". Há um botão para fechar no canto superior direito da dica de ensino.

Adicionar conteúdo

O conteúdo pode ser adicionado a uma dica de ensino usando a propriedade Content . Se o conteúdo a ser mostrado for maior que o tamanho permitido pela dica de ensino, uma barra de rolagem será automaticamente habilitada para que o usuário possa rolar a área de conteúdo.

<Button x:Name="SaveButton" Content="Save">
    <Button.Resources>
        <TeachingTip x:Name="AutoSaveTip"
            Target="{x:Bind SaveButton}"
            Title="Saving automatically"
            Subtitle="We save your changes as you go - so you never have to.">
                <StackPanel>
                    <CheckBox x:Name="HideTipsCheckBox" Content="Don't show tips at start up" IsChecked="{x:Bind HidingTips, Mode=TwoWay}" />
                    <TextBlock>You can change your tip preferences in <Hyperlink NavigateUri="app:/item/SettingsPage">Settings</Hyperlink> if you change your mind.</TextBlock>
                </StackPanel>
        </TeachingTip>
    </Button.Resources>
</Button>

Um aplicativo de exemplo com uma dica de ensino direcionada ao botão salvar. O título da dica diz "Salvamento automático" e o subtítulo diz "Salvamos as suas alterações automaticamente — para que você nunca precise se preocupar com isso". Na área de conteúdo da dica de ensino há uma caixa de seleção com o texto "Não mostrar dicas na inicialização" e abaixo se lê "Você pode alterar as suas preferências de dicas nas Configurações se mudar de ideia" em que "Configurações" é um link para a página das configurações do aplicativo. Há um botão para fechar no canto superior direito da dica de ensino.

Adicionar botões

Por padrão, um botão de "X" para fechar é mostrado ao lado do título de uma dica de ensino. O botão Fechar pode ser personalizado com a propriedade CloseButtonContent. Nesse caso, o botão é movido para a parte inferior da dica de ensino.

Observação: nenhum botão para fechar será exibido em dicas habilitadas para light dismiss

Um botão de ação personalizado pode ser adicionado definindo a propriedade ActionButtonContent (e, opcionalmente, as propriedades ActionButtonCommandCommandParameter).

<Button x:Name="SaveButton" Content="Save">
    <Button.Resources>
        <TeachingTip x:Name="AutoSaveTip"
            Target="{x:Bind SaveButton}"
            Title="Saving automatically"
            Subtitle="We save your changes as you go - so you never have to."
            ActionButtonContent="Disable"
            ActionButtonCommand="{x:Bind DisableAutoSaveCommand}"
            CloseButtonContent="Got it!">
                <StackPanel>
                    <CheckBox x:Name="HideTipsCheckBox" Content="Don't show tips at start up" IsChecked="{x:Bind HidingTips, Mode=TwoWay}" />
                    <TextBlock>You can change your tip preferences in <Hyperlink NavigateUri="app:/item/SettingsPage">Settings</Hyperlink> if you change your mind.</TextBlock>
                </StackPanel>
        </TeachingTip>
    </Button.Resources>
</Button>

Um aplicativo de exemplo com uma dica de ensino direcionada ao botão Salvar. O título da dica diz "Salvamento automático" e o subtítulo diz "Salvamos as suas alterações automaticamente — para que você nunca precise se preocupar com isso". Na área de conteúdo da dica de ensino há uma caixa de seleção com o texto "Não mostrar dicas na inicialização" e abaixo se lê "Você pode alterar as suas preferências de dicas nas Configurações se mudar de ideia" em que "Configurações" é um link para a página das configurações do aplicativo. Na parte inferior do ensino há dois botões, um cinza à esquerda com o texto "Desabilitar" e um azul à direita com o texto "Entendi!"

Conteúdo em destaque

É possível adicionar conteúdo de borda a borda a uma dica de ensino configurando a propriedade HeroContent. Para que o conteúdo em destaque fique na parte superior ou inferior da dica de ensino, configure a propriedade HeroContentPlacement.

<Button x:Name="SaveButton" Content="Save">
    <Button.Resources>
        <TeachingTip x:Name="AutoSaveTip"
            Target="{x:Bind SaveButton}"
            Title="Saving automatically"
            Subtitle="We save your changes as you go - so you never have to.">
            <TeachingTip.HeroContent>
                <Image Source="Assets/cloud.png" />
            </TeachingTip.HeroContent>
        </TeachingTip>
    </Button.Resources>
</Button>

Um aplicativo de exemplo com uma dica de ensino direcionada ao botão salvar. O título da dica diz "Salvando automaticamente" e o subtítulo diz "Salvamos suas alterações conforme você vai - para que você nunca precise". Na parte inferior da dica de ensino está uma imagem borda a borda de um homem de desenho animado colocando arquivos na nuvem. Há um botão fechar no canto superior direito da dica de ensino.

Adicionar um ícone

Um ícone pode ser adicionado ao lado do título e do subtítulo usando a propriedade IconSource . É recomendável usar ícones nos tamanhos de 16px, 24px e 32px.

<Button x:Name="SaveButton" Content="Save">
    <Button.Resources>
        <TeachingTip x:Name="AutoSaveTip"
            Target="{x:Bind SaveButton}"
            Title="Saving automatically"
            Subtitle="We save your changes as you go - so you never have to."
            <TeachingTip.IconSource>
                <SymbolIconSource Symbol="Save" />
            </TeachingTip.IconSource>
        </TeachingTip>
    </Button.Resources>
</Button>

Um aplicativo de exemplo com uma dica de ensino direcionada ao botão salvar. O título da dica diz "Salvando automaticamente" e o subtítulo diz "Salvamos suas alterações conforme você vai - para que você nunca precise". À esquerda do título e do subtítulo está um ícone de disco disquete. Há um botão fechar no canto superior direito da dica de ensino.

Habilitar light dismiss

A funcionalidade light dismiss fica desabilitada por padrão. No entanto, é possível habilitá-la definindo a propriedade IsLightDismissEnabled para que a dica de ensino seja ignorada, por exemplo, quando o usuário rola a tela ou interage com outros elementos do aplicativo. Por causa desse comportamento, dicas que desaparecem automaticamente são a melhor solução quando uma dica precisa ser colocada em uma área de rolagem.

O botão Fechar será automaticamente removido de uma dica de instrução habilitada para light-dismiss, para indicar aos usuários o seu comportamento de light-dismiss.

<Button x:Name="SaveButton" Content="Save" />

<TeachingTip x:Name="AutoSaveTip"
    Title="Saving automatically"
    Subtitle="We save your changes as you go - so you never have to."
    IsLightDismissEnabled="True">
</TeachingTip>

Ultrapassar os limites da raiz XAML

Começando com o Windows 10, versão 1903 (Build 18362), uma dica de instrução pode escapar dos limites da raiz do XAML e da tela ao definir a propriedade ShouldConstrainToRootBounds. Quando essa propriedade está habilitada, a dica de instrução não tentará se manter dentro dos limites da raiz XAML ou da tela e sempre ficará posicionada no modo configurado . É recomendável habilitar a propriedade e definir o modo mais próximo do centro da raiz XAML para garantir a melhor experiência para os usuários.

Em versões anteriores do Windows, essa propriedade é ignorada e a dica de ensino sempre permanece dentro dos limites da raiz XAML.

<Button x:Name="SaveButton" Content="Save" />

<TeachingTip x:Name="AutoSaveTip"
    Title="Saving automatically"
    Subtitle="We save your changes as you go - so you never have to."
    PreferredPlacement="BottomRight"
    PlacementMargin="-80,-50,0,0"
    ShouldConstrainToRootBounds="False">
</TeachingTip>

Um aplicativo de exemplo com uma dica de ensino fora do canto inferior direito do aplicativo. O título da dica diz "Salvando automaticamente" e o subtítulo diz "Salvamos suas alterações conforme você vai - para que você nunca precise". Há um botão fechar no canto superior direito da dica de ensino.

Cancelar e adiar o encerramento

O evento Closing pode ser usado para cancelar e/ou postergar a finalização de uma dica didática. É possível usá-lo para manter a dica de ensino aberta ou dar tempo para que uma ação ou animação personalizada ocorra. Quando o fechamento de uma informação educativa for cancelado, o valor de IsOpen voltará para true. No entanto, ele permanecerá falso durante o adiamento da operação. Um fechamento programático também pode ser cancelado.

Observação

Se nenhuma opção de posicionamento permitir que a dica de ensino completa seja mostrada, a dica de ensino iterará ao longo do ciclo de vida do evento para forçar o fechamento em vez de ser exibida sem um botão Fechar acessível. Se o aplicativo cancelar o evento Closing, a dica de instrução poderá permanecer aberta sem um botão Fechar acessível.

<TeachingTip x:Name="EnableNewSettingsTip"
    Title="New ways to protect your privacy!"
    Subtitle="Please close this tip and review our updated privacy policy and privacy settings."
    Closing="OnTipClosing">
</TeachingTip>

private void OnTipClosing(muxc.TeachingTip sender, muxc.TeachingTipClosingEventArgs args)
{
    if (args.Reason == muxc.TeachingTipCloseReason.CloseButton)
    {
        using(args.GetDeferral())
        {
            bool success = UpdateUserSettings(User thisUsersID);
            if(!success)
            {
                // We were not able to update the settings!
                // Don't close the tip and display the reason why.
                args.Cancel = true;
                ShowLastErrorMessage();
            }
        }
    }
}

Caixas de diálogo e submenus

Comentários

Esta página foi útil?

Last updated on 2026-03-05