AnimatedIcon

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

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

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

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

动画搜索图标

这是正确的控件吗?

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

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

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

如果不需要动画图标,请改用 FontIconSymbolIconBitmapIcon

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 SDKWinUI 3 的应用优化的,但通常适用于使用 WinUI 2 的 UWP 应用。 有关特定于平台的信息和示例,请查看 UWP API 参考。

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

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

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

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

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