Aracılığıyla paylaş

Başlık çubuğu özelleştirme

Windows, her pencere için varsayılan bir başlık çubuğu sağlar ve uygulamanızın kişiliğiyle eşleşecek şekilde özelleştirmenize olanak tanır. Varsayılan başlık çubuğu, pencereyi sürükleyip yeniden boyutlandırma gibi bazı standart bileşenler ve temel işlevlerle birlikte gelir.

Başlık çubuğunu gösteren bir Windows uygulaması

Uygulamanızın başlık çubuğunu , kabul edilebilir başlık çubuğu alanı içeriğini ve önerilen kullanıcı arabirimi desenlerini özelleştirme yönergeleri için Başlık çubuğu tasarım makalesine bakın.

Başlık çubuğu için Windows 11 Fluent Design kılavuzuna bakın

Important

Bu makalede, WinUI 3 ile veya WinUI 3 olmadan Windows Uygulama SDK'sını kullanan uygulamalar için başlık çubuğunun nasıl özelleştirileceği gösterilmektedir. UWP ve WinUI 2 kullanan uygulamalar için bkz. UWP için Başlık çubuğu özelleştirme .

Important

Windows Uygulama SDK'sı 1.7'ye yeni bir Başlık çubuğu denetimi eklendi. Başlık çubuğu özelleştirme işlemini basitleştirir.

Başlık çubuğu bileşenleri

Bu liste, standart başlık çubuğunun bileşenlerini açıklar.

  • Başlık çubuğu dikdörtgeni
  • Başlık metni
  • Sistem simgesi
  • Sistem menüsü - Uygulama simgesine veya başlık çubuğuna sağ tıklayarak erişilir
  • Resim yazısı denetimleri
    • Simge Durumuna Küçült düğmesi
    • Ekranı Kapla/Geri Yükle düğmesi
    • Kapat düğmesi

Windowing

Windows Uygulama SDK'sı pencereleme işlevi, Win32 HWND modelini temel alan Microsoft.UI.Windowing.AppWindow sınıfı aracılığıyla kullanılmaktadır. AppWindow ile uygulamanızdaki en üst düzey HWND arasında 1:1 eşlemesi vardır. AppWindow ve ilgili sınıfları, başlık çubuğunu özelleştirme de dahil olmak üzere uygulamanızın üst düzey pencerelerinin birçok yönünü yönetmenize olanak sağlayan API'ler sağlar. Windows'un sağladığı varsayılan başlık çubuğunu, kullanıcı arabiriminizin geri kalanıyla uyumlu olacak şekilde değiştirebilir veya uygulama tuvalinizi başlık çubuğu alanına genişletip kendi başlık çubuğu içeriğinizi sağlayabilirsiniz.

WinUI 3'teki pencereleme işlevi, Win32 HWND modelini de temel alan Microsoft.UI.Xaml.Window sınıfı üzerinden yapılır. WinUI 3 kullanan XAML uygulamaları için, XAML Penceresi API'leri başlık çubuğunu özelleştirmek için daha basit bir yol sağlarken gerektiğinde AppWindow API'lerine erişmenizi sağlar.

AppWindow ile çalışma

AppWindow API'lerini Windows Uygulama SDK'sının desteklediği herhangi bir UI çerçevesiyle kullanabilirsiniz : Win32, WPF, WinForms veya WinUI 3 - ve bunları yalnızca ihtiyacınız olan API'leri kullanarak artımlı olarak benimseyebilirsiniz.

Uygulamanızın UI çerçevesi olarak WinUI 3 XAML kullanıyorsanız hem Window hem de AppWindow API'leri kullanılabilir. Windows Uygulama SDK'sı 1.4'den başlayarak, XAML Penceresi ve AppWindow başlık çubuğu özelleştirmesi için aynı AppWindowTitleBar nesnesini kullanır. Mevcut bir XAML penceresinden AppWindow nesnesi almak için Window.AppWindow özelliğini kullanın. Bu AppWindow nesnesiyle başlık çubuğu özelleştirme API'lerine erişebilirsiniz. Başlık çubuğunun ek özelliklerine erişmek için XAML Pencerenizdeki AppWindow API'lerini şu şekilde kullanabilirsiniz: AppWindow.TitleBar.ForegroundColor = Colors.White;.

WinUI 3 1.3 veya sonraki bir sürümü kullanmıyorsanız, birlikte çalışma API'lerini kullanarak AppWindow'ı edinin ve başlık çubuğunu özelleştirmek için AppWindow API'lerini kullanın. Birlikte çalışma API'leri hakkında daha fazla bilgi için bkz. Uygulama pencerelerini yönetme - UI çerçevesi ve HWND birlikte çalışması ve Pencereleme galerisi örneği.

Başlık çubuğunu ne kadar özelleştirmek gerekiyor?

Başlık çubuğuna uygulayabileceğiniz iki özelleştirme düzeyi vardır: varsayılan başlık çubuğuna küçük değişiklikler uygulayın veya uygulama tuvalinizi başlık çubuğu alanına genişletip tamamen özel içerik sağlayın.

Simple

Başlık çubuğu rengini değiştirme gibi basit özelleştirmeler için AppWindowTitleBar nesnesinde özellikleri, başlık çubuğu öğeleri için kullanmak istediğiniz renkleri belirtmek üzere ayarlayabilirsiniz. Bu durumda sistem, uygulama başlığını çizme ve sürükleme alanlarını tanımlama gibi başlık çubuğunun diğer tüm yönlerinden sorumlu olur.

Full

Diğer seçeneğiniz, varsayılan sistem başlık çubuğunu gizlemek ve kendi özel içeriğiniz ile değiştirmektir. Örneğin, başlık çubuğu alanına metin, arama kutusu veya özel menüler yerleştirebilirsiniz. Mica gibi bir malzeme arka planı başlık çubuğu alanına genişletmek için de bu seçeneği kullanmanız gerekir.

Tam özelleştirmeyi tercih ettiğinizde, başlık çubuğu alanına içerik yerleştirmek sizin sorumluluğunuzdadır ve kendi sürükleme bölgelerinizi tanımlayabilirsiniz. Başlık denetimleri (sistem Kapat, Simge Durumuna Küçült ve Büyüt düğmeleri) sistem tarafından hala kullanılabilir ve işlenir, ancak uygulama başlığı gibi öğeler kullanılamaz. Bu öğeleri uygulamanızın ihtiyaç duyduğu şekilde oluşturmanız gerekir.

Basit özelleştirme

Yalnızca başlık çubuğu başlığını, renklerini veya simgesini özelleştirmek istiyorsanız, uygulama pencerenizin başlık çubuğu nesnesinde özellikleri ayarlayabilirsiniz.

Title

Varsayılan olarak, başlık çubuğunda uygulama türü pencere başlığı olarak gösterilir (örneğin, "WinUI Desktop"). Pencere başlığını, uygulamanız için anlamlı bir görünen ad gösterecek şekilde güncelleştirmeniz gerekir.

XAML uygulamasında, Package.appxmanifest dosyasında ayarlanmış bir görünen ad bulunmaktadır. Bu değeri alabilir ve Title özelliğini bunun gibi ayarlamak için kullanabilirsiniz.

Title = AppInfo.Current.DisplayInfo.DisplayName;

Pencere başlığını değiştirmek için Window.Title özelliğini burada gösterildiği gibi tek satırlı metin değerine ayarlayın.

<Window
    ...
    Title="App title">
    ...
</Window>

public MainWindow()
{
    InitializeComponent();
    Title = "App title";
}

AppWindow API'lerini kullanarak pencere başlığını değiştirmek için AppWindow.Title özelliğini burada gösterildiği gibi tek satırlı metin değerine ayarlayın. Bu örnekte, uygulamanız WinUI 3 1.3 veya sonraki bir sürümünü kullanmıyorsa ihtiyaç duyulan AppWindow'u elde etmek için birlikte çalışma API'lerinin nasıl kullanılacağı gösterilmektedir.

using Microsoft.UI;           // Needed for WindowId.
using Microsoft.UI.Windowing; // Needed for AppWindow.
using WinRT.Interop;          // Needed for XAML/HWND interop.

private AppWindow m_AppWindow;

public MainWindow()
{
    this.InitializeComponent();

    m_AppWindow = GetAppWindowForCurrentWindow();
    m_AppWindow.Title = "App title";
}

private AppWindow GetAppWindowForCurrentWindow()
{
    IntPtr hWnd = WindowNative.GetWindowHandle(this);
    WindowId wndId = Win32Interop.GetWindowIdFromWindow(hWnd);
    return AppWindow.GetFromWindowId(wndId);
}

Colors

Varsayılan başlık çubuğu renklerini özelleştirmek veya varsayılan pencere simgesini değiştirmek için AppWindow API'lerini kullanmanız veya başlık çubuğunuzu tamamen özelleştirmeyi tercih etmeniz gerekir.

Bu örnekte AppWindowTitleBar örneğinin nasıl alınıp renk özelliklerinin nasıl ayarlanacağı gösterilmektedir.

Important

Uygulama Windows 10'da çalıştırıldığında renk özelleştirmesi yoksayılır.

// Assumes "this" is a XAML Window. In projects that don't use 
// WinUI 3 1.3 or later, use interop APIs to get the AppWindow.
AppWindow m_AppWindow = this.AppWindow;

private bool SetTitleBarColors()
{
    // Check to see if customization is supported.
    // The method returns true on Windows 10 since Windows App SDK 1.2,
    // and on all versions of Windows App SDK on Windows 11.
    if (AppWindowTitleBar.IsCustomizationSupported())
    {
        AppWindowTitleBar m_TitleBar = m_AppWindow.TitleBar;

        // Set active window colors.
        // Note: No effect when app is running on Windows 10
        // because color customization is not supported.
        m_TitleBar.ForegroundColor = Colors.White;
        m_TitleBar.BackgroundColor = Colors.Green;
        m_TitleBar.ButtonForegroundColor = Colors.White;
        m_TitleBar.ButtonBackgroundColor = Colors.SeaGreen;
        m_TitleBar.ButtonHoverForegroundColor = Colors.Gainsboro;
        m_TitleBar.ButtonHoverBackgroundColor = Colors.DarkSeaGreen;
        m_TitleBar.ButtonPressedForegroundColor = Colors.Gray;
        m_TitleBar.ButtonPressedBackgroundColor = Colors.LightGreen;

        // Set inactive window colors.
        // Note: No effect when app is running on Windows 10
        // because color customization is not supported.
        m_TitleBar.InactiveForegroundColor = Colors.Gainsboro;
        m_TitleBar.InactiveBackgroundColor = Colors.SeaGreen;
        m_TitleBar.ButtonInactiveForegroundColor = Colors.Gainsboro;
        m_TitleBar.ButtonInactiveBackgroundColor = Colors.SeaGreen;
        return true;
    }
    return false;
}

Başlık çubuğu renklerini ayarlarken dikkat etmeniz gereken birkaç şey vardır:

  • Düğme arka plan rengi, düğmeyi kapat üzerine gelindiğinde ve basıldığında durumlara uygulanmaz. Kapat düğmesi her zaman bu durumlar için sistem tanımlı rengi kullanır.
  • Color özelliğini null olarak ayarlamak, bunu varsayılan sistem rengine sıfırlar.
  • Saydam renkler ayarlayamazsınız. Rengin alfa kanalı yoksayılır.

Windows, kullanıcıya seçili tema rengini başlık çubuğuna uygulama seçeneği sunar. Herhangi bir başlık çubuğu rengi ayarlarsanız, tüm renkleri açıkça ayarlamanızı öneririz. Bu, kullanıcı tanımlı renk ayarları nedeniyle istenmeyen renk bileşimleri olmamasını sağlar.

Simge ve sistem menüsü

Sistem simgesini gizleyebilir veya özel bir simgeyle değiştirebilirsiniz. Sistem simgesi, bir kez sağ tıklandığında veya dokunulduğunda sistem menüsünü gösterir. Çift tıklandığında/dokunulduğunda pencereyi kapatır.

Sistem simgesini ve ilişkili davranışları göstermek veya gizlemek için IconShowOptions özelliğini başlık çubuğunu ayarlayın.

m_TitleBar.IconShowOptions = IconShowOptions.HideIconAndSystemMenu;

Özel pencere simgesi kullanmak için AppWindow.SetIcon yöntemlerinden birini çağırarak yeni simgeyi ayarlayın.

  • SetIcon(String)

    SetIcon(String) yöntemi şu anda yalnızca .ico dosyalarıyla çalışır. Bu yönteme ilettiğiniz dize, .ico dosyasının tam nitelikli yoludur.

    m_AppWindow.SetIcon("iconPath/iconName.ico");

  • SetIcon(IconId)

    CreateIcon gibi Simge işlevlerinden birinden bir simgenin (HICON) tutamacı zaten varsa, IconId almak için GetIconIdFromIcon birlikte çalışma API'sini kullanabilirsiniz. Ardından, pencere simgenizi ayarlamak için SetIcon(IconId) yöntemine geçirebilirsinizIconId.

    m_AppWindow.SetIcon(iconId));

Tam özelleştirme

Tam başlık çubuğu özelleştirmesini kabul ettiğinizde, uygulamanızın istemci alanı başlık çubuğu alanı da dahil olmak üzere tüm pencereyi kapsayacak şekilde genişletilir. Pencere tarafından sağlanan başlık düğmeleri hariç, tüm pencere için çizim ve giriş işlemleri sizin sorumluluğunuzdadır.

Sistem başlık çubuğunu gizlemek ve içeriğinizi başlık çubuğu alanına genişletmek için, uygulama içeriğini başlık çubuğu alanına genişleten özelliği trueolarak ayarlayın. Bir XAML uygulamasında, bu özellik uygulamanızın OnLaunched yönteminde (App.xaml.cs) veya uygulamanızın ilk sayfasında ayarlanabilir.

Tip

Tüm kodu aynı anda görmek için Tam özelleştirme örneği bölümüne bakın.

Bu örnekte Window.ExtendsContentIntoTitleBar özelliğinin trueolarak nasıl ayarlanacağı gösterilmektedir.

public MainWindow()
{
    this.InitializeComponent();

    // Hide system title bar.
    ExtendsContentIntoTitleBar = true;
}

Caution

ExtendsContentIntoTitleBar, Windowiçin XAML IntelliSense'te gösterilir, ancak bunu XAML'de ayarlamak hataya neden olur. Bunun yerine kodda bu özelliği ayarlayın.

Bu örnekte AppWindowTitleBar'ın nasıl alınıp AppWindowTitleBar.ExtendsContentIntoTitleBar özelliğinintrueolarak nasıl ayarlanacağı gösterilmektedir. Bu örnekte, uygulamanız WinUI 3 1.3 veya sonraki bir sürümü kullanmıyorsa gereken AppWindow'a ulaşmak için birlikte çalışma API'lerinin nasıl kullanılacağı gösterilmektedir.

using Microsoft.UI;           // Needed for WindowId.
using Microsoft.UI.Windowing; // Needed for AppWindow.
using WinRT.Interop;          // Needed for XAML/HWND interop.

private AppWindow m_AppWindow;

public MainWindow()
{
    this.InitializeComponent();

    m_AppWindow = GetAppWindowForCurrentWindow();
    var titleBar = m_AppWindow.TitleBar;
    // Hide system title bar.
    titleBar.ExtendsContentIntoTitleBar = true;
}

private AppWindow GetAppWindowForCurrentWindow()
{
    IntPtr hWnd = WindowNative.GetWindowHandle(this);
    WindowId wndId = Win32Interop.GetWindowIdFromWindow(hWnd);
    return AppWindow.GetFromWindowId(wndId);
}

Başlık çubuğu içeriği ve varsayılan sürükleme bölgesi

Uygulamanız başlık çubuğu alanına genişletildiğinde, başlık çubuğu için kullanıcı arabirimini tanımlamak ve yönetmek sizin sorumluluğunuzdadır. Bu genellikle en azından başlık metnini ve sürükleme bölgesini belirtmeyi içerir. Başlık çubuğunun sürükleme bölgesi, kullanıcının pencereyi taşımak için nereye tıklayıp sürükleyebileceğini tanımlar. Ayrıca kullanıcı sistem menüsünü göstermek için sağ tıklayabileceği yerdir.

Kabul edilebilir başlık çubuğu içeriği ve önerilen kullanıcı arabirimi desenleri hakkında daha fazla bilgi edinmek için bkz. başlık çubuğu tasarımı .

Bu örnekte etkileşimli içerik içermeyen özel başlık çubuğu kullanıcı arabirimi için XAML gösterilmektedir.

<Grid x:Name="AppTitleBar"  
      Height="32">
    <Grid.ColumnDefinitions>
        <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
        <ColumnDefinition/>
        <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
    </Grid.ColumnDefinitions>
    <Image x:Name="TitleBarIcon" Source="ms-appx:///Assets/StoreLogo.png"
           Grid.Column="1"
           HorizontalAlignment="Left"
           Width="16" Height="16"
           Margin="8,0,0,0"/>
    <TextBlock x:Name="TitleBarTextBlock" 
               Text="App title" 
               Style="{StaticResource CaptionTextBlockStyle}"
               Grid.Column="1"
               VerticalAlignment="Center"
               Margin="28,0,0,0"/>
</Grid>

Important

LeftPaddingColumn ve RightPaddingColumn, resim yazısı düğmeleri için yer ayırmak için kullanılır. Bu sütunların Width değerleri daha sonra gösterilen kodda ayarlanır. Kod ve açıklama için Sistem resim yazısı düğmeleri bölümüne bakın.

XAML uygulamasının görünen adı, Package.appxmanifest dosyasında ayarlanır. Bu değeri alabilir ve özel başlık çubuğunuzda aşağıdaki gibi kullanabilirsiniz.

TitleBarTextBlock.Text = AppInfo.Current.DisplayInfo.DisplayName;

İçeriğinizi başlık çubuğu alanına genişlettiğinizde, sistem başlık çubuğu gizlenir ve resim yazısı düğmeleri ve ekranın genişliği boyunca sistem başlık çubuğuyla aynı bir sürükleme bölgesi sağlayan varsayılan bir AppWindowTitleBar oluşturulur. Başlık çubuğunuza etkileşimli içerik yerleştirmezseniz, bu varsayılan sürükleme bölgesini as-isbırakabilirsiniz. Başlık çubuğunuza etkileşimli içerik yerleştirirseniz, sonraki bölümde ele aldığımız etkileşimli bölgeleri belirtmeniz gerekir.

Caution

Özel sürükleme bölgeleri tanımladığınızda, varsayılan başlık çubuğu alanında pencerenin en üstünde olmaları gerekmez; kullanıcı arabiriminizin herhangi bir bölümünü sürükleme bölgesi olarak tanımlayabilirsiniz. Ancak sürükleme bölgelerinin farklı yerlere yerleştirilmesi, kullanıcılarınızın bunları bulmasını zorlaştırabilir.

Etkileşimli içerik

Düğme, menü veya arama kutusu gibi etkileşimli denetimleri uygulamanın üst bölümüne yerleştirerek başlık çubuğunda görünmelerini sağlayabilirsiniz. Ancak, etkileşimli öğelerinizin kullanıcı girişi aldığından emin olmak ve kullanıcıların pencerenizi hareket ettirmesine izin vermek için hangi bölgelerin etkileşimli olduğunu belirtmeniz gerekir.

Başlık çubuğunda arama kutusu bulunan bir Windows uygulaması

Başlık çubuğu alanına etkileşimli içerik eklediğinizde, girdinin başlık çubuğu tarafından işlenmek yerine etkileşimli denetime geçirildiği alanları belirtmek için InputNonClientPointerSource sınıfını kullanmanız gerekir. Etkileşimli bölgeleri ayarlamak için InputNonClientPointerSource.SetRegionRects yöntemini çağırın. Bu yöntem, ayarlanan bölge türünü (bu örnekte Passthrough) belirten bir değer ve her biri Passthrough bir bölge tanımlayan bir dikdörtgen dizisi alır. Başlık çubuğunun boyutu değiştiğinde, etkileşimli bölgeleri yeni boyutla eşleşecek şekilde yeniden hesaplamanız ve yeni değerlerle SetRegionRects çağırmanız gerekir.

Bu örnekte arama kutusu ve PersonPicture hesap denetimi içeren özel bir başlık çubuğu kullanıcı arabirimi gösterilmektedir. Bu denetimler için etkileşimli dikdörtgenlerin nasıl hesaplanıp ayarlanacağı ve bu dikdörtgenlerin girişleri nasıl ileteceği gösterilir.

Bu kod hakkında dikkat edilmesi gereken birkaç önemli nokta şunlardır:

  • AppTitleBar Etkileşimli içerik için Başlık çubuğu tasarım kılavuzunu izlemek için Kılavuz yüksekliğini 48 olarak ayarlayın.
  • Başlık düğmelerinin başlık çubuğuyla aynı yükseklikte olması için TallPreferredHeightOption olarak ayarlayın.
  • Kontrolleri yeniden boyutlandırmayı ve bölgeleri hesaplamayı kolaylaştırmak için, düzeni oluştururken birden çok adlandırılmış sütun içeren bir Grid kullanın.
  • öğesini içeren AutoSuggestBox sütun için ile yıldız (*) boyutlandırmasını MinWidth kullanın; böylece pencereyle otomatik olarak yeniden boyutlandırılır.
  • MinWidth'ı RightDragColumn'e ayarlayarak pencere yeniden boyutlandırıldığında bile her zaman sürüklenebilir küçük bir alan oluşturun.
  • ExtendsContentIntoTitleBar MainWindow oluşturucusunda true olarak ayarlayın. Daha sonra çağrılan kodda ayarlarsanız, önce varsayılan sistem başlık çubuğu gösterilebilir ve ardından gizlenebilir.
  • AppTitleBar öğesi yüklendikten sonra etkileşimli bölgeleri hesaplamak için ilk çağrıyı yapın. Aksi takdirde, hesaplama için kullanılan öğelerin doğru değerlere sahip olacağının garantisi yoktur.
  • Etkileşimli dikdörtgen hesaplamalarını yalnızca AppTitleBar öğesi boyut değiştirildikten sonra (AppTitleBar_SizeChanged) güncelleştirin. Eğer Changed penceresi olayına bağlıysanız, AppTitleBar henüz yeniden boyutlandırılmamışken olayın gerçekleştiği ve hesaplamaların yanlış değerlere dayandığı durumlar (örneğin pencereyi büyütmek/küçültmek gibi) olabilir.
  • Özel sürükle/etkileşimli alanlarınızı yalnızca özel başlık çubuğunun kullanıldığını onaylamak için ExtendsContentIntoTitleBar denetledikten sonra ayarlayın.
<Grid x:Name="AppTitleBar"
      Height="48">
    <Grid.ColumnDefinitions>
        <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
        <ColumnDefinition x:Name="IconColumn" Width="Auto"/>
        <ColumnDefinition x:Name="TitleColumn" Width="Auto"/>
        <ColumnDefinition x:Name="LeftDragColumn" Width="*"/>
        <ColumnDefinition x:Name="SearchColumn" Width="4*" MinWidth="220"/>
        <ColumnDefinition x:Name="RightDragColumn" Width="*" MinWidth="48"/>
        <ColumnDefinition x:Name="AccountColumn" Width="Auto"/>
        <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
    </Grid.ColumnDefinitions>
    <Image x:Name="TitleBarIcon" 
           Source="ms-appx:///Assets/StoreLogo.png"
           Grid.Column="1"
           Width="16" Height="16"
           Margin="8,0,4,0"/>
    <TextBlock x:Name="TitleBarTextBlock"
               Text="App title" 
               Style="{StaticResource CaptionTextBlockStyle}"
               Grid.Column="2"
               VerticalAlignment="Center">
    </TextBlock>
    <AutoSuggestBox x:Name="TitleBarSearchBox" 
                    Grid.Column="4" 
                    QueryIcon="Find"
                    PlaceholderText="Search"
                    VerticalAlignment="Center"
                    MaxWidth="600"/>
    <PersonPicture x:Name="PersonPic" 
                   Grid.Column="6" 
                   Height="32" Margin="0,0,16,0"/>
</Grid>

Bu kod, AutoSuggestBox ve PersonPicture denetimlerine karşılık gelen etkileşimli bölgelerin nasıl hesaplandığını ve ayarlandığını gösterir.

public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();

        // Assumes "this" is a XAML Window. In projects that don't use 
        // WinUI 3 1.3 or later, use interop APIs to get the AppWindow.
        m_AppWindow = this.AppWindow;
        AppTitleBar.Loaded += AppTitleBar_Loaded;
        AppTitleBar.SizeChanged += AppTitleBar_SizeChanged;
        ExtendsContentIntoTitleBar = true;
        TitleBarTextBlock.Text = AppInfo.Current.DisplayInfo.DisplayName;
    }

    private void AppTitleBar_Loaded(object sender, RoutedEventArgs e)
    {
        if (ExtendsContentIntoTitleBar == true)
        {
            // Set the initial interactive regions.
            SetRegionsForCustomTitleBar();
        }
    }

    private void AppTitleBar_SizeChanged(object sender, SizeChangedEventArgs e)
    {
        if (ExtendsContentIntoTitleBar == true)
        {
            // Update interactive regions if the size of the window changes.
            SetRegionsForCustomTitleBar();
        }
    }

    private void SetRegionsForCustomTitleBar()
    {
        // Specify the interactive regions of the title bar.

        double scaleAdjustment = AppTitleBar.XamlRoot.RasterizationScale;

        RightPaddingColumn.Width = new GridLength(m_AppWindow.TitleBar.RightInset / scaleAdjustment);
        LeftPaddingColumn.Width = new GridLength(m_AppWindow.TitleBar.LeftInset / scaleAdjustment);

        GeneralTransform transform = TitleBarSearchBox.TransformToVisual(null);
        Rect bounds = transform.TransformBounds(new Rect(0, 0, 
                                                         TitleBarSearchBox.ActualWidth,
                                                         TitleBarSearchBox.ActualHeight));
        Windows.Graphics.RectInt32 SearchBoxRect = GetRect(bounds, scaleAdjustment);
        
        transform = PersonPic.TransformToVisual(null);
        bounds = transform.TransformBounds(new Rect(0, 0,
                                                    PersonPic.ActualWidth,
                                                    PersonPic.ActualHeight));
        Windows.Graphics.RectInt32 PersonPicRect = GetRect(bounds, scaleAdjustment);

        var rectArray = new Windows.Graphics.RectInt32[] { SearchBoxRect, PersonPicRect };

        InputNonClientPointerSource nonClientInputSrc =
            InputNonClientPointerSource.GetForWindowId(this.AppWindow.Id);
        nonClientInputSrc.SetRegionRects(NonClientRegionKind.Passthrough, rectArray);
    }

    private Windows.Graphics.RectInt32 GetRect(Rect bounds, double scale)
    {
        return new Windows.Graphics.RectInt32(
            _X: (int)Math.Round(bounds.X * scale),
            _Y: (int)Math.Round(bounds.Y * scale),
            _Width: (int)Math.Round(bounds.Width * scale),
            _Height: (int)Math.Round(bounds.Height * scale)
        );
    }
}

Warning

AppWindow, mantıksal koordinatları kullanmayan UI çerçeveleriyle uyumluluk için fiziksel pikselleri kullanır. WPF veya WinUI 3 kullanıyorsanız, RightInset, LeftInsetve görüntüleme ölçeği 100%değilse bölgeleri hesaplamak için kullanılan değerlerin ayarlanması gerekir. Bu örnekte, görüntüleme ölçeği ayarını hesaba katmamız gereken bir scaleAdjustment değeri elde ediyoruz.

Sistem başlık düğmeleri

Sistem, uygulama penceresinin sol üst veya sağ üst köşesini sistem başlık çubuğu düğmeleri için ayırır (simge durumuna küçült, ekranı kapla/geri yükle, kapat). Sistem, pencereyi sürüklemek, en aza indirmek, en üst düzeye çıkarmak ve kapatmak için en düşük işlevselliğin sağlandığını garanti etmek için resim yazısı düğmesi alanının denetimini elinde tutar. Sistem, soldan sağa diller için sağ üstteki Kapat düğmesini, sağdan sola diller için ise sol üstteki düğmeyi çizer.

Uygulama arka planınız gibi resim yazısı denetim alanının altına içerik çizebilirsiniz, ancak kullanıcının etkileşim kurabilmesini beklediğiniz hiçbir kullanıcı arabirimini yerleştirmemelisiniz. Başlık kontrolleri için giriş sistem tarafından işlendiği için herhangi bir giriş almaz.

Önceki örnekteki bu satırlar, başlık çubuğunu tanımlayan XAML'deki doldurma sütunlarını gösterir. Kenar boşlukları yerine doldurma sütunları kullanıldığında arka plan, resim yazısı denetim düğmelerinin altındaki alanı boyar (saydam düğmeler için). Hem sağ hem de sol doldurma sütunlarını kullanmak, başlık çubuğunuzun hem sağdan sola hem de soldan sağa düzenlerde doğru şekilde davranmasını sağlar.

<Grid.ColumnDefinitions>
    <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
    <ColumnDefinition/>
    <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
</Grid.ColumnDefinitions>

Başlık çubuğu kullanıcı arabiriminizin düzeninde hesaba ekleyebilmeniz için resim yazısı denetim alanının boyutları ve konumu AppWindowTitleBar sınıfı tarafından iletilir. Her iki taraftaki ayrılmış bölgenin genişliği LeftInset veya RightInset özellikleri tarafından, yüksekliği ise Height özelliği tarafından verilir.

Sürükleme bölgeleri hesaplanıp ayarlandığında doldurma sütunlarının genişliğinin nasıl belirtildiği aşağıda açıklanmaktadır.

RightPaddingColumn.Width = 
    new GridLength(m_AppWindow.TitleBar.RightInset / scaleAdjustment);
LeftPaddingColumn.Width = 
    new GridLength(m_AppWindow.TitleBar.LeftInset / scaleAdjustment);

Important

Görüntü ölçeklendirmenin bu değerleri nasıl etkilediği hakkında etkileşimli içerik bölümünde önemli bilgilere bakın.

Özel başlık çubukları için uzun başlık çubuğu desteği

Başlık çubuğuna arama kutusu veya kişi resmi gibi etkileşimli içerik eklediğinizde, bu öğelere daha fazla yer açmak için başlık çubuğunuzun yüksekliğini artırmanızı öneririz. Daha uzun bir başlık çubuğu, dokunma manipülasyonlarını da kolaylaştırır. AppWindowTitleBar.PreferredHeightOption özelliği, başlık çubuğu yüksekliğinizi varsayılan olan standart yükseklikten daha yüksek bir yüksekliğe yükseltme seçeneği sunar. Tall başlık çubuğu modunu seçtiğinizde, sistemin istemci alanında katman olarak çizdiği başlık düğmeleri, min/max/close simgeleri ortalanmış şekilde daha uzun hale getirilir. Sürükleme bölgesi belirtmediyseniz, sistem pencerenizin genişliğini ve ayarladığınız PreferredHeightOption değeri tarafından belirlenen yüksekliği genişleten bir bölge çizer.

Bu örnek, PreferredHeightOption özelliğini nasıl ayarlayabileceğinizi gösterir.

// A taller title bar is only supported when drawing a fully custom title bar.
if (ExtendsContentIntoTitleBar == true)
{
    m_AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Tall;
}

Caution

AppWindowTitleBar.ExtendsContentIntoTitleBar özelliğini ayarlamadan PreferredHeightOption önce olmalıdırtrue. Eğer PreferredHeightOptionExtendsContentIntoTitleBarise false ayarlamaya çalıştığınızda bir istisna atılır.

Resim yazısı düğmelerinde renk ve saydamlık

Uygulama içeriğinizi başlık çubuğu alanına genişlettiğinizde, uygulama arka planınızın gösterilmesini sağlamak için resim yazısı düğmelerinin arka planını saydam hale getirebilirsiniz. Tam saydamlık için genellikle arka planı Colors.Transparent olarak ayarlarsınız. Kısmi saydamlık için, özelliğini ayarladığınız Renk için alfa kanalını ayarlayın.

Bu başlık çubuğu özellikleri saydam olabilir:

Diğer tüm renk özellikleri alfa kanalını yoksaymaya devam edecektir. ExtendsContentIntoTitleBar falseolarak ayarlanırsa, alfa kanalı, tüm AppWindowTitleBar renk özelliklerinde her zaman yoksayılır.

Düğme arka plan rengi Kapat düğmesinin üzerine gelindiğinde ve basıldığında durumlara uygulanmaz. Kapat düğmesi her zaman bu durumlar için sistem tanımlı rengi kullanır.

Tip

Mica , odakta olan pencereyi ayırt etmesine yardımcı olan keyifli bir malzemedir . Windows 11'de uzun ömürlü pencereler için arka plan olarak kullanmanızı öneririz. Pencerenizin istemci alanına Mica uyguladıysanız, başlık çubuğuna genişletebilir ve Mica'nın görünmesi için başlık düğmelerinizi saydam hale getirebilirsiniz. Daha fazla bilgi için bkz. Mica malzemeleri .

Pencere etkin olmadığında başlık çubuğunu soluk hale getir.

Pencereniz etkin veya etkin olmadığında bunu açıkça ifade etmelisiniz. Başlık çubuğunuzdaki metnin, simgelerin ve düğmelerin rengini en azından değiştirmeniz gerekir.

XAML uygulamaları için Window.Activated olayını işleyip pencerenin etkinleştirme durumunu belirleyin ve başlık çubuğu kullanıcı arabiriminizi gerektiği gibi güncelleştirin.

public MainWindow()
{
    ...
    Activated += MainWindow_Activated;
}

private void MainWindow_Activated(object sender, WindowActivatedEventArgs args)
{
    if (args.WindowActivationState == WindowActivationState.Deactivated)
    {
        TitleBarTextBlock.Foreground =
            (SolidColorBrush)App.Current.Resources["WindowCaptionForegroundDisabled"];
    }
    else
    {
        TitleBarTextBlock.Foreground =
            (SolidColorBrush)App.Current.Resources["WindowCaptionForeground"];
    }
}

Diğer ui çerçeveleri için, pencerenin etkinleştirme durumunu belirlemek için bir olayı işleyin ve başlık çubuğu kullanıcı arabiriminizi gerektiği gibi güncelleştirin. Pencerenin durumunu nasıl belirleyeceğiniz, uygulamanız için kullandığınız kullanıcı arabirimi çerçevesine bağlıdır.

Başlık çubuğunu sıfırlama

Uygulamanız çalışırken sistem başlık çubuğunu sıfırlamak veya geçiş yapmak için AppWindowTitleBar.ResetToDefault'u çağırabilirsiniz.

m_AppWindow.TitleBar.ResetToDefault();

XAML uygulamaları için başlık çubuğunu şu yollarla da sıfırlayabilirsiniz:

  • Uygulamanız çalışırken yeni bir başlık çubuğu öğesine geçmek için SetTitleBar'ı arayın.
  • Varsayılan SetTitleBar sürükleme bölgelerine geri döndürmek için null parametresini kullanarak AppWindowTitleBar'ı arayın.
  • parametresi olarak ile çağrısı null yapın SetTitleBar ve ExtendsContentIntoTitleBar'ıfalse varsayılan sistem başlık çubuğuna geri dönmek için olarak ayarlayın.

Başlık çubuğunu gösterme ve gizleme

Uygulamanıza tam ekran veya kompakt katman modları için destek eklerseniz, uygulamanız bu modlar arasında geçiş yaparken başlık çubuğunuzda değişiklik yapmanız gerekebilir. XAML Penceresi tam ekran modunu desteklemek için herhangi bir API sağlamaz; Bunun için AppWindow API'lerini kullanabilirsiniz.

Uygulamanız tam ekran modunda çalıştığında, sistem başlık çubuğunu ve resim yazısı denetim düğmelerini gizler. AppWindow.Changed olayını işleyebilir ve yeni bir pencere sunusunun yanıtında başlık çubuğunu göstermeniz, gizlemeniz veya değiştirmeniz gerekip gerekmediğini belirlemek için DidPresenterChange özelliğini denetleyebilirsiniz.

Bu örnekte, önceki örneklerden Changed öğesini göstermek ve gizlemek için AppTitleBar olayının nasıl işleneceğini gösterilmektedir. Pencere kompakt katman moduna alınırsa, başlık çubuğu varsayılan sistem başlık çubuğuna sıfırlanır (veya sıkıştırılmış katman için iyileştirilmiş özel bir başlık çubuğu sağlayabilirsiniz).

public MainWindow()
{
    this.InitializeComponent();

    m_AppWindow = this.AppWindow;
    m_AppWindow.Changed += AppWindow_Changed;
}

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    if (args.DidPresenterChange)
    {
        switch (sender.Presenter.Kind)
        {
            case AppWindowPresenterKind.CompactOverlay:
                // Compact overlay - hide custom title bar
                // and use the default system title bar instead.
                AppTitleBar.Visibility = Visibility.Collapsed;
                sender.TitleBar.ResetToDefault();
                break;

            case AppWindowPresenterKind.FullScreen:
                // Full screen - hide the custom title bar
                // and the default system title bar.
                AppTitleBar.Visibility = Visibility.Collapsed;
                sender.TitleBar.ExtendsContentIntoTitleBar = true;
                break;

            case AppWindowPresenterKind.Overlapped:
                // Normal - hide the system title bar
                // and use the custom title bar instead.
                AppTitleBar.Visibility = Visibility.Visible;
                sender.TitleBar.ExtendsContentIntoTitleBar = true;
                break;

            default:
                // Use the default system title bar.
                sender.TitleBar.ResetToDefault();
                break;
        }
    }
}

Note

Tam ekran ve kompakt katman modları yalnızca uygulamanız tarafından destekleniyorsa girilebilir. Daha fazla bilgi için bkz. Uygulama pencerelerini , FullScreenPresenterve CompactOverlayPresenter yönetme.

Yapılması ve yapılmaması gerekenler

  • Pencereniz etkin veya etkin olmadığında bunu belirgin hale getirin. Başlık çubuğunuzdaki metnin, simgelerin ve düğmelerin rengini en azından değiştirin.
  • Uygulama tuvalinin üst kenarı boyunca bir sürükleme bölgesi tanımlayın. Sistem başlık çubuklarının yerleşimini eşleştirmek, kullanıcıların bulmasını kolaylaştırır.
  • Uygulamanın tuvalinde görsel başlık çubuğuyla (varsa) eşleşen bir sürükleme bölgesi tanımlayın.

Tam özelleştirme örneği

Bu örnek, Tam özelleştirme bölümünde açıklanan tüm kodu gösterir.

<Window
    x:Class="WinUI3_CustomTitleBar.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition/>
        </Grid.RowDefinitions>

        <Grid x:Name="AppTitleBar"
      Height="48">
            <Grid.ColumnDefinitions>
                <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
                <ColumnDefinition x:Name="IconColumn" Width="Auto"/>
                <ColumnDefinition x:Name="TitleColumn" Width="Auto"/>
                <ColumnDefinition x:Name="LeftDragColumn" Width="*"/>
                <ColumnDefinition x:Name="SearchColumn" Width="4*" MinWidth="220"/>
                <ColumnDefinition x:Name="RightDragColumn" Width="*" MinWidth="48"/>
                <ColumnDefinition x:Name="AccountColumn" Width="Auto"/>
                <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
            </Grid.ColumnDefinitions>
            <Image x:Name="TitleBarIcon" 
           Source="ms-appx:///Assets/StoreLogo.png"
           Grid.Column="1"
           Width="16" Height="16"
           Margin="8,0,4,0"/>
            <TextBlock x:Name="TitleBarTextBlock"
                       Text="App title" 
                       Style="{StaticResource CaptionTextBlockStyle}"
                       Grid.Column="2"
                       VerticalAlignment="Center">
            </TextBlock>
            <AutoSuggestBox x:Name="TitleBarSearchBox" 
                            Grid.Column="4" 
                            QueryIcon="Find"
                            PlaceholderText="Search"
                            VerticalAlignment="Center"
                            MaxWidth="600"/>
            <PersonPicture x:Name="PersonPic" 
                           Grid.Column="6" 
                           Height="32" Margin="0,0,16,0"/>
        </Grid>

        <NavigationView Grid.Row="1"
                        IsBackButtonVisible="Collapsed"
                        IsSettingsVisible="False">
            <StackPanel>
                <TextBlock Text="Content" 
                           Style="{ThemeResource TitleTextBlockStyle}"
                           Margin="32,0,0,0"/>
                <StackPanel Grid.Row="1" VerticalAlignment="Center">
                    <Button Margin="4" x:Name="CompactoverlaytBtn"
                            Content="Enter CompactOverlay"
                            Click="SwitchPresenter"/>
                    <Button Margin="4" x:Name="FullscreenBtn" 
                            Content="Enter FullScreen"
                            Click="SwitchPresenter"/>
                    <Button Margin="4" x:Name="OverlappedBtn"
                            Content="Revert to default (Overlapped)"
                            Click="SwitchPresenter"/>
                </StackPanel>
            </StackPanel>
        </NavigationView>
    </Grid>
</Window>

using Microsoft.UI.Input;
using Microsoft.UI.Windowing;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml.Media;
using System;
using Windows.ApplicationModel;
using Rect = Windows.Foundation.Rect;

public sealed partial class MainWindow : Window
{
    private AppWindow m_AppWindow;

    public MainWindow()
    {
        this.InitializeComponent();

        // Assumes "this" is a XAML Window. In projects that don't use 
        // WinUI 3 1.3 or later, use interop APIs to get the AppWindow.
        m_AppWindow = this.AppWindow;
        m_AppWindow.Changed += AppWindow_Changed;
        Activated += MainWindow_Activated;
        AppTitleBar.SizeChanged += AppTitleBar_SizeChanged;
        AppTitleBar.Loaded += AppTitleBar_Loaded;

        ExtendsContentIntoTitleBar = true;
        if (ExtendsContentIntoTitleBar == true)
        {
            m_AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Tall;
        }
        TitleBarTextBlock.Text = AppInfo.Current.DisplayInfo.DisplayName;
    }

    private void AppTitleBar_Loaded(object sender, RoutedEventArgs e)
        {
            if (ExtendsContentIntoTitleBar == true)
            {
                // Set the initial interactive regions.
                SetRegionsForCustomTitleBar();
            }
        }

    private void AppTitleBar_SizeChanged(object sender, SizeChangedEventArgs e)
        {
            if (ExtendsContentIntoTitleBar == true)
            {
                // Update interactive regions if the size of the window changes.
                SetRegionsForCustomTitleBar();
            }
        }

    private void SetRegionsForCustomTitleBar()
    {
        // Specify the interactive regions of the title bar.

        double scaleAdjustment = AppTitleBar.XamlRoot.RasterizationScale;

        RightPaddingColumn.Width = new GridLength(m_AppWindow.TitleBar.RightInset / scaleAdjustment);
        LeftPaddingColumn.Width = new GridLength(m_AppWindow.TitleBar.LeftInset / scaleAdjustment);

        // Get the rectangle around the AutoSuggestBox control.
        GeneralTransform transform = TitleBarSearchBox.TransformToVisual(null);
        Rect bounds = transform.TransformBounds(new Rect(0, 0,
                                                         TitleBarSearchBox.ActualWidth,
                                                         TitleBarSearchBox.ActualHeight));
        Windows.Graphics.RectInt32 SearchBoxRect = GetRect(bounds, scaleAdjustment);

        // Get the rectangle around the PersonPicture control.
        transform = PersonPic.TransformToVisual(null);
        bounds = transform.TransformBounds(new Rect(0, 0,
                                                    PersonPic.ActualWidth,
                                                    PersonPic.ActualHeight));
        Windows.Graphics.RectInt32 PersonPicRect = GetRect(bounds, scaleAdjustment);

        var rectArray = new Windows.Graphics.RectInt32[] { SearchBoxRect, PersonPicRect };

        InputNonClientPointerSource nonClientInputSrc =
            InputNonClientPointerSource.GetForWindowId(this.AppWindow.Id);
        nonClientInputSrc.SetRegionRects(NonClientRegionKind.Passthrough, rectArray);
    }

    private Windows.Graphics.RectInt32 GetRect(Rect bounds, double scale)
    {
        return new Windows.Graphics.RectInt32(
            _X: (int)Math.Round(bounds.X * scale),
            _Y: (int)Math.Round(bounds.Y * scale),
            _Width: (int)Math.Round(bounds.Width * scale),
            _Height: (int)Math.Round(bounds.Height * scale)
        );
    }

    private void MainWindow_Activated(object sender, WindowActivatedEventArgs args)
    {
        if (args.WindowActivationState == WindowActivationState.Deactivated)
        {
            TitleBarTextBlock.Foreground =
                (SolidColorBrush)App.Current.Resources["WindowCaptionForegroundDisabled"];
        }
        else
        {
            TitleBarTextBlock.Foreground =
                (SolidColorBrush)App.Current.Resources["WindowCaptionForeground"];
        }
    }

    private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
    {
        if (args.DidPresenterChange)
        {
            switch (sender.Presenter.Kind)
            {
                case AppWindowPresenterKind.CompactOverlay:
                    // Compact overlay - hide custom title bar
                    // and use the default system title bar instead.
                    AppTitleBar.Visibility = Visibility.Collapsed;
                    sender.TitleBar.ResetToDefault();
                    break;

                case AppWindowPresenterKind.FullScreen:
                    // Full screen - hide the custom title bar
                    // and the default system title bar.
                    AppTitleBar.Visibility = Visibility.Collapsed;
                    sender.TitleBar.ExtendsContentIntoTitleBar = true;
                    break;

                case AppWindowPresenterKind.Overlapped:
                    // Normal - hide the system title bar
                    // and use the custom title bar instead.
                    AppTitleBar.Visibility = Visibility.Visible;
                    sender.TitleBar.ExtendsContentIntoTitleBar = true;
                    break;

                default:
                    // Use the default system title bar.
                    sender.TitleBar.ResetToDefault();
                    break;
            }
        }
    }

    private void SwitchPresenter(object sender, RoutedEventArgs e)
    {
        if (AppWindow != null)
        {
            AppWindowPresenterKind newPresenterKind;
            switch ((sender as Button).Name)
            {
                case "CompactoverlaytBtn":
                    newPresenterKind = AppWindowPresenterKind.CompactOverlay;
                    break;

                case "FullscreenBtn":
                    newPresenterKind = AppWindowPresenterKind.FullScreen;
                    break;

                case "OverlappedBtn":
                    newPresenterKind = AppWindowPresenterKind.Overlapped;
                    break;

                default:
                    newPresenterKind = AppWindowPresenterKind.Default;
                    break;
            }

            // If the same presenter button was pressed as the
            // mode we're in, toggle the window back to Default.
            if (newPresenterKind == AppWindow.Presenter.Kind)
            {
                AppWindow.SetPresenter(AppWindowPresenterKind.Default);
            }
            else
            {
                // Else request a presenter of the selected kind
                // to be created and applied to the window.
                AppWindow.SetPresenter(newPresenterKind);
            }
        }
    }
}
  • Last updated on