開始使用 Windows UI 2.x 程式庫Getting started with the Windows UI 2.x Library

WinUI 2.4 是 WinUI 的最新穩定版本,生產環境中的應用程式應使用此版本。WinUI 2.4 is the latest stable version of WinUI and should be used for apps in production.

程式庫會以 NuGet 套件的形式來提供,可供新增至任何新的或現有的 Visual Studio 專案。The library is available as a NuGet package that can be added to any new or existing Visual Studio project.

注意

如需試用 WinUI 3 早期預覽版的詳細資訊,請參閱 Windows UI 程式庫 3 預覽版 3 (2020 年 11 月)For more information on trying out early previews of WinUI 3, see Windows UI Library 3 Preview 3 (November 2020).

下載並安裝 Windows UI 程式庫Download and install the Windows UI Library

  1. 下載 Visual Studio 2019,並務必在 Visual Studio 安裝程式中選擇 [通用 Windows 平台開發] 工作負載。Download Visual Studio 2019 and ensure you choose the Universal Windows Platform development Workload in the Visual Studio installer.

  2. 開啟現有專案,或使用 [Visual C#] -> [Windows] -> [通用] 底下的 [空白應用程式] 範本建立新專案 (也可以使用適用於您語言投影的適當範本來建立)。Open an existing project, or create a new project using the Blank App template under Visual C# -> Windows -> Universal, or the appropriate template for your language projection.

    重要

    若要使用 WinUI 2.4,您必須在專案屬性中設定 TargetPlatformVersion >= 10.0.18362.0 和 TargetPlatformMinVersion >= 10.0.15063.0。To use WinUI 2.4, you must set TargetPlatformVersion >= 10.0.18362.0 and TargetPlatformMinVersion >= 10.0.15063.0 in the project properties.

  3. 在 [方案總管] 面板中,以滑鼠右鍵按一下專案名稱,然後選取 [管理 NuGet 套件]。In the Solution Explorer panel, right click on your project name and select Manage NuGet Packages. 選取 [瀏覽] 索引標籤,然後搜尋 Microsoft.UI.XamlWinUISelect the Browse tab, and search for Microsoft.UI.Xaml or WinUI. 然後選擇您要使用的 [Windows UI 程式庫 NuGet 套件]Then choose which Windows UI Library NuGet Packages you want to use. Microsoft.UI.Xaml 套件包含適用於所有應用程式的 Fluent 控制項和功能。The Microsoft.UI.Xaml package contains Fluent controls and features suitable for all apps.
    您可以選擇性地核取 [包含發行前版本],以查看包含實驗性新功能的最新發行前版本。You can optionally check "Include prerelease" to see the latest prerelease versions that include experimental new features.

    [方案總管] 面板的螢幕擷取畫面,已使用滑鼠右鍵按一下專案,且醒目提示 [管理 NuGet 套件] 選項。Screenshot of the Solution Explorer panel with the project right-clicked and the Manage NuGet Packages option highlighted.

    [NuGet 套件管理員] 對話方塊的螢幕擷取畫面,其中顯示搜尋欄位中含有 winui 的 [瀏覽] 索引標籤。

  4. 將 Windows UI (WinUI) 佈景主題資源新增至 App.xaml 資源。Add the Windows UI (WinUI) Theme Resources to your App.xaml resources. 視您是否有額外的應用程式資源而定,您可以透過兩種方式來執行此動作。There are two ways to do this, depending on whether you have additional application resources.

    a.a. 如果您沒有其他應用程式資源,請將 <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls"/> 新增至您的 Application.Resources:If you don't have other application resources, add <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls"/> to your Application.Resources:

    <Application>
        <Application.Resources>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
        </Application.Resources>
    </Application>
    

    b.b. 否則,如果您有多組應用程式資源,則請將 <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls"/> 新增至 Application.Resources.MergedDictionaries:Otherwise, if you have more than one set of application resources, add <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls"/> to Application.Resources.MergedDictionaries:

    <Application>
        <Application.Resources>
            <ResourceDictionary>
                <ResourceDictionary.MergedDictionaries>
                    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                </ResourceDictionary.MergedDictionaries>
            </ResourceDictionary>
        </Application.Resources>
    </Application>
    

    重要

    資源新增至 ResourceDictionary 的順序會影響其套用順序。The order of resources added to a ResourceDictionary affects the order in which they are applied. XamlControlsResources 字典會覆寫許多預設的資源索引鍵,因此應先將其新增至 Application.Resources,以免其覆寫您應用程式中的任何其他自訂樣式或資源。The XamlControlsResources dictionary overrides many default resource keys and should therefore be added to Application.Resources first so that it doesn't override any other custom styles or resources in your app. 如需如何載入資源的詳細資訊,請參閱 ResourceDictionary 與 XAML 資源參考For more information on resource loading, see ResourceDictionary and XAML resource references.

  5. 將工具組的參考新增至 XAML 頁面和程式碼後置頁面。Add a reference to the toolkit to XAML pages and your code-behind pages.

    • 在 XAML 頁面中,於頁面頂端新增參考In your XAML page, add a reference at the top of your page

      xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
      
    • 在您的程式碼中 (如果您想要使用類型名稱,而不加以限定),您可以新增 using 指示詞。In your code (if you want to use the type names without qualifying them), you can add a using directive.

      using MUXC = Microsoft.UI.Xaml.Controls;
      

C++/WinRT 專案的其他步驟Additional steps for a C++/WinRT project

當您將 NuGet 套件新增至 C++/WinRT 專案時,工具會在專案的 \Generated Files\winrt 資料夾中產生一組投影標頭。When you add a NuGet package to a C++/WinRT project, the tooling generates a set of projection headers in your project's \Generated Files\winrt folder. 若要將這些標頭檔帶入專案中,讓這些新類型的參考可以解析,您可以移至先行編譯標頭檔 (通常是 pch.h) 並納入這些類型。To bring those headers files into your project, so that references to those new types resolve, you can go into your precompiled header file (typically pch.h) and include them. 以下範例包含為 Microsoft.UI.Xaml 套件所產生的標頭檔。Below is an example that includes the generated header files for the Microsoft.UI.Xaml package.

// pch.h
...
#include "winrt/Microsoft.UI.Xaml.Automation.Peers.h"
#include "winrt/Microsoft.UI.Xaml.Controls.Primitives.h"
#include "winrt/Microsoft.UI.Xaml.Media.h"
#include "winrt/Microsoft.UI.Xaml.XamlTypeInfo.h"
...

如需如何將 Windows UI 程式庫的簡單支援新增至 C++/WinRT 專案的完整逐步解說,請參閱 C++/WinRT Windows UI 程式庫簡單範例For a full, step-by-step walkthrough of adding simple support for the Windows UI Library to a C++/WinRT project, see A simple C++/WinRT Windows UI Library example.

參與 Windows UI 程式庫Contributing to the Windows UI Library

WinUI 是裝載於 GitHub 上的開放原始碼專案。WinUI is an open source project hosted on GitHub.

我們歡迎您在 Windows UI 程式庫存放庫中提出錯誤回報、功能要求和社群程式碼。We welcome bug reports, feature requests and community code contributions in the Windows UI Library repo.

其他資源Other resources

如果您不熟悉 UWP,建議您造訪開發人員入口網站上的 UWP 開發入門頁面。If you're new to UWP, then we recommend that you visit the Getting Started with UWP Development pages on the Developer portal.