Windows UI 程式庫 3 預覽版 3 (2020 年 11 月)Windows UI Library 3 Preview 3 (November 2020)

Windows UI 程式庫 (WinUI) 3 是同時適用於 Windows 桌面和 UWP 應用程式的原生使用者體驗 (UX)。Windows UI Library (WinUI) 3 is a native user experience (UX) framework for both Windows Desktop and UWP apps.

WinUI 3 預覽版 3 包含全新和改良的功能,以及重大的錯誤修正。WinUI 3 Preview 3 brings both new and improved functionality, along with significant bug fixes.

請參閱 預覽版 3 的限制和已知問題See Preview 3 limitations and known issues.

重要

WinUI 3 預覽版的目的是進行早期評估,並從開發人員社群收集意見反應。This WinUI 3 preview release is intended for early evaluation and to gather feedback from the developer community. 不會 用於生產應用程式。It should NOT be used for production apps.

我們會繼續將 WinUI 3 的預覽版本延續到 2021,然後推出第一個正式版本。We will continue shipping preview releases of WinUI 3 into 2021, followed by the first official release.

請使用 WinUI GitHub 存放庫以提供意見反應及記錄建議和問題。Please use the WinUI GitHub repo to provide feedback and log suggestions and issues.

安裝 WinUI 3 預覽版 3Install WinUI 3 Preview 3

WinUI 3 預覽版 3 包含 Visual Studio 專案範本,可協助您開始使用以 WinUI 為基礎的使用者介面以及包含 WinUI 程式庫的 NuGet 套件,來建置應用程式。WinUI 3 Preview 3 includes Visual Studio project templates to help get started building apps with a WinUI-based user interface, and a NuGet package that contains the WinUI libraries. 若要安裝 WinUI 3 預覽版 3,請遵循下列步驟。To install WinUI 3 Preview 3, follow these steps.

注意

您也可以複製 WinUI 3 預覽版 3 版本的 XAML 控制項資源庫,並加以建置。You can also clone and build the WinUI 3 Preview 3 version of the XAML Controls Gallery.

  1. 確定您的開發電腦已安裝 Windows 10 1803 (組建 17134) 或較新版本。Ensure that your development computer has Windows 10, version 1803 (build 17134), or newer installed.

  2. 安裝 Visual Studio 2019 (16.9 預覽版)Install Visual Studio 2019, version 16.9 Preview

    安裝 Visual Studio 時,您必須包含下列工作負載:You must include the following workload when installing Visual Studio:

    • 通用 Windows 平台開發Universal Windows Platform development

    若要建立 .NET 應用程式,您也必須包含下列工作負載:To build .NET apps, you must also include the following workloads:

    • .NET 桌面開發 (這也會安裝 .NET 5).NET Desktop Development (this also installs .NET 5)

    若要建立 C++ 應用程式,您也必須包含下列工作負載:To build C++ apps, you must also include the following workloads:

    • 使用 C++ 的傳統型開發Desktop development with C++
    • C++ (v142) 通用 Windows 平台工具,通用 Windows 平台工作負載的選用元件 (請參閱右側窗格中 [通用 Windows 平台開發] 區段底下的 [安裝詳細資料])The C++ (v142) Universal Windows Platform tools optional component for the Universal Windows Platform workload (see "Installation Details" under the "Universal Windows Platform development" section, on the right pane)
  3. 請確定您的系統已針對 nuget.org 啟用 NuGet 套件來源。如需詳細資訊,請參閱 常見的 NuGet 設定Make sure your system has a NuGet package source enabled for nuget.org. For more information, see Common NuGet configurations.

  4. 下載及安裝 WinUI 3 預覽版 3 VSIX 套件Download and install the WinUI 3 Preview 3 VSIX package. 這會將 WinUI 3 專案範本和 NuGet 套件 (包含 WinUI 3 程式庫) 新增至 Visual Studio 2019。This adds both the WinUI 3 project templates and the NuGet package containing the WinUI 3 libraries to Visual Studio 2019.

    如需如何將 VSIX 套件新增至 Visual Studio 的指示,請參閱尋找和使用 Visual Studio 擴充功能For instructions on how to add the VSIX package to Visual Studio, see Finding and Using Visual Studio Extensions.

WebView2WebView2

如果您在應用程式中使用 WebView2 控制項,請從 Microsoft Edge Insider Channels安裝 Microsoft Edge 瀏覽器的 Dev 通道版本If you're using the WebView2 control in your app, please install the Dev Channel version of the Microsoft Edge Browser from Microsoft Edge Insider Channels. 請務必將 Microsoft Edge Beta、Microsoft Edge Dev 和 Microsoft Edge WebView2 執行階段的任何現有執行個體解除安裝。Make sure to uninstall any existing instances of Microsoft Edge Beta, Microsoft Edge Dev, and Microsoft Edge WebView2 Runtime.

Windows 社群工具組Windows Community Toolkit

如果您使用的是 Windows 社群工具組,請下載最新版本If you're using the Windows Community Toolkit, download the latest version.

建立 WinUI 專案Create WinUI projects

安裝 WinUI 3 預覽版 3 VSIX 套件之後,您就可以在 Visual Studio 中使用其中一個 WinUI 專案範本來建立新的專案。After installing the WinUI 3 Preview 3 VSIX package, you're ready to create a new project using one of the WinUI project templates in Visual Studio. 若要在 [建立新專案] 對話方塊中存取 WinUI 專案範本,請將語言篩選為 C++C# ,將平台篩選為 Windows,以及將專案類型篩選為 WinUITo access the WinUI project templates in the Create a new project dialog, filter the language to C++ or C#, the platform to Windows, and the project type to WinUI. 或者,您可以搜尋「WinUI」並選取其中一個可用的 C# 或 C++ 範本。Alternatively, you can search for WinUI and select one of the available C# or C++ templates.

WinUI 專案範本

如需開始使用 WinUI 專案範本的詳細資訊,請參閱下列文章:For more information about getting started with the WinUI project templates, see the following articles:

除了限制和已知問題之外,使用 WinUI 專案建置應用程式類似於使用 XAML 和 WinUI 2.x 建置 UWP 應用程式。Aside from the limitations and known issues, building an app using the WinUI projects is similar to building a UWP app with XAML and WinUI 2.x. 因此,大部分適用於 UWP 應用程式的 指引文件,以及 Windows SDK 中的 Windows.UI WinRT 命名空間都適用。Therefore, most of the guidance documentation for UWP apps and the Windows.UI WinRT namespaces in the Windows SDK is applicable.

在此版本中,我們也新增了 WinUI 3 API 參考文件,適用於所有已移植到 WinUI 3 的 WinRT API。With this release, we've also added WinUI 3 API reference documentation for all WinRT APIs ported to WinUI 3.

如果您使用 WinUI 3 預覽版 2 建立專案,您可以將專案升級為使用預覽版 3。If you created a project using WinUI 3 Preview 2, you can upgrade your project to use Preview 3. 如需詳細指示,請參閱 WinUI GitHub 存放庫See the WinUI GitHub repository for detailed instructions.

WinUI 3 的專案範本Project templates for WinUI 3

您可以使用這些 WinUI 專案範本來建立應用程式。You can use these WinUI project templates to create apps.

範本Template LanguageLanguage 描述Description
已封裝的空白應用程式 (WinUI in Desktop)Blank App, Packaged (WinUI in Desktop) C# 和 C++C# and C++ 使用以 WinUI 為基礎的使用者介面,建立桌面 .NET 5 (C#) 或原生 Win32 (C++) 應用程式。Creates a desktop .NET 5 (C#) or native Win32 (C++) app with a WinUI-based user interface. 產生的專案包含一個基本視窗,該視窗是從 WinUI 程式庫中的 Microsoft.UI.Xaml.Window 類別衍生,您可以用來開始建置您的 UI。The generated project includes a basic window that derives from the Microsoft.UI.Xaml.Window class in the WinUI library that you can use to start building your UI. 如需此專案類型的詳細資訊,請參閱開始使用適用於桌面應用程式的 WinUI 3For more information about this project type, see Get started with WinUI 3 for desktop apps.

解決方案也包含 Windows 應用程式封裝專案,其已設定為將應用程式建置到 MSIX 套件The solution also includes a Windows Application Packaging Project that is configured to build the app into an MSIX package. 這可提供新式部署體驗,透過套件擴充功能與 Windows 10 功能整合的能力,還有更多功能。This provides a modern deployment experience, the ability to integrate with Windows 10 features via package extensions, and much more.
空白應用程式 (WinUI in UWP)Blank App (WinUI in UWP) C# 和 C++C# and C++ 建立具有以 WinUI 為基礎的使用者介面的 UWP 應用程式。Creates a UWP app that with a WinUI-based user interface. 產生的專案包含一個基本頁面,該頁面是從 WinUI 程式庫中的 Microsoft.UI.Xaml.Controls.Page 類別衍生,您可以用來開始建置您的 UI。The generated project includes a basic page that derives from the Microsoft.UI.Xaml.Controls.Page class in the WinUI library that you can use to start building your UI. 如需此專案類型的詳細資訊,請參閱開始使用適用於 UWP 應用程式的 WinUI 3For more information about this project type, see Get started with WinUI 3 for UWP apps.

您可以使用這些 WinUI 專案範本來建置可供以 WinUI 為基礎的應用程式載入及使用的元件。You can use these WinUI project templates to build components that can be loaded and used by a WinUI-based app.

範本Template LanguageLanguage 描述Description
類別庫 (WinUI in Desktop)Class Library (WinUI in Desktop) 僅限 C#C# only 在 C# 中建立 .NET 5 受控類別庫 (DLL),可供具有以 WinUI 為基礎的使用者介面的其他 .NET 5 桌面應用程式使用。Creates a .NET 5 managed class library (DLL) in C# that can be used by other .NET 5 desktop apps with a WinUI-based user interface.
類別庫 (WinUI in UWP)Class Library (WinUI in UWP) 僅限 C#C# only 在 C# 中建立受控類別程式庫 (DLL),可供具有以 WinUI 為基礎的使用者介面的其他 UWP 應用程式使用。Creates a managed class library (DLL) in C# that can be used by other UWP apps with a WinUI-based user interface.
Windows 執行階段元件 (WinUI)Windows Runtime Component (WinUI) C++C++ 建立以 C++/WinRT 撰寫的 Windows 執行階段元件,可以由具有 WinUI 架構使者介面的任何 UWP 或桌面應用程式取用,不論該應用程式是以何種程式設計語言撰寫。Creates a Windows Runtime component written in C++/WinRT that can be consumed by any UWP or Desktop app with a WinUI-based user interface, regardless of the programming language in which the app is written.
Windows 執行階段元件 (UWP)Windows Runtime Component (UWP) C#C# 建立以 C# 撰寫的 Windows 執行階段元件,可以由具有 WinUI 架構使者介面的任何 UWP 應用程式取用,不論該應用程式是以何種程式設計語言撰寫。Creates a Windows Runtime component written in C# that can be consumed by any UWP app with a WinUI-based user interface, regardless of the programming language in which the app is written.

WinUI 3 的項目範本Item templates for WinUI 3

您可以在 WinUI 專案中使用下列項目範本。The following item templates are available for use in a WinUI project. 若要存取這些 WinUI 項目範本,請以滑鼠右鍵按一下 [方案總管] 中的專案節點,選取 [新增] -> [新項目],然後按一下 [新增新項目] 對話方塊中的 [WinUI]。To access these WinUI item templates, right-click the project node in Solution Explorer, select Add -> New item, and click WinUI in the Add New Item dialog.

WinUI 項目範本

範本Template LanguageLanguage 說明Description
空白頁面 (WinUI)Blank Page (WinUI) C# 和 C++C# and C++ 新增 XAML 檔案和程式碼檔案,該檔案會定義衍生自 WinUI 程式庫中 Microsoft.UI.Xaml.Controls.Page 類別的新頁面。Adds a XAML file and code file that defines a new page derived from the Microsoft.UI.Xaml.Controls.Page class in the WinUI library.
空白視窗 (WinUI in Desktop)Blank Window (WinUI in Desktop) C# 和 C++C# and C++ 新增 XAML 檔案和程式碼檔案,該檔案會定義衍生自 WinUI 程式庫中 Microsoft.UI.Xaml.Window 類別的新視窗。Adds a XAML file and code file that defines a new window derived from the Microsoft.UI.Xaml.Window class in the WinUI library.
自訂控制項 (WinUI)Custom Control (WinUI) C# 和 C++C# and C++ 新增程式碼檔案,以使用預設樣式建立樣板化控制項。Adds a code file for creating a templated control with a default style. 樣板化控制項衍生自 WinUI 程式庫中的 Microsoft.UI.Xaml.Controls.Control 類別。The templated control is derived from the Microsoft.UI.Xaml.Controls.Control class in the WinUI library.

如需示範如何使用此項目範本的逐步解說,請參閱 UWP 和 WinUI 3 應用程式的樣板化 XAML 控制項 (使用 C++/WinRT)UWP 和 WinUI 3 應用程式的樣板化 XAML 控制項 (使用 C#)For a walkthrough that demonstrates how to use this item template, see Templated XAML controls for UWP and WinUI 3 apps with C++/WinRT and Templated XAML controls for UWP and WinUI 3 apps with C#. 如需樣板化控制項的詳細資訊,請參閱自訂 XAML 控制項For more information about templated controls, see Custom XAML Controls.
資源字典 (WinUI)Resource Dictionary (WinUI) C# 和 C++C# and C++ 新增 XAML 資源的空白索引鍵集合。Adds an empty, keyed collection of XAML resources. 如需詳細資訊,請參閱 ResourceDictionary 與 XAML 資源參考For more information, see ResourceDictionary and XAML resource references.
資源檔 (WinUI)Resources File (WinUI) C# 和 C++C# and C++ 新增檔案,用於儲存應用程式的字串和條件式資源。Adds a file for storing string and conditional resources for your app. 您可以使用此項目來協助將您的應用程式當地語系化。You can use this item to help localize your app. 如需詳細資料,請參閱將您 UI 和應用程式套件資訊清單中的字串當地語系化For more info, see Localize strings in your UI and app package manifest.
使用者控制項 (WinUI)User Control (WinUI) C# 和 C++C# and C++ 新增 XAML 檔案和程式碼檔案,以建立衍生自 WinUI 程式庫中 Microsoft.UI.Xaml.Controls.UserControl 類別的使用者控制項。Adds a XAML file and code file for creating a user control that derives from the Microsoft.UI.Xaml.Controls.UserControl class in the WinUI library. 一般而言,使用者控制項會封裝相關的現有控制項,並提供自己的邏輯。Typically, a user control encapsulates related existing controls and provide its own logic.

如需使用者控制項的詳細資訊,請參閱自訂 XAML 控制項For more information about user controls, see Custom XAML Controls.

Visual Studio 支援Visual Studio Support

若要使用新增至 WinUI 3 預覽版 3 的最新工具功能 (如熱重新載入、即時視覺化樹狀結構和即時屬性總管),您必須使用最新的 Visual Studio 預覽版與最新的 WinUI 3 預覽版。In order to take advantage of the latest tooling features added into WinUI 3 Preview 3 like Hot Reload, Live Visual Tree, and Live Property Explorer, you must use the latest preview version of Visual Studio with the latest WinUI 3 preview. 下表顯示未來版本與 WinUI 3 預覽版 3 的相容性:The table below shows the compatibility of future versions with WinUI 3 Preview 3:

VS 版本VS Version WinUI 3 預覽版 3WinUI 3 Preview 3
16.8 RTM16.8 RTM No
16.9 預覽版16.9 Previews Yes
16.9 RTM16.9 RTM No
16.10 預覽版16.10 Previews Yes

預覽版 3 的新特性與功能New features and capabilities in Preview 3

  • ARM64 支援ARM64 Support
  • 在應用程式內部和外部拖放Drag and drop inside and outside of apps
  • RenderTargetBitmap (目前僅限 XAML 內容 - 無 SwapChainPanel 內容)RenderTargetBitmap (currently only XAML content - no SwapChainPanel content)
  • 工具/開發人員體驗的改良:Improvements to our tooling/developer experience:
    • 即時視覺化樹狀結構、熱重新載入、即時屬性總管和類似工具Live Visual Tree, Hot Reload, Live Property Explorer and similar tools
    • Intellisense 現在可用於 WinUI 3Intellisense now working for WinUI 3
  • MRT Core 支援MRT Core Support
    • 這可讓應用程式在啟動時更快速且負擔更輕,並提供更快的資源查閱。This makes apps faster and lighter on startup and provides quicker resource lookup.
  • 自訂游標支援Custom cursor support
  • 無執行緒輸入Off-thread input
  • 自預覽版 2 以來的效能改進Performance improvements since Preview 2
  • 桌面應用程式中的多重視窗 - 預覽版 2 之後的改良支援Multiple windows in Desktop apps - improved support since Preview 2

過去 WinUI 3 預覽版 3 中引進的新特性和功能New features and capabilities introduced in past WinUI 3 Previews

下列功能是在 WinUI 3 預覽版 1 與 2 中引進,並繼續在 WinUI 3 預覽版 3 中受支援。The following features and capabilities were introduced in WinUI 3 Preview 1 & 2 and continue to be supported in WinUI 3 Preview 3.

  • 能夠使用 WinUI 建立桌面應用程式,包括適用於 Win32 應用程式的 .NET 5Ability to create Desktop apps with WinUI, including .NET 5 for Win32 apps
  • RadialGradientBrushRadialGradientBrush
  • TabView 更新TabView updates
  • 深色主題更新Dark theme updates
  • WebView2 的改良和更新Improvements and updates to WebView2
    • 高 DPI 的支援Support for High DPI
    • 支援視窗的大小調整和移動Support for window resizing and moving
    • 已更新為以較新版本的 Edge 為目標Updated to target more recent version of Edge
    • 不再需要參考 WebView2 專屬的 Nuget 套件No longer necessary to reference a WebView2-specific Nuget package
  • SwapChainPanelSwapChainPanel
  • 遷移開放原始碼所需的改良功能Improvements required for open source migration

如需有關 WinUI 3 和 WinUI 藍圖優點的詳細資訊,請參閱 GitHub 上的 Windows UI 程式庫藍圖For more information on both the benefits of WinUI 3 and the WinUI roadmap, see the Windows UI Library Roadmap on GitHub.

提供意見反應和建議Provide feedback and suggestions

我們歡迎您在 WinUI GitHub 存放庫 中提供意見反應。We welcome your feedback in the WinUI GitHub repo.

未來將推出哪些新功能?What's coming next?

請查看我們的詳細功能藍圖,了解將特定功能引進 WinUI 3 的時間。Take a look at our detailed feature roadmap to see when specific features will be brought into WinUI 3.

預覽版 3 的限制和已知問題Preview 3 limitations and known issues

預覽版 3 版本僅供預覽。The Preview 3 release is just that, a preview. 特別是與桌面版應用程式相關的案例都是新項目。The scenarios around Desktop apps are especially new. 請預期會有錯誤、限制和其他問題。Please expect bugs, limitations, and other issues.

下列項目是 WinUI 3 預覽版 3 的一些已知問題。The following items are some of the known issues with WinUI 3 Preview 3. 如果您發現下面未列出的問題,請透過 WinUI GitHub 存放庫參與現有問題或提出新問題,來讓我們知道。If you find an issue that isn't listed below, please let us know by contributing to an existing issue or filing a new issue through the WinUI GitHub repo.

平台和 OS 支援Platform and OS support

WinUI 3 預覽版 3 可與執行 Windows 10 2018 年 4 月更新 (版本 1803 - 組建 17134) 和更新版本的電腦相容。WinUI 3 Preview 3 is compatible with PCs running the Windows 10 April 2018 Update (version 1803 - build 17134) and newer.

開發人員工具Developer tools

  • 僅支援 C# 和 C++/WinRT 應用程式Only C# and C++/WinRT apps are supported
  • 桌面應用程式支援 .NET 5 和 C# 9,而且必須在 MSIX 應用程式中加以封裝Desktop apps support .NET 5 and C# 9, and must be packaged in an MSIX app
  • UWP 應用程式支援 .NET Native 和 C# 7.3UWP apps support .NET Native and C# 7.3
  • 開發人員工具和 Intellisense 在 Visual Studio 16.8 版中可能無法正常運作。Developer tools and Intellisense may not work properly in Visual Studio version 16.8.
  • 沒有 XAML 設計工具支援No XAML Designer support
  • 不支援新的 C++/CX 應用程式,不過,您現有的應用程式仍可繼續運作 (請盡速移至 C++/WinRT)New C++/CX apps are not supported, however, your existing apps will continue to function (please move to C++/WinRT as soon as possible)
  • 桌面應用程式中的多重視窗支援仍在準備中,尚未完成也未穩定。Support for multiple windows in Desktop apps is in progress, but not yet complete and stable.
    • 如果您發現多重視窗行為上出現新問題或功能衰退,請在我們的存放庫中提出該問題。Please file a bug on our repo if you find new issues or regressions with multi-window behavior.
  • 不支援未封裝的桌面部署Unpackaged desktop deployment is not supported
  • 使用 F5 執行桌面應用程式時,請確定您執行的是封裝專案。When running a Desktop app using F5, make sure that you are running the packaging project. 在應用程式專案上按 F5,將會執行未封裝的應用程式,而 WinUI 3 尚不支援此動作。Hitting F5 on the app project will run an unpackaged app, which WinUI 3 does not yet support.

缺少平台功能Missing Platform Features

  • Xbox 支援Xbox support
  • HoloLens 支援HoloLens support
  • 視窗型快顯Windowed popups
    • 更明確地說,ShouldConstrainToRootBounds 屬性的行為一律會如同設定為 true 時的行為 (不論屬性值為何)。More specifically, the ShouldConstrainToRootBounds property always acts as if it's set to true, regardless of the property value.
  • 筆跡支援Inking support
  • 壓克力Acrylic
  • MediaElement 和 MediaPlayerElementMediaElement and MediaPlayerElement
  • MapControlMapControl
  • SwapChainPanel 和非 XAML 內容的 RenderTargetBitmapRenderTargetBitmap for SwapChainPanel and non-XAML content
  • SwapChainPanel 不支援透明度SwapChainPanel does not support transparency
  • 全域顯示 (Global Reveal) 會使用回溯行為 (實心筆刷)Global Reveal uses fallback behavior, a solid brush
  • 此版本不支援 XAML IslandsXAML Islands is not supported in this release
  • 第三方生態系統程式庫的功能不完整3rd party ecosystem libraries will not fully function
  • IME 無法運作IMEs do not work

已知問題Known issues

  • Alt + F4 不會關閉桌面應用程式視窗。Alt+F4 does not close Desktop app windows.

  • 如果您在應用程式中使用 WebView2,但其並未呈現或載入,則您可能執行了不相容的 Edge 瀏覽器版本。If you’re using a WebView2 in your app but it is not rendering or loading, you may be running an incompatible version of the Edge browser. 請下載 Microsoft Edge 的 Dev 通道版本,並且務必將 Microsoft Edge Beta、Microsoft Edge Dev 和 Microsoft Edge WebView2 執行階段的任何現有執行個體解除安裝。Download the Dev channel of Microsoft Edge and be sure to uninstall any existing instances of Microsoft Edge Beta, Microsoft Edge Dev, and Microsoft Edge WebView2 Runtime.

  • 您不應在 .NET 5 WinUI 應用程式中使用封送函式,因為這些函式無法與 C#/WinRT 正確地交互操作。Marshal functions should not be used in .NET 5 WinUI apps as they do not interoperate correctly with C#/WinRT. 如需詳細資訊,請參閱本頁面For more details, see this page.

  • 如果您在設定 URI 屬性時發生損毀情況 (例如在 Xaml 標記中使用 {Binding} 時),您可以使用 {x:Bind} 或使用 C#/WinRT 的預覽版本來解決此問題。If you experience a crash setting a URI property, for example using a {Binding} in Xaml markup, you can work around it by using {x:Bind}, or by using a preview version of C#/WinRT. 若要這麼做,請將下列幾行新增至您的 .csproj 檔案:To do this, add the following lines to your .csproj file:

    <ItemGroup>
      <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" 
                          RuntimeFrameworkVersion="10.0.18362.11-preview" />
      <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" 
                          TargetingPackVersion="10.0.18362.11-preview" />
    </ItemGroup>
    
  • 針對 C# UWP 應用程式:For C# UWP apps:

    WinUI 3 架構是一組 WinRT 元件,可以從 C++ (使用 C++/WinRT) 或 C# 中使用。The WinUI 3 framework is a set of WinRT components which can be used from C++ (using C++/WinRT) or C#. 使用時 C#,.NET 會有兩個版本 (視應用程式模型而定):在 UWP 應用程式中使用 WinUI 3 時,您使用的是使用 .NET Native;而在桌面應用程式中使用時,則是使用 .NET 5 (和 C#/WinRT)。When using C#, there are two versions of .NET, depending on the app model: when using WinUI 3 in a UWP app you’re using .NET Native; when using in a Desktop app you’re using .NET 5 (and C#/WinRT).

    在 UWP 中針對 WinUI 3 應用程式使用 C# 時,API 命名空間會與在 WinUI 3 桌面應用程式或 C# WinUI 2 應用程式中使用 C# 時有一些差異:某些類型會位於 Microsoft 命名空間,而不是 System 命名空間中。When using C# for a WinUI 3 app in UWP, there are a few API namespace differences compared to C# in a WinUI 3 Desktop app or a C# WinUI 2 app: some types are in a Microsoft namespace rather than a System namespace. 例如,不是在 System.ComponentModel 命名空間中的 INotifyPropertyChanged 介面,而是在 Microsoft.UI.Xaml.Data 命名空間中。For example, rather than the INotifyPropertyChanged interface being in the System.ComponentModel namespace, it’s in the Microsoft.UI.Xaml.Data namespace.

    這適用於:This applies to:

    • INotifyPropertyChanged (和相關的類型)INotifyPropertyChanged (and related types)
    • INotifyCollectionChanged
    • ICommand

    System 命名空間版本仍然存在,但不能與 WinUI 3 搭配使用。The System namespace versions still exist, but cannot be used with WinUI 3. 這表示 ObservableCollection 在 WinUI 3 C# UWP 應用程式中不會如預期般運作。This means that ObservableCollection doesn't work as-is in WinUI 3 C# UWP apps. 如需因應措施,請參閱 XAML 控制項庫範例中的 CollectionsInterop 範例For a workaround, see the CollectionsInterop sample in the XAML Controls Gallery sample.

如需包含所有 WinUI 3 預覽版 3 控制項和功能的範例應用程式,請參閱 XAML 控制項資源庫的 WinUI 3 預覽版 3 分支See the WinUI 3 Preview 3 branch of the XAML Controls Gallery for a sample app that includes all WinUI 3 Preview 3 controls and features.

WinUI 3 預覽版 3 XAML 控制項庫應用程式WinUI 3 Preview 3 XAML Controls Gallery app
WinUI 3 預覽版 3 XAML 控制項庫應用程式的範例Example of the WinUI 3 Preview 3 XAML Controls Gallery app

若要下載範例,請使用下列命令來複製 winui3preview 分支:To download the sample, clone the winui3preview branch using the following command:

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

複製之後,請確定您已切換至本機 Git 環境中的 winui3preview 分支:After cloning, ensure that you switch to the winui3preview branch in your local Git environment:

git checkout winui3preview