AnimatedIcon 類別

定義

命名空間:

Microsoft.UI.Xaml.Controls

表示圖示，顯示及控制可產生動畫效果的視覺效果，以回應使用者互動和視覺狀態變更。

本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.XamlContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.UI.Xaml.Markup.ContentProperty(Name="Source")]
class AnimatedIcon : IconElement

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.XamlContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.UI.Xaml.Markup.ContentProperty(Name="Source")]
public class AnimatedIcon : IconElement

Public Class AnimatedIcon
Inherits IconElement

繼承

IconElement

AnimatedIcon

屬性

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute

範例

提示

如需詳細資訊、設計指引和程式碼範例，請參閱 動畫圖標。

開啟 WinUI 2 資源庫應用程式，並查看 AnimatedIcon 運作情形。

WinUI 2 資源庫應用程式包含大部分 WinUI 2 控制項、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub上取得原始程式碼。

將 AnimatedIcon 新增至按鈕

這個範例示範一個上一頁按鈕，該按鈕會顯示在發生指標事件時產生動畫效果的返回箭號圖示。

• AnimatedBackVisualSource是 WinUI 提供的反向箭號動畫。
• 無法播放動畫時，會使用 FallbackIconSource 。
• 已設定為 true 的AddHandler方法 handledEventsToo 會用於按鈕標示為Handled的事件。

<!-- 
xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
xmlns:animatedvisuals="using:Microsoft.UI.Xaml.Controls.AnimatedVisuals"
-->

<AppBarButton x:Name="BackButton" Label="Back"
              muxc:AnimatedIcon.State="Normal"
              PointerEntered="AppBarButton_PointerEntered"
              PointerExited="AppBarButton_PointerExited">
    <muxc:AnimatedIcon>
        <animatedvisuals:AnimatedBackVisualSource/>
        <muxc:AnimatedIcon.FallbackIconSource>
            <muxc:SymbolIconSource Symbol="Back"/>
        </muxc:AnimatedIcon.FallbackIconSource>
    </muxc:AnimatedIcon>
</AppBarButton>

// using muxc = Microsoft.UI.Xaml.Controls;

// Add handlers.
protected override void OnNavigatedTo(NavigationEventArgs e)
{
    SettingsButton.AddHandler(UIElement.PointerPressedEvent, 
        new PointerEventHandler(AppBarButton_PointerPressed), true);
    SettingsButton.AddHandler(UIElement.PointerReleasedEvent, 
        new PointerEventHandler(AppBarButton_PointerReleased), true);
    base.OnNavigatedTo(e);
}

// Remove handlers.
protected override void OnNavigatedFrom(NavigationEventArgs e)
{
    SettingsButton.RemoveHandler(UIElement.PointerPressedEvent, 
        (PointerEventHandler)AppBarButton_PointerPressed);
    SettingsButton.RemoveHandler(UIElement.PointerReleasedEvent, 
        (PointerEventHandler)AppBarButton_PointerReleased);
    base.OnNavigatedFrom(e);
}

private void AppBarButton_PointerEntered(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "PointerOver");
}

private void AppBarButton_PointerPressed(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "Pressed");
}

private void AppBarButton_PointerReleased(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "Normal");
}

private void AppBarButton_PointerExited(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "Normal");
}

備註

設定 AnimatedIcon.Source 屬性，以指定圖示的動畫視覺效果。 WinUI 為 Microsoft.UI.Xaml.Controls.AnimatedVisuals 命名空間中的一些常見圖示提供動畫視覺效果。

在某些情況下，系統設定或限制可能會防止圖示產生動畫效果。

• 如果使用者在其系統設定中關閉動畫， AnimatedIcon 則顯示控制項所在的狀態轉換最終畫面格。
• 指定不支援動畫時要使用的 FallbackIconSource ，例如不支援 Lottie 動畫的舊版 Windows 上。

自訂動畫

您可以建立自訂動畫，以作為應用程式中的動畫圖標。 您可以使用 Adobe AfterEffects建立動畫，然後使用該輸出搭配 Lottie-Windows 程式庫來產生實作 IAnimatedVisualSource2 的自訂類別。 您可以使用這個類別作為動畫圖標 的來源 。 如需詳細資訊，請參閱 使用 Lottie 建立 AnimatedIcon 的動畫內容。

控制動畫圖標狀態

您可以藉由設定 AnimatedIcon.State 附加屬性來變更動畫的播放位置和狀態。 state 屬性會採用字串值來描述視覺狀態，例如 「 Normal 」、「 PointerOver 」 或 「 Pressed 」。 您也可以指定特定狀態轉換，例如 「 PressedToNormal 」。

動畫圖標 來源 包含 標記 ，會將動畫時間軸中的位置對應至視覺狀態。 支援設定附加屬性的 State 字串值 Source 會在集合中 Markers 定義。 如需詳細資訊，請參閱 定義 AnimatedIcon 標記。

控制項範本中使用的動畫視覺效果來源通常會有一組 Markers 更複雜的對應至控制項狀態，而動畫視覺效果以供更一般使用，通常會有一組 Markers 較簡單的對應至指標事件。

設定狀態的位置

您可以在 XAML 樹狀結構中或上階上 AnimatedIcon 設定 屬性。 不論是哪一種情況，您都需要使用附加屬性語法，如下所示：

<muxc:AnimatedIcon muxc:AnimatedIcon.State="Normal">...</muxc:AnimatedIcon>

重要

如果您將 新增 AnimatedIcon 至 XAML 樹狀結構，並在上階元素上設定 State 屬性， State 則必須在動畫圖標第一次載入動畫之前將 屬性設定為初始值，才能讓圖示產生動畫效果。 您通常會在 XAML 中設定初始狀態，如下所示。

<StackPanel muxc:AnimatedIcon.State="Normal" ...>
   <muxc:AnimatedIcon>
       <animatedvisuals:AnimatedBackVisualSource/>
   </muxc:AnimatedIcon>
</StackPanel>

使用視覺狀態

您可以將 新增 AnimatedIcon 至 XAML 控制項的 ， ControlTemplate 並使用 VisualStateManager 來設定其狀態。 某些控制項，例如NavigationViewItem，會自動設定設定為圖示的 狀態 AnimatedIcon 。

若要查看在控制項範本視覺狀態中設定 AnimatedIcon.State 的範例，請參閱 WinUI GitHub 存放庫中 的 CheckBox_themeresources.xaml 。 控制項 CheckBox 會針對其核取記號使用 AnimatedAcceptVisualSource 。 視覺狀態 setter 看起來像這樣：

<VisualState x:Name="CheckedPointerOver">
    ...
    <VisualState.Setters>
        <Setter Target="CheckGlyph.(AnimatedIcon.State)" Value="PointerOverOn"/>
    </VisualState.Setters>
</VisualState>

處理指標事件

若要讓 AnimatedIcon 回應使用者互動，您必須設定 AnimatedIcon.State 附加屬性，以回應某些指標事件。 下表顯示您通常會處理的指標事件，以及對應至這些事件的常見狀態。 不過， (，並非所有動畫圖標來源都會完全對應到這些狀態。)

事件	狀態
PointerEntered	"PointerOver"
PointerPressed	"Pressed"
PointerReleased	"Normal"
PointerExited	"Normal"

提示

如果您將 放在 AnimatedIconButton 或其他具有 Click 事件的控制項內， PointerPressed 則 和 PointerReleased 事件會標示為 [已處理]。 若要在按鈕上處理這些事件，請使用 AddHandler 方法來連接事件處理常式，並將 指定 handledEventsToo 為 true 。 使用 RemoveHandler 中斷事件處理常式的連線。

如需示範這些事件處理常式的範例程式碼，請參閱範例一節。

XAML 附加屬性

AnimatedIcon 是 XAML 附加屬性的主機服務類別。

為了支援 XAML 處理器存取附加屬性，以及公開對等 的 get 和 set 作業給程式碼，每個 XAML 附加屬性都有一對 Get 和 Set 存取子方法。 在程式碼中取得或設定值的另一種方式是使用相依性屬性系統，呼叫 GetValue 或 SetValue ，並將識別碼欄位傳遞為相依性屬性識別碼。

建構函式

AnimatedIcon()

初始化 AnimatedIcon 類別的新實例。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。

屬性

FallbackIconSource	取得或設定當動畫圖標無法執行時要使用的靜態圖示。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
FallbackIconSourceProperty	識別 FallbackIconSource 相依性屬性。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
MirroredWhenRightToLeft	取得或設定值，這個值表示 當 FlowDirection 為 RightToLeft時，圖示是否會鏡像。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
MirroredWhenRightToLeftProperty	識別 MirroredWhenRightToLeft 相依性屬性。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
Source	取得或設定 物件所 AnimatedIcon 顯示的動畫視覺效果。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
SourceProperty	識別 來源 相依性屬性。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
StateProperty	識別 AnimatedIcon.State XAML 附加屬性。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。

附加屬性

State

開發人員在 AnimatedIcon 上設定的屬性。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。

方法

GetState(DependencyObject)	擷取指定DependencyObject之AnimatedIcon.State附加屬性的值。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。
SetState(DependencyObject, String)	指定指定DependencyObject之AnimatedIcon.State附加屬性的值。 本檔適用于 Windows 應用程式 SDK 中適用于 WinUI 的 WinUI 2 for UWP (，請參閱Windows 應用程式 SDK命名空間) 。

另請參閱

• AnimatedVisualPlayer
• 動畫圖標概觀
• VisualStateManager
• Lottie-Windows