觸發程序

  • 發行項

Browse sample. 流覽範例

.NET 多平臺應用程式 UI （.NET MAUI） 觸發程式可讓您以宣告方式在 XAML 中表達動作，以根據事件或資料變更來變更控制項的外觀。 此外，狀態觸發程序是一組特殊化觸發程序，其定義何時應套用 VisualState。

您可以直接將觸發程式指派給控制項的 Triggers 集合，或將其新增至要套用至多個控制項的頁面層級或應用層級資源字典。

屬性觸發程序

Trigger表示當指定的屬性符合指定條件時，套用屬性值或執行動作的觸發程式。

下列範例顯示 Trigger ，會在收到焦點時變更 Entry 背景色彩：

<Entry Placeholder="Enter name">
    <Entry.Triggers>
        <Trigger TargetType="Entry"
                 Property="IsFocused"
                 Value="True">
            <Setter Property="BackgroundColor"
                    Value="Yellow" />
            <!-- Multiple Setter elements are allowed -->
        </Trigger>
    </Entry.Triggers>
</Entry>

觸發程式的宣告會指定下列專案：

  • TargetType - 觸發程式所套用的控制項類型。
  • Property - 受監視之控制項上的 屬性。
  • Value - 值，當它發生于受監視屬性時，導致觸發程式啟動。
  • Setter - 符合觸發條件時所套用的專案 Setter 集合。

此外，也可以指定選擇性 EnterActions 和 ExitActions 集合。 如需詳細資訊，請參閱 EnterActions 和 ExitActions 。

使用樣式套用觸發程式

觸發程序也可以新增至控制項的 Style 宣告、頁面上或應用程式 ResourceDictionary。 下列範例會 宣告頁面上所有 Entry 控制項的隱含 樣式：

<ContentPage.Resources>
    <Style TargetType="Entry">
        <Style.Triggers>
            <Trigger TargetType="Entry"
                     Property="IsFocused"
                     Value="True">
                <Setter Property="BackgroundColor"
                        Value="Yellow" />
                <!-- Multiple Setter elements are allowed -->
            </Trigger>
        </Style.Triggers>
    </Style>
</ContentPage.Resources>

資料觸發程序

DataTrigger表示當系結資料符合指定條件時，套用屬性值或執行動作的觸發程式。 標記 Binding 延伸可用來監視指定的條件。

下列範例顯示 DataTrigger 當 是空的 時，會停用 Button 的 Entry ：

<Entry x:Name="entry"
       Text=""
       Placeholder="Enter text" />
<Button Text="Save">
    <Button.Triggers>
        <DataTrigger TargetType="Button"
                     Binding="{Binding Source={x:Reference entry},
                                       Path=Text.Length}"
                     Value="0">
            <Setter Property="IsEnabled"
                    Value="False" />
            <!-- Multiple Setter elements are allowed -->
        </DataTrigger>
    </Button.Triggers>
</Button>

在此範例中，當 的 Entry 長度為零時，就會啟動觸發程式。

提示

評估 Path=Text.Length 時一律會提供目標屬性的預設值 （例如 Text="" ），否則會是 null ，而且觸發程式無法如您所預期般運作。

此外，也可以指定選擇性 EnterActions 和 ExitActions 集合。 如需詳細資訊，請參閱 EnterActions 和 ExitActions 。

事件觸發程式

EventTrigger表示套用一組動作以回應事件的觸發程式。 不同于 Trigger ， EventTrigger 沒有終止狀態的概念，因此一旦引發事件的條件不再成立，動作就不會復原。

EventTrigger只需要 Event 設定 屬性：

<EventTrigger Event="TextChanged">
    <local:NumericValidationTriggerAction />
</EventTrigger>

在此範例中，沒有任何 Setter 元素。 相反地，有 物件 NumericalValidationTriggerAction 。

注意

事件觸發程式不支援 EnterActions 和 ExitActions 。

觸發程式動作實作必須：

  • 實作泛型 TriggerAction<T> 類別，且泛型參數對應觸發程序將套用至的控制項類型。 您可以使用這類 VisualElement 類別來撰寫使用各種控制項的觸發程式動作，或指定類似 的 Entry 控制項類型。
  • 覆寫 Invoke 方法。 每當觸發程式事件發生時，就會呼叫這個方法。
  • 選擇性地公開可在 XAML 中宣告觸發程式時設定的屬性。

下列範例顯示 類別 NumericValidationTriggerAction ：

public class NumericValidationTriggerAction : TriggerAction<Entry>
{
    protected override void Invoke(Entry entry)
    {
        double result;
        bool isValid = Double.TryParse(entry.Text, out result);
        entry.TextColor = isValid ? Colors.Black : Colors.Red;
    }
}

警告

在 中 ResourceDictionary 共用觸發程式時請小心。 一個實例將會在控制項之間共用，因此任何設定一次的狀態都會套用至所有實例。

多觸發程式

MultiTrigger表示當符合一組條件時，套用屬性值或執行動作的觸發程式。 套用物件之前 Setter ，所有條件都必須為 true。

下列範例顯示系結至兩個 MultiTriggerEntry 物件的 ：

<Entry x:Name="email"
       Text="" />
<Entry x:Name="phone"
       Text="" />
<Button Text="Save">
    <Button.Triggers>
        <MultiTrigger TargetType="Button">
            <MultiTrigger.Conditions>
                <BindingCondition Binding="{Binding Source={x:Reference email},
                                            Path=Text.Length}"
                                  Value="0" />
                <BindingCondition Binding="{Binding Source={x:Reference phone},
                                            Path=Text.Length}"
                                  Value="0" />
            </MultiTrigger.Conditions>
            <Setter Property="IsEnabled" Value="False" />
            <!-- multiple Setter elements are allowed -->
        </MultiTrigger>
    </Button.Triggers>
</Button>

此外， MultiTrigger.Conditions 集合也可以包含 PropertyCondition 物件：

<PropertyCondition Property="Text"
                   Value="OK" />

EnterActions 和 ExitActions

觸發程式發生時實作變更的替代方法是指定 EnterActions 和 ExitActions 集合，以及建立 TriggerAction<T> 實作。

型 IList<TriggerAction> 別 為 的 EnterActions 集合會定義符合觸發條件時要叫用的集合。 型 IList<TriggerAction> 別 為 的 ExitActions 集合會定義在不再符合觸發條件之後叫用的集合。

注意

EventTrigger 類別會忽略 EnterActions 和 ExitActions 集合中定義的 TriggerAction 物件。

下列範例顯示指定 和 ExitAction 的屬性觸發程式 EnterAction ：

<Entry Placeholder="Enter job title">
    <Entry.Triggers>
        <Trigger TargetType="Entry"
                 Property="Entry.IsFocused"
                 Value="True">
            <Trigger.EnterActions>
                <local:FadeTriggerAction StartsFrom="0" />
            </Trigger.EnterActions>

            <Trigger.ExitActions>
                <local:FadeTriggerAction StartsFrom="1" />
            </Trigger.ExitActions>
        </Trigger>
    </Entry.Triggers>
</Entry>

觸發程式動作實作必須：

  • 實作泛型 TriggerAction<T> 類別，且泛型參數對應觸發程序將套用至的控制項類型。 您可以使用這類 VisualElement 類別來撰寫使用各種控制項的觸發程式動作，或指定類似 的 Entry 控制項類型。
  • 覆寫 Invoke 方法。 每當觸發程式事件發生時，就會呼叫這個方法。
  • 選擇性地公開可在 XAML 中宣告觸發程式時設定的屬性。

下列範例顯示 類別 FadeTriggerAction ：

public class FadeTriggerAction : TriggerAction<VisualElement>
{
    public int StartsFrom { get; set; }

    protected override void Invoke(VisualElement sender)
    {
        sender.Animate("FadeTriggerAction", new Animation((d) =>
        {
            var val = StartsFrom == 1 ? d : 1 - d;
            sender.BackgroundColor = Color.FromRgb(1, val, 1);
        }),
        length: 1000, // milliseconds
        easing: Easing.Linear);
    }
}

注意

您可以提供 EnterActions 和 以及 ExitActionsSetter 觸發程式中的物件，但請注意， Setter 系統會立即呼叫物件（它們不會等待 EnterAction 或 ExitAction 完成）。

狀態觸發程序

狀態觸發程式是一組特殊的觸發程式，可定義應套用 的條件 VisualState 。

狀態觸發程序會新增至 VisualState 的 StateTriggers 集合。 此集合可以包含單一狀態觸發程序或多個狀態觸發程序。 當集合中的任何狀態觸發程序為作用中時，將會套用 VisualState。

使用狀態觸發程式來控制視覺狀態時，.NET MAUI 會使用下列優先順序規則來判斷哪一個觸發程式 （以及對應的 VisualState ） 為作用中：

  1. 衍生自 StateTriggerBase 的任何觸發程序。
  2. 因為符合 MinWindowWidth 條件，所以已啟用 AdaptiveTrigger。
  3. 因為符合 MinWindowHeight 條件，所以已啟用 AdaptiveTrigger。

如果多個觸發程序同時處於作用中狀態 (例如，兩個自訂觸發程序)，則會優先使用標記中宣告的第一個觸發程序。

注意

狀態觸發程序可以在 Style 中設定，或直接在元素上設定。

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

狀態觸發程序

衍生自 StateTriggerBase 類別的 StateTrigger 類別具有 IsActive 可繫結屬性。 當 IsActive 屬性變更值時，StateTrigger 會觸發 VisualState 變更。

StateTriggerBase 類別 (所有狀態觸發程序的基底類別) 具有 IsActive 屬性與 IsActiveChanged 事件。 每當發生 VisualState 變更時，就會引發此事件。 此外，類別 StateTriggerBase 具有可 OnAttached 覆寫的 和 OnDetached 方法。

重要

StateTrigger.IsActive 可繫結屬性會隱藏繼承的 StateTriggerBase.IsActive 屬性。

下列 XAML 範例顯示包含 StateTrigger 物件的 Style：

<Style TargetType="Grid">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Checked">
                    <VisualState.StateTriggers>
                        <StateTrigger IsActive="{Binding IsToggled}"
                                      IsActiveChanged="OnCheckedStateIsActiveChanged" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Black" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Unchecked">
                    <VisualState.StateTriggers>
                        <StateTrigger IsActive="{Binding IsToggled, Converter={StaticResource inverseBooleanConverter}}"
                                      IsActiveChanged="OnUncheckedStateIsActiveChanged" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="White" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

在此範例中，隱含的 Style 以 Grid 物件為目標。 當繫結物件的 IsToggled 屬性為 true 時，Grid 的背景色彩會設定為黑色。 當繫結物件的 IsToggled 屬性變成 false 時，就會觸發 VisualState 變更，而且 Grid 的背景色彩會變成白色。

此外，每次 VisualState 發生變更時， IsActiveChanged 都會引發 的 VisualState 事件。 每個 VisualState 都會註冊此事件的事件處理常式：

void OnCheckedStateIsActiveChanged(object sender, EventArgs e)
{
    StateTriggerBase stateTrigger = sender as StateTriggerBase;
    Console.WriteLine($"Checked state active: {stateTrigger.IsActive}");
}

void OnUncheckedStateIsActiveChanged(object sender, EventArgs e)
{
    StateTriggerBase stateTrigger = sender as StateTriggerBase;
    Console.WriteLine($"Unchecked state active: {stateTrigger.IsActive}");
}

在此範例中，當引發 事件的處理常式 IsActiveChanged 時，處理常式會輸出 是否 VisualState 為使用中。 例如，從 Checked 視覺效果狀態變更為 Unchecked 視覺效果狀態時，下列訊息會輸出至主控台視窗：

Checked state active: False
Unchecked state active: True

注意

自訂狀態觸發程式可以藉由衍生自 StateTriggerBase 類別來建立，並覆寫 OnAttached 和 OnDetached 方法來執行任何必要的註冊和清除。

調適型觸發程序

當視窗具有指定的高度或寬度時，AdaptiveTrigger 會觸發 VisualState 變更。 此觸發程序有兩個可繫結的屬性：

注意

AdaptiveTrigger 衍生自 StateTriggerBase 類別，因此可將事件處理常式附加至 IsActiveChanged 事件。

下列 XAML 範例顯示包含 AdaptiveTrigger 物件的 Style：

<Style TargetType="StackLayout">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Vertical">
                    <VisualState.StateTriggers>
                        <AdaptiveTrigger MinWindowWidth="0" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="Orientation"
                                Value="Vertical" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Horizontal">
                    <VisualState.StateTriggers>
                        <AdaptiveTrigger MinWindowWidth="800" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="Orientation"
                                Value="Horizontal" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

在此範例中，隱含的 Style 以 StackLayout 物件為目標。 當視窗寬度介於 0 到 800 裝置獨立單位之間時，套用 Style 的 StackLayout 物件將會有垂直方向。 當視窗寬度為 > = 800 個裝置獨立單位時，就會 VisualState 觸發變更，而方向會 StackLayout 變更為水準。

MinWindowHeight 與 MinWindowWidth 屬性可以單獨使用，也可以相互結合使用。 下列 XAML 顯示設定這兩個屬性的範例：

<AdaptiveTrigger MinWindowWidth="800"
                 MinWindowHeight="1200"/>

在此範例中， AdaptiveTrigger 表示當目前的視窗寬度為 > = 800 個裝置獨立單位，而目前的視窗高度 > 為 = 1200 個裝置獨立單位時，就會套用對應的 VisualState 。

比較狀態觸發程序

CompareStateTrigger 會在屬性等於特定值時，觸發 VisualState 變更。 此觸發程序有兩個可繫結的屬性：

  • Property (object 型別)，指出將由觸發程序比較的屬性。
  • Value (object 型別)，指出應套用 VisualState 的值。

注意

CompareStateTrigger 衍生自 StateTriggerBase 類別，因此可將事件處理常式附加至 IsActiveChanged 事件。

下列 XAML 範例顯示包含 CompareStateTrigger 物件的 Style：

<Style TargetType="Grid">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Checked">
                    <VisualState.StateTriggers>
                        <CompareStateTrigger Property="{Binding Source={x:Reference checkBox}, Path=IsChecked}"
                                             Value="True" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Black" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Unchecked">
                    <VisualState.StateTriggers>
                        <CompareStateTrigger Property="{Binding Source={x:Reference checkBox}, Path=IsChecked}"
                                             Value="False" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="White" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>
...
<Grid>
    <Frame BackgroundColor="White"
           CornerRadius="12"
           Margin="24"
           HorizontalOptions="Center"
           VerticalOptions="Center">
        <StackLayout Orientation="Horizontal">
            <CheckBox x:Name="checkBox"
                      VerticalOptions="Center" />
            <Label Text="Check the CheckBox to modify the Grid background color."
                   VerticalOptions="Center" />
        </StackLayout>
    </Frame>
</Grid>

在此範例中，隱含的 Style 以 Grid 物件為目標。 當 CheckBox 的 IsChecked 屬性為 false 時，Grid 的背景色彩會設定為白色。 CheckBox.IsChecked當 屬性變成 true 時， VisualState 就會觸發變更，而 的背景色彩 Grid 會變成黑色。

裝置狀態觸發程序

DeviceStateTrigger 會根據應用程式執行所在的裝置平台，觸發 VisualState 變更。 此觸發程序具有單一可繫結屬性：

注意

DeviceStateTrigger 衍生自 StateTriggerBase 類別，因此可將事件處理常式附加至 IsActiveChanged 事件。

下列 XAML 範例顯示包含 DeviceStateTrigger 物件的 Style：

<Style x:Key="DeviceStateTriggerPageStyle"
       TargetType="ContentPage">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="iOS">
                    <VisualState.StateTriggers>
                        <DeviceStateTrigger Device="iOS" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Silver" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Android">
                    <VisualState.StateTriggers>
                        <DeviceStateTrigger Device="Android" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="#2196F3" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

在此範例中，明確的 Style 以 ContentPage 物件為目標。 ContentPage 使用樣式的物件會將其背景色彩設定為 iOS 上的銀色，並在 Android 上設定為淡藍色。

方向狀態觸發程序

當裝置的方向變更時，OrientationStateTrigger 會觸發 VisualState 變更。 此觸發程序具有單一可繫結屬性：

注意

OrientationStateTrigger 衍生自 StateTriggerBase 類別，因此可將事件處理常式附加至 IsActiveChanged 事件。

下列 XAML 範例顯示包含 OrientationStateTrigger 物件的 Style：

<Style x:Key="OrientationStateTriggerPageStyle"
       TargetType="ContentPage">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Portrait">
                    <VisualState.StateTriggers>
                        <OrientationStateTrigger Orientation="Portrait" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Silver" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Landscape">
                    <VisualState.StateTriggers>
                        <OrientationStateTrigger Orientation="Landscape" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="White" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

在此範例中，明確的 Style 以 ContentPage 物件為目標。 取用樣式的 ContentPage 物件，會在方向為直向時將其背景色彩設定為銀色，並在方向為橫向時將其背景色彩設定為白色。