AnimatedIcon

  • Artigo

Um controle AnimatedIcon reproduz imagens animadas em resposta à interação do usuário e às alterações de estado visual.

Ícones animados podem chamar a atenção para um componente de interface do usuário, como o próximo botão em um tutorial, ou simplesmente refletir a ação associada ao ícone de maneira divertida e interessante.

Animações personalizadas podem ser criadas com Adobe AfterEffects e renderizadas com a biblioteca Lottie-Windows para usar como um ícone animado em seu aplicativo WinUI. Para obter mais detalhes, consulte Usar Lottie para criar conteúdo animado para um AnimatedIcon mais adiante neste artigo.

O exemplo a seguir mostra um ícone de pesquisa animado básico que foi criado no Adobe AfterEffects e renderizado por meio de Lottie.

Um ícone de pesquisa animado

Esse é o controle correto?

Use o controle AnimatedIcon quando o ícone de um controle precisar ser animado em resposta à interação do usuário com o controle, como quando um usuário passa o mouse sobre um botão ou clica nele.

Não use um AnimatedIcon se a animação não for disparada por uma transição de estado visual e for reproduzida em um loop, reproduzida apenas uma vez ou puder ser pausada. Em vez disso, use AnimatedVisualPlayer.

Não use AnimatedIcon para nada além de um ícone ou onde o controle não dá suporte a uma propriedade IconElement ou IconElementSource. Em vez disso, use AnimatedVisualPlayer.

Quando um ícone animado não for necessário, use FontIcon, SymbolIcon ou BitmapIcon .

Diferenças entre AnimatedIcon e AnimatedVisualPlayer

AnimatedIcon é um IconElement, que pode ser usado em qualquer lugar em que um elemento ou IconElement é necessário (como NavigationViewItem.Icon) e é controlado por meio de uma propriedade State.

AnimatedVisualPlayer é um player de animação mais geral, que é controlado por meio de métodos como Reproduzir e Pausar e pode ser usado em qualquer lugar em um aplicativo.

Usar Lottie para criar conteúdo animado para um AnimatedIcon

Definir uma animação para um AnimatedIcon começa da mesma forma que o processo para definir uma animação para um AnimatedVisualPlayer. Você deve criar ou obter o arquivo Lottie para o ícone que deseja adicionar e executar esse arquivo por meio da LottieGen. O LottieGen gera um código para uma classe do C++/WinRT cuja instância você pode criar e usar com um AnimatedIcon.

Observação

O controle AutoSuggestBox usa a classe AnimatedVisuals.AnimatedFindVisualSource , que foi gerada usando a ferramenta LottieGen.

Você também pode definir marcadores na definição de animação para indicar posições de tempo de reprodução. Em seguida, você pode definir o estado AnimatedIcon para esses marcadores. Por exemplo, se você tiver uma posição de reprodução no arquivo Lottie marcada como "PointerOver", poderá definir o estado AnimatedIcon como "PointerOver" e mover a animação para essa posição de reprodução.

Definir uma propriedade de cor em sua animação Lottie chamada "Primeiro plano" permite definir a cor usando a propriedade AnimatedIcon.Foreground.

Recomendações

  • Veja as diretrizes de experiência do usuário para Ícones para Aplicativos do Windows para garantir que seus ícones correspondam aos princípios de design.
  • Limite o número de ícones animados em uma única tela ou exibição. Animar apenas ícones para chamar a atenção do usuário para onde ele precisa executar uma ação ou quando estiver executando uma ação.

UWP e WinUI 2

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API da UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.

O AnimatedIcon para aplicativos UWP requer a Biblioteca de Interface do Usuário do Windows 2. Para obter mais informações, incluindo instruções de instalação, confira Biblioteca de interface do usuário do Windows. As APIs para esse controle existem no namespace Microsoft.UI.Xaml.Controls .

Para usar o código neste artigo com a WinUI 2, use um alias em XAML (usamos muxc) para representar as APIs da Biblioteca de Interface do Usuário do Windows incluídas em seu projeto. Confira Introdução à WinUI 2 para obter mais informações.

xmlns:muxc="using:Microsoft.UI.Xaml.Controls"

<muxc:AnimatedIcon />

Criar um ícone animado

Abra o aplicativo Galeria do WinUI 3 e veja o AnimatedIcon em ação.

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub

Adicionar um AnimatedIcon a um botão

O exemplo a seguir demonstra um botão Voltar que exibe um ícone de fundo animado em um evento PointerEntered .

  • O AnimatedBackVisualSource é uma classe criada com a ferramenta de linha de comando LottieGen .
  • O FallbackIconSource é usado quando animações não podem ser reproduzidas, como em versões mais antigas do Windows que não dão suporte a animações Lottie.
  • Se o usuário desativar as animações nas configurações do sistema, AnimatedIcon exibirá o quadro final da transição de estado em que os controles estavam.
<Button PointerEntered="Button_PointerEntered" PointerExited="Button_PointerExited">
    <AnimatedIcon x:Name='BackAnimatedIcon'>
        <AnimatedIcon.Source>
            <animatedvisuals:AnimatedBackVisualSource/>
        </AnimatedIcon.Source>
        <AnimatedIcon.FallbackIconSource>
            <SymbolIconSource Symbol='Back'/>
        </AnimatedIcon.FallbackIconSource>
    </AnimatedIcon>
</Button>

private void Button_PointerEntered(object sender, PointerRoutedEventArgs e)
{
    AnimatedIcon.SetState(this.BackAnimatedIcon, "PointerOver");
}

private void Button_PointerExited(object sender, PointerRoutedEventArgs e)
{
    AnimatedIcon.SetState(this.BackAnimatedIcon, "Normal");
}

Adicionar um AnimatedIcon ao NavigationViewItem

O controle NavigationViewItem define automaticamente estados comuns em um AnimatedIcon com base no estado do controle, se esses marcadores forem definidos na animação Lottie.

Por exemplo, o exemplo a seguir mostra como definir uma animação personalizada (GameSettingsIcon) que foi gerada pela ferramenta LottieGen:

<NavigationView.MenuItems>
    <NavigationViewItem Content = "Game Settings">
        <NavigationViewItem.Icon>
            <AnimatedIcon x:Name='GameSettingsIcon'>
                <AnimatedIcon.Source>
                    <animatedvisuals:AnimatedSettingsVisualSource/>
                </AnimatedIcon.Source>
                <AnimatedIcon.FallbackIconSource>
                    <FontIconSource FontFamily="Segoe MDL2 Assets" Glyph="&#xE713;"/>
                </AnimatedIcon.FallbackIconSource>
            </AnimatedIcon>
        </NavigationViewItem.Icon>
    </NavigationViewItem>
</NavigationView.MenuItems>

Engrenagem de Configurações Animadas

O NavigationViewItem define automaticamente os seguintes estados no AnimatedIcon:

  • Normal
  • PointerOver
  • Pressionado
  • Selecionado
  • PressedSelected
  • PointerOverSelected

Se GameSettingsIcon tiver um marcador definido para "NormalToPointerOver", o ícone será animado até que o ponteiro se mova sobre NavigationViewItem. Consulte a seção a seguir para obter mais informações sobre como criar marcadores.

Definir marcadores AnimatedIcon

Para criar o personalizado GameSettingsIcon no exemplo anterior, execute um arquivo JSON Lottie (com marcadores) por meio da ferramenta LottieGen do Windows para gerar o código de animação como uma classe C#.

Depois de executar o arquivo Lottie por meio do LottieGen, você poderá adicionar a classe de saída CodeGen ao seu projeto. Confira o tutorial LottieGen para obter mais informações.

Definir o estado AnimatedIcon como um novo valor também define uma posição de reprodução na animação Lottie para a transição do estado antigo para o novo estado. Essas posições de reprodução também são identificadas com marcadores no arquivo Lottie. Marcadores específicos para o início da transição ou o final da transição também podem ser definidos.

Por exemplo, o controle AutoSuggestBox usa um AnimatedIcon que anima com os seguintes estados:

  • Normal
  • PointerOver
  • Pressionado

Você pode definir marcadores no arquivo Lottie com esses nomes de estado. Você também pode definir marcadores da seguinte maneira:

  • Insira "To" entre nomes de estado. Por exemplo, se você definir um marcador "NormalToPointerOver", alterar o estado AnimatedIcon de "Normal" para "PointerOver" fará com que ele se mova para a posição de reprodução desse marcador.
  • Acrescente "_Start" ou "_End" a um nome de marcador. Por exemplo, definir marcadores "NormalToPointerOver_Start" e "NormalToPointerOver_End" e alterar o estado AnimatedIcon de "Normal" para "PointerOver" fará com que ele pule para a posição de reprodução do marcador de _Start e, em seguida, anime para a posição de reprodução _End.

O algoritmo exato usado para mapear alterações de Estado AnimatedIcon para posições de reprodução de marcador:

  • Verifique os marcadores do arquivo fornecido para os marcadores "[PreviousState]To[NewState]_Start" e "[PreviousState]To[NewState]_End". Se ambos forem encontrados, reproduza a animação de "[PreviousState]To[NewState]_Start" para "[PreviousState]To[NewState]_End".
  • Se "[PreviousState]To[NewState]_Start" não for encontrado, mas "[PreviousState]To[NewState]_End" for encontrado, corte na posição de reprodução "[PreviousState]To[NewState]_End".
  • Se "[PreviousState]To[NewState]_End" não for encontrado, mas "[PreviousState]To[NewState]_Start" for encontrado, corte na posição de reprodução "[PreviousState]To[NewState]_Start".
  • Verifique se os marcadores de IAnimatedVisualSource2 fornecidos para o marcador "[PreviousState]To[NewState]". Se for encontrado, corte na posição de reprodução "[PreviousState]To[NewState]".
  • Verifique se os marcadores de IAnimatedVisualSource2 fornecidos para o marcador "[NewState]". Se for encontrado, corte na posição de reprodução "[NewState]".
  • Verifique se os marcadores de IAnimatedVisualSource2 fornecidos têm qualquer marcador que termine com "To[NewState]_End". Se algum marcador for encontrado que tenha essa finalização, corte duro para o primeiro marcador encontrado com a posição de reprodução do final apropriado.
  • Verifique se "[NewState]" analisa um float. Se isso acontecer, animado da posição atual para o float analisado.
  • Corte rígido para a posição de reprodução 0,0.

O exemplo a seguir mostra o formato de marcador em um arquivo JSON Lottie. Consulte as diretrizes do AnimatedIcon para obter mais detalhes.

"markers":[{"tm":0,"cm":"NormalToPointerOver_Start","dr":0},{"tm":9,"cm":"NormalToPointerOver_End","dr":0},

{"tm":10,"cm":"NormalToPressed_Start","dr":0},{"tm":19,"cm":"NormalToPressed_End","dr":0},

{"tm":20,"cm":"PointerOverToNormal_Start","dr":0},{"tm":29,"cm":"PointerOverToNormal_End","dr":0},

{"tm":30,"cm":"PointerOverToPressed_Start","dr":0},{"tm":39,"cm":"PointerOverToPressed_End","dr":0},

{"tm":40,"cm":"PressedToNormal_Start","dr":0},{"tm":49,"cm":"PressedToNormal_End","dr":0},

{"tm":50,"cm":"PressedToPointerOver_Start","dr":0},{"tm":69,"cm":"PressedToPointerOver_End","dr":0},

{"tm":90,"cm":"PressedToNormal_Start","dr":0},{"tm":99,"cm":"PressedToNormal_End","dr":0},

{"tm":100,"cm":"PressedToPointerOver_Start","dr":0},{"tm":101,"cm":"PressedToPointerOver_End","dr":0}]

Adicionando um AnimatedIcon autônomo

O exemplo a seguir é um botão em que o usuário clica em Aceitar um prompt.

A MyAcceptAnimation classe é criada com a ferramenta LottieGen .

O FallbackIconSource será usado em vez da animação quando as animações não puderem ser reproduzidas, como em versões mais antigas do Windows que não dão suporte a animações Lottie.

Se o usuário final desativar animações nas configurações do sistema, AnimatedIcon exibirá o quadro final da transição de estado em que os controles estavam.

<Button PointerEntered="HandlePointerEntered" PointerExited="HandlePointerExited">
    <AnimatedIcon x:Name='AnimatedIcon1'>
        <local:MyAcceptAnimation/>
        <AnimatedIcon.FallbackIconSource>
            <SymbolIconSource Symbol='Accept'/>
        </AnimatedIcon.FallbackIconSource>
    </AnimatedIcon>
</Button>

private void Button_PointerEntered(object sender, PointerRoutedEventArgs e)
{
    AnimatedIcon.SetState(this.AnimatedIcon1, "PointerOver");
}

private void Button_PointerExited(object sender, PointerRoutedEventArgs e)
{
    AnimatedIcon.SetState(this.StackPaAnimatedIcon1nel1, "Normal");
}