使用視覺層增強 UI (Windows 應用程式 SDK/WinUI 3)

Windows 應用程式 SDK/WinUI 3 中的視覺層為圖形、效果、動畫和輸入提供高效能、保留模式 API。 這是跨所有 Windows 裝置的 UI 基礎。

Microsoft.UI.Composition 中的類型會形成視覺層 Windows 應用程式 SDK/WinUI 3 實作。 非常類似 Windows.UI.Composition 命名空間中實作的 UWP 視覺效果層。 以下詳細介紹了兩者之間的差異以及 Windows 應用程式 SDK/WinUI 3 視覺層缺少的功能。

UWP 的差異

Microsoft.UI.Composition 與 UWP 視覺層之間最明顯的差異是命名空間。 在最常使用的案例中，Microsoft.UI.Composition 提供幾乎與 UWP 視覺層相同之功能的存取權。 但有例外狀況和差異。

Windows 應用程式 SDK/WinUI 3 會使用 Microsoft.UI.Composition 來描述個別視覺效果的樹狀結構。 然後，這些視覺效果會進行複合，以建立視窗的完整轉譯。 這與 Windows.UI.Composition 的運作方式非常類似 (適用於 UWP app)。 但有一個很大的差異是，Microsoft.UI.Composition 撰寫器會在 Windows 應用程式 SDK 應用程式中完全執行，而且只能存取所繪製的圖元。 這意味著任何外部內容 (不是由合成器繪製的內容) 對於合成器來說都是未知的。 這會建立某些限制。

外部內容的範例是 (Microsoft.UI.Xaml.Controls) MediaPlayerElement。 Windows 媒體堆疊為 XAML 提供不透明媒體交換鏈句柄。 XAML 將該句柄提供給合成器，合成器將其交給 Windows (透過 Windows.UI.Composition) 進行顯示。 更具體地說，由於合成器看不到媒體交換鏈中的任何像素，因此它無法將其合成為視窗整體渲染的一部分。 相反，它將媒體交換鏈提供給 Windows，以將其呈現在合成器的渲染下方，並在合成器的渲染中切出一個洞，以便允許其下方的媒體交換鏈可見。 這是此設定的可視化。

一般來說，該方法允許外部內容 (例如交換鏈) 成為視窗整體渲染的一部分；它仍然允許合成器繪製的其他內容重疊在外部內容之上，例如，XAML 的 MediaTransportControls 在媒體之上呈現。 但它不允許與此外部內容進行更高級的效果互動。 這適用於可用於將交換鏈插入視圖的所有方法：透過 XAML (例如，透過 SwapChainPanel) 或透過 Composition (例如，使用 ICompositorInterop::CreateCompositionSurfaceForSwapChain)。

在 Windows 應用程式 SDK/WinUI 3 中，下列 API 全都會建立外部內容。

• MediaPlayerElement
• SwapChainPanel
• WebView2
• MicaBackdrop 和 DesktopAcrylicBackdrop，以及它們使用的底層 MicaController 和 DesktopAcrylicController。

上述處理外部內容的模型會建立下列限制：

• 無法將合成器內容放在外部內容後面 (即上圖外部層的後面/下方)。 例如，不可能為 WebView2 提供透明背景以便能夠看到其後面的 XAML 按鈕或映像。 唯一可以位於外部內容後面的是其他外部內容和視窗背景。 因此，我們不建議/停用外部內容的透明度。
• 您無法從外部內容取得撰寫器內容範例。 例如，AcrylicBrush 無法從 MediaPlayerElement 取樣及模糊任何圖元。 AcrylicBrush 會從組合器影像中取樣，這是外部內容區域的透明黑色。 因此，透明黑色將是 AcrylicBrush 模糊。 同樣，MicaBackdrop 或 DesktopAcrylicBackdrop 前面的 AcrylicBrush 無法看到這些背景將繪製的任何顏色；相反，畫筆會模糊透明的黑色。
• 另一個案例稱為 目的地反轉，用於文本框控制項的插入號，以反轉文字插入插入插入號前面的圖元。 這會類似地從合成器表面反轉樣本，如果文字方塊沒有合成器繪製的不透明背景，則會受到影響。
• 因為 WinUI 3 SwapChainPanel 會建立外部內容，所以不支持透明度。 它也不支援套用 AcrylicBrush 和其他在它前面使用 CompositionBackdropBrush 的效果。 AcrylicBrush 和其他 CompositionBackdropBrush 效果無法從 SwapChainPanel 取樣。
• 在傳統型應用程式中 (WinUI 3 應用程式是傳統型應用程式)，Window.Current 為 null。 因此，您無法從 Window.Current.Compositor 擷取 Compositor 的執行個體。 呼叫 ElementCompositionPreview.GetElementVisual(UIElement) 取得合成視覺對象，並從視覺Compositor對象的 Compositor 屬性中檢索該視覺對象。 如果您無法存取 UIElement (例如，如果您在類別庫中建立 CompositionBrush)，您可以呼叫 CompositionTarget.GetCompositorForCurrentThread。

如需有關視覺層的詳細資訊，請參閱 UWP 檔中的視覺層概觀。 在大部分情況下，文件和範例也適用於 Microsoft.UI.Composition。

使用 Microsoft.UI.Composition 的必要條件

若要在 Windows 應用程式 SDK/WinUI 3 中使用 Microsoft.UI.Composition API：

1. 下載並安裝最新版的 Windows 應用程式 SDK。 如需詳細資訊，請參閱安裝 Windows 應用程式 SDK 工具。
2. 請遵循指示來建立您的第一個 WinUI 3 專案，或使用現有專案中的 Windows 應用程式 SDK。

若要深入瞭解 Windows 應用程式 SDK/WinUI 3 中 Microsoft.UI.Composition 的可用性，請參閱發行通道。

Windows 組合範例庫

Windows 組合範例 我們已更新 Windows 組合範例庫，現在依賴 Windows 應用程式 SDK 組合 API.Gallery 請瀏覽 WindowsCompositionSamples 以查看 Microsoft.UI.Composition API 運作情形。

相關主題

• UWP 視覺層概觀
• 在傳統型應用程式中使用視覺層