共用方式為


WinUI 2 使用者入門

WinUI 2.8 是最新的 WinUI 穩定版,可用於建置生產 UWP 應用程式 (以及使用 XAML Islands 的桌面應用程式)。

程式庫會以 NuGet 套件的形式來提供,可供新增至任何新的或現有的 Visual Studio 專案。

注意

如需使用最新版的 WinUI 3 來建置 Windows 桌面應用程式的詳細資訊,請參閱 WinUI 3

請下載並安裝 WinUI

  1. 下載 Visual Studio 2022,並務必在 Visual Studio 安裝程式中選擇 [通用 Windows 平台開發] 工作負載。

  2. 開啟現有專案,或使用 [Visual C#] -> [Windows] -> [通用] 底下的 [空白應用程式] 範本建立新專案 (也可以使用適用於您語言專案的適當範本來建立)。

    重要

    若要使用 WinUI 2.8,您的專案屬性必須設為 TargetPlatformVersion >= 10.0.18362.0 和 TargetPlatformMinVersion >= 10.0.17763.0。

  3. 在 [方案總管] 面板中,以滑鼠右鍵按一下專案名稱,然後選取 [管理 NuGet 套件]

    [方案總管] 面板的螢幕擷取畫面,已使用滑鼠右鍵按一下專案,且醒目提示 [管理 NuGet 套件] 選項。
    [方案總管] 面板,其中已使用滑鼠右鍵按一下專案,且醒目提示 [管理 NuGet 套件] 選項。

  4. 在 [NuGet 套件管理員] 中選取 [瀏覽] 索引標籤,然後搜尋 Microsoft.UI.XamlWinUI。 選取您想要使用的 WinUI NuGet 套件 (Microsoft.UI.Xaml 套件包含適用於所有應用程式的 Fluent 控制項和功能)。 按一下 [安裝]。

    核取 [包含發行前版本] 核取方塊,以查看包含實驗性新功能的最新發行前版本。

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

  5. 將 WinUI 佈景主題資源新增至 App.xaml 檔案。

    視您是否有額外的應用程式資源而定,您可以透過兩種方式來執行此動作。

    a. 如果您不需要其他應用程式資源,請新增 WinUI 資源元素 <XamlControlsResources,如下列範例所示:

    <Application
        x:Class="ExampleApp.App"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        RequestedTheme="Light">
    
        <Application.Resources>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
        </Application.Resources>
    
    </Application>
    

    b. 如果您有其他資源,建議您將這些資源新增至 XamlControlsResources.MergedDictionaries。 這適用於平台的資源系統,以允許覆寫 XamlControlsResources 資源。

    <Application
        x:Class="ExampleApp.App"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:controls="using:Microsoft.UI.Xaml.Controls"
        RequestedTheme="Light">
    
        <Application.Resources>
            <controls:XamlControlsResources>
                <controls:XamlControlsResources.MergedDictionaries>
                    <ResourceDictionary Source="/Styles/Styles.xaml"/>
                    <!-- Other app resources here -->
                </controls:XamlControlsResources.MergedDictionaries>
            </controls:XamlControlsResources>
        </Application.Resources>
    
    </Application>
    
  6. 將 WinUI 套件的參考新增至 XAML 頁面及/或程式碼後置頁面。

    • 在 XAML 頁面中,於頁面頂端新增參考

      xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
      
    • 在您的程式碼中 (如果您想要使用類型名稱,而不加以限定),您可以新增 using 指示詞。

      using MUXC = Microsoft.UI.Xaml.Controls;
      

C++/WinRT 專案的其他步驟

當您將 NuGet 套件新增至 C++/WinRT 專案時,工具會在專案的 \Generated Files\winrt 資料夾中產生一組投影標頭。 若要將這些標頭檔帶入專案中,讓這些新類型的參考可以解析,您可以移至先行編譯標頭檔 (通常是 pch.h) 並納入這些類型。 以下範例包含為 Microsoft.UI.Xaml 套件所產生的標頭檔。

// 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>
...

如需如何將 WinUI 的簡易支援新增至 C++/WinRT 專案的完整逐步解說,請參閱 C++/WinRT WinUI 簡易範例

參與 WinUI

我們歡迎您在 GitHub 的 microsoft-ui-xaml repo 中提出錯誤回報、功能要求和社群程式碼貢獻。

其他資源

如果您不熟悉 UWP,建議您造訪開發人員入口網站上的 UWP 開發入門頁面。