共用方式為


核取方塊

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

複選框狀態的範例

這是正確的控制項嗎?

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

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

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

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

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

使用複選框選取多個選項

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

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

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

建議

  • 確認核取方塊的用途和目前狀態是清楚的。

  • 將核取方塊文字內容限制為不超過兩行。

  • 將核取方塊標籤標當做複選標記為 true 且沒有複選標記則為 false 的語句。

  • 除非您的品牌指導方針指示您使用其他字型,否則使用預設字型。

  • 如果文字內容是動態的,請考慮控制項將如何調整大小以及它周圍的視覺效果會發生什麼。

  • 如果有兩個以上的互斥選項可供選擇,請考慮使用圓形按鈕

  • 不要將兩個核取方塊群組放在彼此旁邊。 使用群組標籤來分隔群組。

  • 請勿使用複選框作為開啟/關閉控件或執行命令;請改用切換開關

  • 請勿使用核取方塊來顯示其他控制項,例如對話框。

  • 使用不確定狀態來指示為某些 (但不是全部) 子選項設定了選項。

  • 使用不確定狀態時,使用附屬複選框來顯示哪些選項已選擇,哪些選項未選擇。 設計 UI,讓使用者可以看到子選項。

  • 請勿使用不確定狀態來表示第三個狀態。 不確定狀態用於指示為某些 (但不是全部) 子選項設定了選項。 因此,不允許使用者直接設定不確定的狀態。 作為不該做什麼的範例,此核取方塊使用不確定狀態來指示中等辣度:

    不確定複選框

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

    具有三個選項的單選按鈕群組:不辣、辣和額外辣

UWP 和 WinUI 2

重要

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

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

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

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

建立核取方塊

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 事件或 CheckedUnchecked 事件。

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

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

在下列範例中,我們示範處理 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;
        }
    }
}

取得範例程式碼