Button

發行項
10/29/2024

.NET 多平臺應用程式 UI （.NET MAUI） Button 會顯示文字，並回應點選或按兩下以指示應用程式執行工作。 Button通常會顯示簡短的文字字串，指出命令，但它也可以顯示位圖影像，或文字和影像的組合。 Button當按下手指或按兩下滑鼠時，就會起始該命令。

Button 會定義下列屬性：

BorderColor型 Color別為的，描述按鈕的框線色彩。
BorderWidth型 double別為的，會定義按鈕框線的寬度。
CharacterSpacing型 double別為的，定義按鈕文字字元之間的間距。
Command型 ICommand別為的，定義點選按鈕時所執行的命令。
CommandParameter型 object別為的，是傳遞至 Command的參數。
ContentLayout型 ButtonContentLayout別為的物件，會定義物件，控制按鈕影像的位置，以及按鈕影像與文字之間的間距。
CornerRadius類型 int為的，描述按鈕框線的圓角半徑。
FontAttributes型 FontAttributes別為的，會決定文字樣式。
FontAutoScalingEnabled型 bool別為的，定義按鈕文字是否會反映操作系統中設定的縮放喜好設定。此屬性的預設值為 true。
FontFamily型 string別為的，會定義字型系列。
FontSize型 double別為的，會定義字型大小。
ImageSource型 ImageSource別為的點陣圖影像，指定要顯示為按鈕內容的點陣圖影像。
LineBreakMode型 LineBreakMode別為的，決定當文字不能放入一行時，應該如何處理文字。
Padding型 Thickness別為的，會決定按鈕的邊框間距。
Text類型 string為的，會定義顯示為按鈕內容的文字。
TextColor類型 Color為的，描述按鈕文字的色彩。
TextTransform型 TextTransform別為的，定義按鈕文字的大小寫。

這些屬性是由 BindableProperty 物件所支援，這表示這些屬性可以是數據系結的目標，並設定樣式。

注意

雖然 Button 定義 ImageSource 屬性，但可讓您在上 Button顯示影像，這個屬性是用於在文字旁 Button 顯示小型圖示時使用。

此外， Button 定義 Clicked、 Pressed和 Released 事件。 Clicked當點選與手指或滑鼠指標從按鈕表面放開時Button，就會引發事件。 Pressed當手指按下時Button，會引發事件，或按下滑鼠按鈕，且指標位於上方Button。 Released放開手指或滑鼠按鈕時，就會引發事件。一般而言， Clicked 事件也會與 Released 事件同時引發，但如果手指或滑鼠指標在放開之前會離開表面 Button ， Clicked 則可能不會發生此事件。

重要

Button必須IsEnabled將其屬性設定為 true ，才能回應點選。

建立按鈕

若要建立按鈕，請建立 Button 對象並處理其 Clicked 事件。

下列 XAML 範例示範如何建立 Button：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ButtonDemos.BasicButtonClickPage"
             Title="Basic Button Click">
    <StackLayout>
        <Button Text="Click to Rotate Text!"
                VerticalOptions="Center"
                HorizontalOptions="Center"
                Clicked="OnButtonClicked" />
        <Label x:Name="label"
               Text="Click the Button above"
               FontSize="18"
               VerticalOptions="Center"
               HorizontalOptions="Center" />
    </StackLayout>
</ContentPage>

Text 屬性可指定出現在 Button 中的文字。事件 Clicked 會設定為名為的 OnButtonClicked事件處理程式。此處理程式位於程式代碼後置檔案中：

public partial class BasicButtonClickPage : ContentPage
{
    public BasicButtonClickPage ()
    {
        InitializeComponent ();
    }

    async void OnButtonClicked(object sender, EventArgs args)
    {
        await label.RelRotateTo(360, 1000);
    }
}

在此範例中，點選時 Button ，會 OnButtonClicked 執行方法。自 sender 變數是 Button 負責此事件的物件。您可以使用這個來存取Button物件，或區分共用相同Clicked事件的多個Button物件。處理程式會 Clicked 呼叫動畫函式，以 1000 毫秒旋轉 Label 360 度：

要建立的 Button 對等 C# 程式代碼為：

Button button = new Button
{
    Text = "Click to Rotate Text!",
    VerticalOptions = LayoutOptions.Center,
    HorizontalOptions = LayoutOptions.Center
};
button.Clicked += async (sender, args) => await label.RelRotateTo(360, 1000);

使用命令介面

應用程式可以回應 Button 點選，而不需要處理 Clicked 事件。會 Button 實作稱為命令或 命令介面的 替代通知機制。這包含兩個屬性：

Command 型 ICommand別為，這是命名空間中 System.Windows.Input 定義的介面。
CommandParameter 類型的 Object屬性。

此方法特別適用於與數據系結的連線，特別是在實作 Model-View-ViewModel （MVVM）模式時。在MVVM應用程式中，viewmodel 會定義類型 ICommand 的屬性，然後以數據系結連接到 Button 物件。 .NET MAUI 也會定義 Command 和 Command<T> 類別，以實 ICommand 作介面，並協助 viewmodel 定義型別 ICommand的屬性。如需命令的詳細資訊，請參閱命令。

下列範例示範一個非常簡單的 viewmodel 類別，其定義名為類型的 double 屬性，以及名為 NumberMultiplyBy2Command 和 DivideBy2Command類型的ICommand兩個屬性：

public class CommandDemoViewModel : INotifyPropertyChanged
{
    double number = 1;

    public event PropertyChangedEventHandler PropertyChanged;

    public ICommand MultiplyBy2Command { get; private set; }
    public ICommand DivideBy2Command { get; private set; }

    public CommandDemoViewModel()
    {
        MultiplyBy2Command = new Command(() => Number *= 2);
        DivideBy2Command = new Command(() => Number /= 2);
    }

    public double Number
    {
        get
        {
            return number;
        }
        set
        {
            if (number != value)
            {
                number = value;
                PropertyChanged?.Invoke(this, new PropertyChangedEventArgs("Number"));
            }
        }
    }
}

在此範例中，這兩 ICommand 個屬性會在類別的建構函式中初始化，並具有類型 Command為的兩個物件。建 Command 構函式包含一個小函式（稱為建 execute 構函式自變數），可將屬性的值 Number 加倍或減半。

下列 XAML 範例會取用類別 CommandDemoViewModel ：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:ButtonDemos"
             x:Class="ButtonDemos.BasicButtonCommandPage"
             Title="Basic Button Command">
    <ContentPage.BindingContext>
        <local:CommandDemoViewModel />
    </ContentPage.BindingContext>

    <StackLayout>
        <Label Text="{Binding Number, StringFormat='Value is now {0}'}"
               FontSize="18"
               VerticalOptions="Center"
               HorizontalOptions="Center" />
        <Button Text="Multiply by 2"
                VerticalOptions="Center"
                HorizontalOptions="Center"
                Command="{Binding MultiplyBy2Command}" />
        <Button Text="Divide by 2"
                VerticalOptions="Center"
                HorizontalOptions="Center"
                Command="{Binding DivideBy2Command}" />
    </StackLayout>
</ContentPage>

在此範例中 Label ，元素和兩個 Button 物件包含類別中三個屬性的 CommandDemoViewModel 系結。當兩個 Button 物件被點選時，會執行命令，而數位會變更值。此方法優於 Clicked 處理程式的優點是，與此頁面功能相關的所有邏輯都位於 viewmodel 中，而不是程式碼後置檔案中，因此能更好地區分使用者介面與商業規則。

物件也可以 Command 控制對象的啟用和停用 Button 。例如，假設您想要限制介於 2^{10 到 2^–10} 之間的數位值範圍。您可以將另一個函式新增至建構函式（稱為 canExecute 自變數），以在應該啟用時Button傳回true：

public class CommandDemoViewModel : INotifyPropertyChanged
{
    ···
    public CommandDemoViewModel()
    {
        MultiplyBy2Command = new Command(
            execute: () =>
            {
                Number *= 2;
                ((Command)MultiplyBy2Command).ChangeCanExecute();
                ((Command)DivideBy2Command).ChangeCanExecute();
            },
            canExecute: () => Number < Math.Pow(2, 10));

        DivideBy2Command = new Command(
            execute: () =>
            {
                Number /= 2;
                ((Command)MultiplyBy2Command).ChangeCanExecute();
                ((Command)DivideBy2Command).ChangeCanExecute();
            },
            canExecute: () => Number > Math.Pow(2, -10));
    }
    ···
}

在這裡範例中，需要對方法Command的ChangeCanExecute呼叫，讓 Command 方法可以呼叫 canExecute 方法，並判斷是否Button應該停用。隨著此程式碼變更，當數字達到限制時， Button 會停用。

您也可以將兩個或多個 Button 元素系結至相同的 ICommand 屬性。元素Button可以使用的Button屬性來區別CommandParameter。在此情況下，您會想要使用泛型 Command<T> 類別。然後，物件 CommandParameter 會當做自變數傳遞至 execute 和 canExecute 方法。如需詳細資訊，請參閱命令。

按下並放開按鈕

Pressed當手指按下時Button，會引發事件，或按下滑鼠按鈕，且指標位於上方Button。 Released放開手指或滑鼠按鈕時，就會引發事件。一般而言， Clicked 事件也會與 Released 事件同時引發，但如果手指或滑鼠指標在放開之前會離開表面 Button ， Clicked 則可能不會發生此事件。

下列 XAML 範例顯示 Label 和，以及 Button 附加與事件的處理程式PressedReleased：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ButtonDemos.PressAndReleaseButtonPage"
             Title="Press and Release Button">
    <StackLayout>
        <Button Text="Press to Rotate Text!"
                VerticalOptions="Center"
                HorizontalOptions="Center"
                Pressed="OnButtonPressed"
                Released="OnButtonReleased" />
        <Label x:Name="label"
               Text="Press and hold the Button above"
               FontSize="18"
               VerticalOptions="Center"
               HorizontalOptions="Center" />
    </StackLayout>
</ContentPage>

程序代碼後置檔案會在 Label 事件發生時 Pressed 產生動畫效果，但在事件發生時 Released 暫停輪替：

public partial class PressAndReleaseButtonPage : ContentPage
{
    IDispatcherTimer timer;
    Stopwatch stopwatch = new Stopwatch();

    public PressAndReleaseButtonPage()
    {
        InitializeComponent();

        timer = Dispatcher.CreateTimer();
        timer.Interval = TimeSpan.FromMilliseconds(16);
        timer.Tick += (s, e) =>
        {
            label.Rotation = 360 * (stopwatch.Elapsed.TotalSeconds % 1);
        };
    }

    void OnButtonPressed(object sender, EventArgs args)
    {
        stopwatch.Start();
        timer.Start();
    }

    void OnButtonReleased(object sender, EventArgs args)
    {
        stopwatch.Stop();
        timer.Stop();
    }
}

結果是 Label ，當手指與 Button接觸時，唯一會旋轉，並在手指釋放時停止。

按鈕視覺狀態

ButtonPressed VisualState具有，可在按下時起始視覺效果變更Button，前提是已啟用。

下列 XAML 範例示範如何定義狀態的 Pressed 視覺狀態：

<Button Text="Click me!"
        ...>
    <VisualStateManager.VisualStateGroups>
        <VisualStateGroupList>
            <VisualStateGroup x:Name="CommonStates">
                <VisualState x:Name="Normal">
                    <VisualState.Setters>
                        <Setter Property="Scale"
                                Value="1" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Pressed">
                    <VisualState.Setters>
                        <Setter Property="Scale"
                                Value="0.8" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="PointerOver" />            
            </VisualStateGroup>
        </VisualStateGroupList>
    </VisualStateManager.VisualStateGroups>
</Button>

在此範例中，會PressedVisualState指定按下時Button，其 Scale 屬性會從預設值 1 變更為 0.8。 Normal VisualState指定當處於正常狀態時Button，其 Scale 屬性會設定為 1。因此，整體效果是按下時 Button ，會重新調整為稍微小一點，而釋放時 Button ，它會重新調整為其預設大小。

重要

Button若要讓返回其Normal狀態，VisualStateGroup也必須定義PointerOver狀態。如果您使用 .NET MAUI 應用程式項目範本所建立的樣式ResourceDictionary，則您已經有定義狀態的PointerOver隱含Button樣式。

如需視覺狀態的詳細資訊，請參閱視覺狀態。

搭配按鈕使用位圖

類別 Button 會 ImageSource 定義屬性，可讓您單獨或結合文字，在上 Button顯示小型位圖影像。您也可以指定文字和影像的排列方式。屬性 ImageSource 的類型為 ImageSource，這表示位圖可以從檔案、內嵌資源、URI 或數據流載入。

點陣圖不會縮放以符合 Button。最佳大小通常介於 32 到 64 個裝置獨立單位之間，視您想要點陣圖的大小而定。

您可以使用的屬性，Text指定在上ButtonContentLayout排列和 ImageSource 屬性Button的方式。這個屬性的類型為 ButtonContentLayout，而且其建構函式有兩個自變數：

列舉的成員 ImagePosition ： Left、 Top、 Right或，表示 Bottom 位圖相對於文字的顯示方式。
double位圖與文字之間的間距值。

在 XAML 中，您可以只指定列舉成員或間距，或以逗號分隔的任何順序來建立 Button 和設定 ContentLayout 屬性：

<Button Text="Button text"
        ImageSource="button.png"
        ContentLayout="Right, 20" />

對等的 C# 程式碼為：

Button button = new Button
{
    Text = "Button text",
    ImageSource = new FileImageSource
    {
        File = "button.png"
    },
    ContentLayout = new Button.ButtonContentLayout(Button.ButtonContentLayout.ImagePosition.Right, 20)
};

注意

Button如果包含文字和影像，則可能無法在按鈕內容納所有內容，因此您應該手動調整影像的大小，以達到您想要的配置。

停用按鈕

有時候應用程式會進入按兩下不是有效作業的狀態 Button 。在這種情況下， Button 可以藉由將其 IsEnabled 屬性設定為 false來停用。

共用方式為