AnimatedIcon

项目
07/30/2024

AnimatedIcon 控件可以播放动画图像以响应用户交互和视觉状态的变化。

动画图标可以吸引对 UI 组件（例如教程中的下一个按钮）的注意，或者以一种有趣的方式直接反映与图标关联的操作。

可以使用 Adobe AfterEffects 创建并使用 Lottie-Windows 库渲染自定义动画，以将其用作 WinUI 应用程序中的动画图标。有关详细信息，请参阅本文稍后的使用 Lottie 创建 AnimatedIcon 的动画内容。

以下示例演示了在 Adobe AfterEffects 中创建并通过 Lottie 渲染的基本动画搜索图标。

这是正确的控件吗？

当需要显示控件图标的动画效果来响应用户与控件的交互时（例如，当用户将鼠标悬停在某个按钮上或单击该按钮时），请使用 AnimatedIcon 控件。

如果动画不是由视觉状态过渡触发，并且循环播放、仅播放一次或可暂停，请不要使用 AnimatedIcon，而是改用 AnimatedVisualPlayer。

请不要将 AnimatedIcon 用于除图标以外的任何元素，或者在该控件不支持 IconElement 或 IconElementSource 属性的情况下，也不要使用它。而是改用 AnimatedVisualPlayer。

如果不需要动画图标，请改用 FontIcon、SymbolIcon 或 BitmapIcon。

AnimatedIcon 与 AnimatedVisualPlayer 的差别

AnimatedIcon 是一个 IconElement，可以在需要某个元素或 IconElement 的任何位置（例如 NavigationViewItem.Icon）使用，并可通过 State 属性对其进行控制。

AnimatedVisualPlayer 是一个更通用的动画播放器，可通过 Play 和 Pause 等方法对其进行控制，并可以在应用程序中的任何位置使用。

使用 Lottie 创建 AnimatedIcon 的动画内容

为 AnimatedIcon 定义动画的前几个步骤与为 AnimatedVisualPlayer 定义动画的过程相同。必须创建或获取要添加的图标的 Lottie 文件，并通过 LottieGen 运行该文件。 LottieGen 为 C++/WinRT 类生成代码，可以实例化该类并将其与 AnimatedIcon 一起使用。

注意

AutoSuggestBox 控件使用通过 LottieGen 工具生成的 AnimatedVisuals.AnimatedFindVisualSource 类。

还可以在动画定义中定义标记，以指示播放时间位置。然后，可将 AnimatedIcon 状态设置为这些标记。例如，如果 Lottie 文件中包含标记为“PointerOver”的播放位置，则可将 AnimatedIcon 状态设置为“PointerOver”并将动画移到该播放位置。

在 Lottie 动画中定义一个名为“Foreground”的颜色属性可以使用 AnimatedIcon.Foreground 属性来设置颜色。

建议

请查看 Windows 应用图标的 UX 指南，以确保你的图标符合设计原则。
限制单个屏幕或视图上的动画图标数目。请仅对用于吸引用户的注意力，以提醒他们采取措施或执行操作的图标显示动画效果。

UWP 和 WinUI 2

重要

本文中的信息和示例是针对使用 Windows App SDK 和 WinUI 3 的应用优化的，但通常适用于使用 WinUI 2 的 UWP 应用。有关特定于平台的信息和示例，请查看 UWP API 参考。

本部分包含在 UWP 或 WinUI 2 应用中使用该控件所需的信息。

用于 UWP 应用的 AnimatedIcon 需要 WinUI 2。有关详细信息（包括安装说明），请参阅 WinUI 2。此控件的 API 存在于 Microsoft.UI.Xaml.Controls 命名空间中。

WinUI 2 API：AnimatedIcon 类
打开 WinUI 2 库应用，了解 AnimatedIcon 的实际应用。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

要将本文中的代码与 WinUI 2 配合使用，请使用 XAML 中的别名（我们使用 muxc）来表示项目中包含的 Windows UI 库 API。有关详细信息，请参阅 WinUI 2 入门。

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

<muxc:AnimatedIcon />

创建动画图标

重要 API：AnimatedIcon 类

打开 WinUI 3 库应用以查看 AnimatedIcon 的操作

WinUI 3 库应用包括大多数 WinUI 3 控件、特性和功能的交互式示例。通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码

将 AnimatedIcon 添加到按钮

以下示例演示了一个后退按钮，在发生 PointerEntered 事件时该按钮可显示动画后退图标。

AnimatedBackVisualSource 是使用 LottieGen 命令行工具创建的类。
无法播放动画时（例如，在不支持 Lottie 动画的早期 Windows 版本上）使用 FallbackIconSource。
如果用户在系统设置中关闭了动画，AnimatedIcon 将显示控件所处状态过渡的最后一帧。

<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");
}

将 AnimatedIcon 添加到 NavigationViewItem

如果在 Lottie 动画中定义了这些标记，则 NavigationViewItem 控件会根据控件的状态自动设置 AnimatedIcon 上的常见状态。

例如，以下示例演示了如何设置 LottieGen 工具生成的自定义动画 (GameSettingsIcon)：

<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>

动画设置齿轮

NavigationViewItem 自动在 AnimatedIcon 上设置以下状态：

正常
PointerOver
Pressed
已选择
PressedSelected
PointerOverSelected

如果 GameSettingsIcon 具有为“NormalToPointerOver”定义的标记，则图标将保持动画效果，直到指针移到 NavigationViewItem。有关创建标记的详细信息，请参阅以下部分。

定义 AnimatedIcon 标记

要在上一示例中创建自定义的 GameSettingsIcon，请通过 Windows LottieGen 工具运行 Lottie JSON 文件（包含标记），以将动画代码生成为 C# 类。

通过 LottieGen 运行 Lottie 文件后，可将 CodeGen 输出类添加到项目。有关详细信息，请参阅 LottieGen 教程。

将 AnimatedIcon 状态设置为新值还会在 Lottie 动画中设置播放位置，以便从旧状态过渡到新状态。这些播放位置也通过 Lottie 文件中的标记进行标识。还可以定义过渡开始位置或过渡结束位置的特定标记。

例如，AutoSuggestBox 控件使用一个通过以下状态播放动画的 AnimatedIcon：

正常
PointerOver
Pressed

可以在 Lottie 文件中使用这些状态名称定义标记。还可以按如下所示定义标记：

在状态名称之间插入“To”。例如，如果你要定义“NormalToPointerOver”标记，将 AnimatedIcon 状态从“Normal”更改为“PointerOver”会导致该控件移到此标记的播放位置。
在标记名称中追加“_Start”或“_End”。例如，定义标记“NormalToPointerOver_Start”和“NormalToPointerOver_End”并将 AnimatedIcon 状态从“Normal”更改为“PointerOver”，会导致该控件跳转到 _Start 标记的播放位置，然后在 _End 播放位置显示动画。

用于将 AnimatedIcon 状态更改映射到标记播放位置的确切算法：

检查所提供文件的标记中是否存在标记“[PreviousState]To[NewState]_Start”和“[PreviousState]To[NewState]_End”。如果找到了这两个标记，则播放从“[PreviousState]To[NewState]_Start”到“[PreviousState]To[NewState]_End”的动画。
如果找不到“[PreviousState]To[NewState]_Start”但找到了“[PreviousState]To[NewState]_End”，则强行切换到“[PreviousState]To[NewState]_End”播放位置。
如果找不到“[PreviousState]To[NewState]_End”但找到了“[PreviousState]To[NewState]_Start”，则强行切换到“[PreviousState]To[NewState]_Start”播放位置。
检查所提供的 IAnimatedVisualSource2 的标记中是否存在标记“[PreviousState]To[NewState]”。如果找到该标记，则强行切换到“[PreviousState]To[NewState]”播放位置。
检查所提供的 IAnimatedVisualSource2 的标记中是否存在标记“[NewState]”。如果找到该标记，则强行切换到“[NewState]”播放位置。
检查所提供的 IAnimatedVisualSource2 的标记中是否存在任何以“To[NewState]_End”结尾的标记。如果找到任何以该字符串结尾的标记，则强行切换到所找到的、具有相应末尾播放位置的第一个标记。
检查“[NewState]”是否分析为浮点值。如果是，则播放从当前位置到分析的浮点值处的动画。
强行切换到播放位置 0.0。

以下示例演示了 Lottie JSON 文件中的标记格式。有关更多详细信息，请参阅 AnimatedIcon 指南。

"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}]

添加独立的 AnimatedIcon

以下示例是用户单击的用于接受提示的按钮。

MyAcceptAnimation 类是使用 LottieGen 工具创建的。

无法播放动画时（例如，在不支持 Lottie 动画的早期 Windows 版本上），将使用 FallbackIconSource 而不是动画。

如果最终用户在系统设置中关闭了动画，AnimatedIcon 将显示控件所处状态过渡的最后一帧。

<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");
}

通过