核取方塊

發行項
04/01/2024

核取方塊用於選擇或取消選擇動作項目。它可用於單一項目或使用者可以從中選擇的多個項目的清單。此控制項有三種選擇狀態：未選擇、已選擇和不確定。當子選項集合同時具有未選取和選取狀態時，請使用不確定狀態。

複選框狀態的範例

這是正確的控制項嗎？

使用單一核取方塊進行二元是/否選擇，例如「還記得我嗎？」登入場景或服務條款協議。

用於個別選擇的單一複選框

對於二元選項，核取方塊和切換開關之間的主要差異為核取方塊適用於狀態，而切換開關適用於動作。您可以延遲提交核取方塊互動 (例如，作為表單提交的一部分)，而您應該立即提交切換開關互動。此外，只有核取方塊允許多重選取。

對於多選場景使用多個核取方塊，在該場景中，使用者從一組不互斥的選項中選擇一個或多個項目。

當使用者可以選取任何選項組合時，請建立一組核取方塊。

使用複選框選取多個選項

當選項可以分組時，您可以使用不確定核取方塊來代表整個群組。當使用者選取群組中的某些子專案，但並非全部時，請使用核取方塊的不確定狀態。

用來顯示混合選擇的複選框

核取方塊和圓形按鈕控制項都允許使用者從選項清單中進行選擇。核取方塊允許使用者選擇選項的組合。相比之下，圓形按鈕可讓使用者從互斥的選項中做出單一選擇。當有多個選項但只能選擇一個時，請使用圓形按鈕。

建議

確認核取方塊的用途和目前狀態是清楚的。
將核取方塊文字內容限制為不超過兩行。
將核取方塊標籤標當做複選標記為 true 且沒有複選標記則為 false 的語句。
除非您的品牌指導方針指示您使用其他字型，否則使用預設字型。
如果文字內容是動態的，請考慮控制項將如何調整大小以及它周圍的視覺效果會發生什麼。
如果有兩個以上的互斥選項可供選擇，請考慮使用圓形按鈕。
不要將兩個核取方塊群組放在彼此旁邊。使用群組標籤來分隔群組。
請勿使用複選框作為開啟/關閉控件或執行命令；請改用切換開關。
請勿使用核取方塊來顯示其他控制項，例如對話框。
使用不確定狀態來指示為某些 (但不是全部) 子選項設定了選項。
使用不確定狀態時，使用附屬複選框來顯示哪些選項已選擇，哪些選項未選擇。設計 UI，讓使用者可以看到子選項。
請勿使用不確定狀態來表示第三個狀態。不確定狀態用於指示為某些 (但不是全部) 子選項設定了選項。因此，不允許使用者直接設定不確定的狀態。作為不該做什麼的範例，此核取方塊使用不確定狀態來指示中等辣度：

改用含三個選項的圓形按鈕群組。

UWP 和 WinUI 2

重要

本文中的資訊和範例針對使用 Windows App SDK 和 WinUI 3 的應用程式進行了最佳化，但通常適用於使用 WinUI 2 的 UWP 應用程式。如需平台特定資訊和範例，請參閱 UWP API 參考。

本節包含您在 UWP 或 WinUI 2 應用程式中使用控制項所需的資訊。

此控制項的 API 位在 Windows.UI.Xaml.Controls 命名空間中。

UWP API：CheckBox 類別、Checked 事件、IsChecked 屬性、Content 屬性
開啟 WinUI 2 資源庫應用程式，並查看 CheckBox 運作情形。 WinUI 2 程式庫應用程式包含大部分 WinUI 2 控制項、特性和功能的互動式範例。從 Microsoft Store 取得應用程式，或在 Github 上取得原始程式碼。

建議使用最新的 WinUI 2 來取得所有控制項的最新樣式和範本。 WinUI 2.2 或更新版本包含此使用圓角之控制項的新範本。如需詳細資訊，請參閱圓角半徑。

建立核取方塊

重要 API：CheckBox 類別、Checked 事件、IsChecked 屬性、Content 屬性

開啟 WinUI 3 資源庫應用程式，並查看 CheckBox 運作情形。

WinUI 3 資源庫應用程式包含大多數 WinUI 3 控制項和功能的互動式範例。從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼

建立簡單核取方塊

若要將標籤指派給核取方塊，請設定 Content 屬性。標籤會顯示在核取方塊旁邊。

此 XAML 會建立單一核取方塊，用來在提交表單之前同意服務條款。

<CheckBox x:Name="termsOfServiceCheckBox"
          Content="I agree to the terms of service."/>

以下是在程式代碼中建立的相同核取方塊。

CheckBox termsOfServiceCheckBox = new CheckBox();
termsOfServiceCheckBox.Content = "I agree to the terms of service.";

繫結至 IsChecked

使用 IsChecked 屬性來判斷核取方塊是否已核取或清除。您可以將 IsChecked 屬性的值繫結至另一個二進位值。不過，因為 IsChecked 是可為 null 的布林值，所以您必須使用轉型或值轉換器，才能將其繫結到布林值屬性。這取決於您所使用的實際繫結類型，而您會在下面找到每個可能類型的範例。

在這個範例中，用於同意服務條款之核取方塊的 IsChecked 屬性會繫結到 [提交] 按鈕的 IsEnabled 屬性。只有在同意服務條款時，才會啟用提交按鈕。

使用 x:Bind

注意

我們只顯示相關的程式碼。如需資料繫結的詳細資訊，請參閱資料繫結概觀。具體的 {x:Bind} 資訊 (例如轉換) 在 {x:Bind} 標記擴充中詳細介紹。

<StackPanel Grid.Column="2" Margin="40">
    <CheckBox x:Name="termsOfServiceCheckBox" Content="I agree to the terms of service."/>
    <Button Content="Submit"
            IsEnabled="{x:Bind (x:Boolean)termsOfServiceCheckBox.IsChecked, Mode=OneWay}"/>
</StackPanel>

如果此核取方塊也可以是不確定狀態，我們會使用繫結的 FallbackValue 屬性來指定代表此狀態的布林值。在此情況下，我們也不想啟用 [提交] 按鈕：

<Button Content="Submit"
        IsEnabled="{x:Bind (x:Boolean)termsOfServiceCheckBox.IsChecked, Mode=OneWay, FallbackValue=False}"/>

使用 x:Bind 或 Binding

注意

我們只會在此顯示使用 {x:Bind} 的相關程式碼。在 {Binding} 範例中，我們會將 {x:Bind} 取代為 {Binding}。如需有關資料繫結、值轉換器以及 {x:Bind} 和 {Binding} 標記擴充之間差異的詳細資訊，請參閱資料繫結概觀。

...
<Page.Resources>
    <local:NullableBooleanToBooleanConverter x:Key="NullableBooleanToBooleanConverter"/>
</Page.Resources>

...

<StackPanel Grid.Column="2" Margin="40">
    <CheckBox x:Name="termsOfServiceCheckBox" Content="I agree to the terms of service."/>
    <Button Content="Submit"
            IsEnabled="{x:Bind termsOfServiceCheckBox.IsChecked,
                        Converter={StaticResource NullableBooleanToBooleanConverter}, Mode=OneWay}"/>
</StackPanel>

public class NullableBooleanToBooleanConverter : IValueConverter
{
    public object Convert(object value, Type targetType, object parameter, string language)
    {
        if (value is bool?)
        {
            return (bool)value;
        }
        return false;
    }

    public object ConvertBack(object value, Type targetType, object parameter, string language)
    {
        if (value is bool)
            return (bool)value;
        return false;
    }
}

處理 Click 和 Checked 事件

若要在複選框狀態變更時執行操作，您可以處理 Click 事件或 Checked 和 Unchecked 事件。

Click 事件會在檢查狀態變更時發生。如果您處理 Click 事件，請使用 IsChecked 屬性來判斷核取方塊的狀態。

Checked 和 Unchecked 事件會獨立發生。如果您處理這些事件，您應該同時處理這兩個事件，以回應核取方塊中的狀態變更。

在下列範例中，我們示範處理 Click 事件，以及 Checked 和 Unchecked 事件。

多個核取方塊可以共用相同的事件處理程式。此範例會建立四個核取方塊來選取披薩配料。這四個核取方塊會共用相同的 Click 事件處理程式，以更新選取的配料清單。

<StackPanel Margin="40">
    <TextBlock Text="Pizza Toppings"/>
    <CheckBox Content="Pepperoni" x:Name="pepperoniCheckbox"
              Click="toppingsCheckbox_Click"/>
    <CheckBox Content="Beef" x:Name="beefCheckbox"
              Click="toppingsCheckbox_Click"/>
    <CheckBox Content="Mushrooms" x:Name="mushroomsCheckbox"
              Click="toppingsCheckbox_Click"/>
    <CheckBox Content="Onions" x:Name="onionsCheckbox"
              Click="toppingsCheckbox_Click"/>

    <!-- Display the selected toppings. -->
    <TextBlock Text="Toppings selected:"/>
    <TextBlock x:Name="toppingsList"/>
</StackPanel>

以下是 Click 事件的事件處理程式。每次按下核取方塊時，都會檢查核取方塊，以查看已核取哪些核取方塊，並更新選取的配料清單。

private void toppingsCheckbox_Click(object sender, RoutedEventArgs e)
{
    string selectedToppingsText = string.Empty;
    CheckBox[] checkboxes = new CheckBox[] { pepperoniCheckbox, beefCheckbox,
                                             mushroomsCheckbox, onionsCheckbox };
    foreach (CheckBox c in checkboxes)
    {
        if (c.IsChecked == true)
        {
            if (selectedToppingsText.Length > 1)
            {
                selectedToppingsText += ", ";
            }
            selectedToppingsText += c.Content;
        }
    }
    toppingsList.Text = selectedToppingsText;
}

使用不確定狀態

CheckBox 控制項繼承自 ToggleButton，而且可以有三種狀態：

州/省	屬性	值
checked	IsChecked	true
unchecked	IsChecked	false
indeterminate	IsChecked	null

針對要報告不確定狀態的核取方塊，您必須將 IsThreeState 屬性設為 true。

當選項可以分組時，您可以使用不確定核取方塊來代表整個群組。當使用者選取群組中的某些子專案，但並非全部時，請使用核取方塊的不確定狀態。

在下列範例中，「全選」複選框的 IsThreeState 屬性設定為 true。如果選取所有子元素，則選取「全選」核取方塊；如果未選取所有子元素，則取消選取「全選」核取方塊，否則不確定。

<StackPanel>
    <CheckBox x:Name="OptionsAllCheckBox" Content="Select all" IsThreeState="True"
              Checked="SelectAll_Checked" Unchecked="SelectAll_Unchecked"
              Indeterminate="SelectAll_Indeterminate"/>
    <CheckBox x:Name="Option1CheckBox" Content="Option 1" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked" />
    <CheckBox x:Name="Option2CheckBox" Content="Option 2" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked" IsChecked="True"/>
    <CheckBox x:Name="Option3CheckBox" Content="Option 3" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked" />
</StackPanel>

private void Option_Checked(object sender, RoutedEventArgs e)
{
    SetCheckedState();
}

private void Option_Unchecked(object sender, RoutedEventArgs e)
{
    SetCheckedState();
}

private void SelectAll_Checked(object sender, RoutedEventArgs e)
{
    Option1CheckBox.IsChecked = Option2CheckBox.IsChecked = Option3CheckBox.IsChecked = true;
}

private void SelectAll_Unchecked(object sender, RoutedEventArgs e)
{
    Option1CheckBox.IsChecked = Option2CheckBox.IsChecked = Option3CheckBox.IsChecked = false;
}

private void SelectAll_Indeterminate(object sender, RoutedEventArgs e)
{
    // If the SelectAll box is checked (all options are selected),
    // clicking the box will change it to its indeterminate state.
    // Instead, we want to uncheck all the boxes,
    // so we do this programmatically. The indeterminate state should
    // only be set programmatically, not by the user.

    if (Option1CheckBox.IsChecked == true &&
        Option2CheckBox.IsChecked == true &&
        Option3CheckBox.IsChecked == true)
    {
        // This will cause SelectAll_Unchecked to be executed, so
        // we don't need to uncheck the other boxes here.
        OptionsAllCheckBox.IsChecked = false;
    }
}

private void SetCheckedState()
{
    // Controls are null the first time this is called, so we just
    // need to perform a null check on any one of the controls.
    if (Option1CheckBox != null)
    {
        if (Option1CheckBox.IsChecked == true &&
            Option2CheckBox.IsChecked == true &&
            Option3CheckBox.IsChecked == true)
        {
            OptionsAllCheckBox.IsChecked = true;
        }
        else if (Option1CheckBox.IsChecked == false &&
            Option2CheckBox.IsChecked == false &&
            Option3CheckBox.IsChecked == false)
        {
            OptionsAllCheckBox.IsChecked = false;
        }
        else
        {
            // Set third state (indeterminate) by setting IsChecked to null.
            OptionsAllCheckBox.IsChecked = null;
        }
    }
}

取得範例程式碼

WinUI 資源庫範例 - 以互動式格式查看所有 XAML 控制項。

共用方式為

核取方塊

這是正確的控制項嗎？

建議

UWP 和 WinUI 2

建立核取方塊

建立簡單核取方塊

繫結至 IsChecked

使用 x:Bind

使用 x:Bind 或 Binding

處理 Click 和 Checked 事件

使用不確定狀態

取得範例程式碼

其他資源

共用方式為

核取方塊

這是正確的控制項嗎？

建議

UWP 和 WinUI 2

建立核取方塊

建立簡單核取方塊

繫結至 IsChecked

使用 x:Bind

使用 x:Bind 或 Binding

處理 Click 和 Checked 事件

使用不確定狀態

取得範例程式碼

相關文章

其他資源