概觀與版本資訊：WinUI 3 - Project Reunion 0.8 預覽版 (2021 年 5 月)

發行項
10/05/2023

WinUI 3 是用於建置現代 Windows 應用程式的原生使用者體驗 (UX) 架構。與 Windows 作業系統各自分開提供，為 Project Reunion (機器翻譯) (現稱為 Windows 應用程式 SDK (機器翻譯)) 的一部分。 0.8 預覽版提供 Visual Studio 中的 WinUI 3 範本 (機器翻譯)，協助您開始透過以 WinUI 3 為基礎的使用者介面建置應用程式。

WinUI 3 - Project Reunion 0.8 預覽版是 WinUI 3 的發行前版本，其中包含 Bug 修正、一般改善項目和實驗性功能，部分功能於 2021 年 6 月已針對 Windows 應用程式 SDK 0.8 穩定版本加強穩定性。

重要

發佈預覽版的目的是進行早期評估，並從開發人員社群收集意見反應。不會用於生產應用程式。

如果您想要使用 Project Reunion 與 WinUI 3 提供生產應用程式，請參閱概觀和版本資訊：WinUI 3 - Project Reunion 0.5 (機器翻譯)。

請使用 WinUI GitHub 存放庫以提供意見反應及記錄建議和問題。

注意

Project Reunion 是 Windows 應用程式 SDK (機器翻譯) 先前的程式碼名稱。本文件提及使用此程式碼名稱的舊版本時，仍會使用 Project Reunion。

安裝 WinUI 3 - Project Reunion 0.8 Preview

此版本的 WinUI 3 是 Project Reunion 0.8 預覽版的一部分。若要安裝，請參閱：

為 Windows 應用程式 SDK 的預覽和實驗通道安裝工具 (機器翻譯)

由於 WinUI 是隨附於 Project Reunion 的一部分，您必須下載 Project Reunion Visual Studio 延伸模組 (VSIX) 才能開始使用，其中包含一組開發人員工具和元件。如需 Project Reunion 套件的詳細資訊，請參閱部署使用 Windows 應用程式 SDK 的應用程式 (機器翻譯)。 Windows 應用程式 SDK VSIX 包含您要用於建置 WinUI 3 應用程式的 Visual Studio 中的 WinUI 3 範本 (機器翻譯)。

注意

若要查看作用中的 WinUI 3 控制項和功能，您可以從 GitHub 複製及建立 WinUI 3 控制項庫 (機器翻譯)，或是從 Microsoft Store 下載。

完成開發環境的設定後，請參閱 Visual Studio 中的 WinUI 3 範本 (機器翻譯)，熟悉可用的 Visual Studio 專案和項目範本。

若想深入瞭解如何開始建置 WinUI 3 應用程式，請參閱下列文章：

建立您的第一個 WinUI 3 專案
使用 WinUI 3 與 Win32 Interop 建置 C# .NET 應用程式 (機器翻譯)

除了限制和已知問題 (機器翻譯) 外，使用 WinUI 專案建置應用程式類似於使用 XAML 與 WinUI 2 建置 UWP 應用程式。因此，大部分適用於 UWP 應用程式的指引文件，以及 Windows SDK 中的 Windows.UI WinRT 命名空間都適用。

如需 WinUI 3 API 參照文件，請參閱：WinUI 3 API 參照 (機器翻譯)

WebView2

若要將此 WinUI 3 版本與 WebView2 搭配使用，但尚未安裝 WebView2 執行階段，請在這個頁面下載永久啟動程式載入程序或永久獨立安裝程式。

Windows 社群工具組

如果您使用的是 Windows 社群工具組，請下載最新版本。

Visual Studio 支援

若要使用新增至 WinUI 3 的最新工具功能 (如熱重新載入、即時視覺化樹狀結構和即時屬性總管)，您必須採用 Visual Studio 2019 16.10 預覽版。請注意，Visual Studio 預覽版是發行前版本產品，因此當您使用 Visual Studio 預覽版建置 WinUI 3 應用程式時，可能會遇到 Bug 和限制。

下表顯示 Visual Studio 2019 版本與 WinUI 3 - Project Reunion 0.5 的相容性。

VS 版本	WinUI 3 - Project Reunion 0.5
16.8	No
16.9	相容，但沒有熱重新載入、即時視覺化樹狀結構或即時屬性總管等功能
16.10 預覽版	相容，具備所有 WinUI 3 工具 (預覽版)

更新現有的 WinUI 3 應用程式

如果您先前是使用 WinUI 3 的舊預覽版或穩定版本建置應用程式，可以透過更新專案採用 WinUI 3 - Project Reunion 0.8 預覽版。如需相關指示，請參閱將現有專案更新為最新版的 Project Reunion (機器翻譯)。

此版本的重大變更

此版本現在可以使用樞紐分析控制項。
此版本也包含 Project Reunion v0.5.5、v0.5.6 與 v0.5.7 服務版本的大部分重大 bug 修正。如需瞭解此預覽版未納入的服務修正，請參閱已知問題 (機器翻譯)。

WinUI 3 - Project Reunion 0.8 預覽版中已修正的 Bug 清單

x:Bind 無法在自訂 MenuFlyoutItem 中運作 (一般而言，假如父系名稱範圍也使用 x:Bind，ControlTemplate 中的 x:Bind 便會無法運作)
- 感謝 @lhak 在 GitHub 上提出這個問題 (英文)！
一旦最上層視窗 (或 island) 移動，視窗型快顯就會隱藏
WinUI 3 控制項庫中的 StandardUICommand 頁面未顯示所有項目
在文字方塊中按滑鼠右鍵，會導致應用程式損毀
- 感謝 @Herdubreid 在 GitHub 上提出這個問題 (英文)！
EditableComboBox 的操作功能表顯示在錯誤的位置
透過觸控變更 RichTextBlock 選取範圍會導致選取指標消失
Microsoft C++ 例外狀況：使用 NavigationView 時，記憶體位置 0x... 會出現winrt::hresult_error
- 感謝 @LeftTwixWand 在 GitHub 上提出這個問題 (英文)！
WinUI 3 錯誤訊息需要改寫：「無法解析 'Windows.metadata'。請安裝 Windows 軟體開發套件。 Windows SDK 已與 Visual Studio 一併安裝。」
VSM Setter 提出例外狀況的奇怪行為具有回溯邏輯
- 感謝您@HppZ在 GitHub 上填寫此問題！
當瀏覽器程序當機時，將焦點移出 WebView2 (如有必要)
ProgressBar 不會顯示 Paused 與 Error 選項之間的差異
- 感謝 @j0shuams 在 GitHub 上提出這個問題 (英文)！
PointerReplay 會不斷執行
NavigationView 會導致 UWP、Reunion 0.5 預覽版當機
- 感謝 @kalin-todorov 在 GitHub 上提出這個問題 (英文)！
AutoSuggestBox、ComboBox 與 CommandBarFlyout 不會在其快顯上設定 ShouldConstrainToRootBounds="false"
WinUI 3 - Project Reunion 0.5 會針對 C# 受控應用程式產生 C++ 例外狀況
- 感謝 @Noemata 在 GitHub 上提出這個問題 (英文)！
WebView2 的初始 Tab 焦點失焦
若 Close() 之後出現 DPI 變更，WebView2 會當機
在 WinUI3 的 CommandBar 上含有飛出視窗的 AppBarButton 外觀出現變化
- 感謝 @eleanorleffler 在 GitHub 上提出這個問題 (英文)！

過去的 WinUI 3 預覽版所導入的特色與功能

下列特色與功能於過去的 WinUI 3 預覽版本中導入，如今 WinUI 3 - Project Reunion 0.8 預覽版仍繼續支援。

注意

WinUI 3 預覽版依然提供下列部分功能，但下一個支援版本可能不再提供。這些功能均標示為實驗性，若在應用程式中使用，系統會擲回警告。 WinUI 2.6 發行前版本包含的 API，在此版本中亦標示為實驗性。

使用 WinUI (包括適用於 Win32 應用程式的 .NET (英文)) 建立傳統型應用程式的功能
為建置 UWP 應用程式提供的預覽層級支援
RadialGradientBrush
TabView 更新
深色主題更新
WebView2 的改良和更新
- 高 DPI 的支援
- 支援視窗的大小調整和移動
- 已更新為以較新版本的 Edge 為目標
- 不再需要參考 WebView2 專屬的 Nuget 套件
SwapChainPanel
MRT Core 支援
- 這可讓應用程式在啟動時更快速且負擔更輕，並提供更快的資源查閱。
Arm64 支援
在應用程式內部和外部拖放
RenderTargetBitmap (目前僅限 XAML 內容 - 無 SwapChainPanel 內容)
自訂游標支援
無執行緒輸入
工具/開發人員體驗的改良：
- 即時視覺化樹狀結構、熱重新載入、即時屬性總管和類似工具
- 適用於 WinUI 3 的 IntelliSense
遷移開放原始碼所需的改良功能
自訂標題列功能：新的 Window.ExtendsContentIntoTitleBar (機器翻譯) 與 Window.SetTitleBar (機器翻譯) API，可讓開發人員在傳統型應用程式中建立自訂標題列。
VirtualSurfaceImageSource 支援
應用程式內壓克力
傳統型應用程式中的多視窗支援
輸入驗證

提供意見反應和建議

我們歡迎您在 WinUI GitHub 存放庫中提供意見反應。

限制和已知問題

WinUI 3 - Project Reunion 0.8 預覽版只提供預覽。請預期會有錯誤、限制和其他問題。

下列項目是 WinUI 3 - Project Reunion 0.8 的部分已知問題。如果您發現下面未列出的問題，請透過 WinUI GitHub 存放庫參與現有問題或提出新問題，來讓我們知道。

平台和 OS 支援

WinUI 3 - Project Reunion 0.8 預覽版與執行 Windows 10 2018 年 10 月更新 (版本 1809 - 組建 17763) 和更新版本的電腦相容。

開發人員工具

僅支援 C# 與 C++/WinRT 應用程式。
傳統型應用程式支援 .NET 6 (及更新版本) 和 C# 9，而且必須封裝在 MSIX 應用程式中。
不支援 XAML 設計工具。
不支援新的 C++/CX 應用程式，不過，您現有的應用程式仍可繼續運作 (請儘速移至 C++/WinRT)。
不支援未封裝的傳統型應用程式部署。
使用 F5 執行傳統型應用程式時，請確認您執行的是封裝專案。在應用程式專案上按 F5，將會執行未封裝的應用程式，而 WinUI 3 尚不支援此動作。

缺少的平台功能

Xbox 支援
HoloLens 支援
視窗型快顯
- 更明確地說，ShouldConstrainToRootBounds 屬性的行為一律會如同設定為 true 時的行為 (不論屬性值為何)。
筆跡支援，包含：
- InkCanvas
- HandwritingView (機器翻譯)
- InkPresenter (機器翻譯)
背景壓克力
MediaElement 和 MediaPlayerElement
MapControl
SwapChainPanel 不支援透明度
使用 CompositionBackdropBrush 的 AcrylicBrush 和其他效果無法從 SwapChainPanel 或 WebView2 取樣。
全域顯示 (Global Reveal) 會使用回溯行為 (實心筆刷)
此版本不支援 XAML Islands
直接在現有的非 WinUI 傳統型應用程式中使用 WinUI 3 會有下列限制：目前移轉現有應用程式的可用路徑是將新的 WinUI 3 專案新增至您的解決方案，並視需要進行調整或重構邏輯。
傳統型應用程式中不會呼叫 Application.Suspending。如需詳細資訊，請參閱 Application.Suspending 事件 (機器翻譯) 的 API 參照文件。
傳統型應用程式中不再支援 UISettings.ColorValuesChanged 事件 (機器翻譯) 與 AccessibilitySettings.HighContrastChanged 事件 (機器翻譯)，若將其用於偵測 Windows 主題中的變更，可能會出現問題。
過去若要取得 CompositionCapabilities 執行個體，須呼叫 CompositionCapabilites.GetForCurrentView() (機器翻譯)，但從這個呼叫傳回的功能「不會」相依於檢視。為了解決並反映這個問題，我們已在此版本中刪除 GetForCurrentView() 靜態，因此您現在可以直接建立 CompositionCapabilties (機器翻譯) 物件。
傳統型應用程式不支援 CoreWindow、ApplicationView、CoreApplicationView、CoreDispatcher 及其相依性 (請見下方)

傳統型應用程式中的 CoreWindow、ApplicationView、CoreApplicationView 與 CoreDispatcher

WinUI 3 Preview 4 和標準的新功能，CoreWindow、ApplicationView、CoreApplicationView CoreDispatcher 及其相依性無法在傳統型應用程式中使用。舉例來說，Window.Dispatcher (機器翻譯) 屬性一律為 null，但 Window.DispatcherQueue 屬性可用作替代項目。

這些 API 只能在 UWP 應用程式中執行。在過去的預覽版中，這些 API 也會在傳統型應用程式中部分運作，但在預覽版 4 之後已完全停用。這些 API 是針對每個執行緒只有一個視窗的 UWP 案例所設計，但 WinUI 3 日後推出的其中一項功能是啟用多個視窗。

有一些 API 內部相依於這些 API 的存在，因此在傳統型應用程式中不受支援。這些 API 通常有靜態 GetForCurrentView 方法，例如 UIViewSettings.GetForCurrentView (機器翻譯)。

若想深入瞭解受影響的 API、因應措施和這類 API 的更換作業，請參閱傳統型應用程式中不支援的 Windows 執行階段 API (機器翻譯)。

已知問題

您可能會因為 .NET SDK 與 winrt.runtime.dll 版本不相符而收到組建錯誤。您可以嘗試下列各項來做為因應措施：

將您的 .NET SDK 明確設定為正確的版本。若要判斷應用程式的正確版本，請在專案檔中找出 <TargetFramework> 標籤。使用您的應用程式在 <TargetFramework> 標籤中設為目標的 Windows SDK 組建編號 (例如 18362 或 19041)，將下列項目新增至您的專案檔，然後儲存專案：
```
<ItemGroup>            
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.{Target Windows SDK Build Number}.16" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.{Target Windows SDK Build Number}.16" />
</ItemGroup>
```
請注意，.NET SDK 5.0.203 和更早版本需採用此因應措施，但 .NET SDK 5.0.204 或 5.0.300 不需要。
使用 Visual Studio 2019 16.10 預覽版 2 時，即時視覺化樹狀結構可能會導致當機。若要避免這種情況，請更新為最新的 Visual Studio 2019 16.10 預覽版。
未設定 SetTitleBar 或將其設為 Null 時，視窗標題按鈕可能會錯置

WinUI 3 控制項庫

請查看 WinUI 3 控制項庫 (先前稱為「XAML 控制項庫 - WinUI 3 版」) 以取得範例應用程式，其中包含 WinUI 3 - Project Reunion 0.8 的所有控制項和功能。

WinUI 3 控制項程式庫應用程式
WinUI 3 控制項庫應用程式的範例

WinUI 3 控制項庫應用程式可透過 Microsoft Store (英文) 取得。

您也可以複製 GitHub 存放庫以下載範例。若要這樣做，請使用下列命令複製 winui3 分支：

注意

此 GitHub 存放庫中還有一個 winui3preview 分支也提供使用 WinUI 3 - Project Reunion 0.8 預覽版的 WinUI 3 控制項庫版本。

git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git

複製之後，請確定您已切換至本機 Git 環境中的 winui3 分支：

git checkout winui3

共用方式為