TouchBehavior

TouchBehavior 是一种 Behavior，提供基于触摸、鼠标单击和悬停事件与任何 VisualElement 交互的功能。 通过 TouchBehavior 实现，可以自定义其附加到的 VisualElement 的许多不同视觉属性，例如 BackgroundColor、Opacity、Rotation 和 Scale，以及许多其他属性。

注意

该工具包还提供了 ImageTouchBehavior 实现，该实现通过提供自定义 Image 元素的 Source 的功能来扩展此 TouchBehavior。

重要

.NET MAUI 社区工具包行为不会设置行为的 BindingContext，因为可以通过样式共享行为，并将其应用于多个控件。 有关详细信息，请参阅 .NET MAUI 行为

语法

以下示例演示如何将 TouchBehavior 添加到父 HorizontalStackLayout，并在用户触摸或点击 HorizontalStackLayout 或其任何子级时执行以下动画：

• 动画持续 250 毫秒
• 应用 CubicInOutEasing
• 将 Opacity 更改为 0.6
• 将 Scale 更改为 0.8

XAML

包括 XAML 命名空间

若要在 XAML 中使用工具包，需要将以下 xmlns 添加到页面或视图中：

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

因此，以下内容：

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

将被修改为包括 xmlns，如下所示：

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

使用 TouchBehavior

<ContentPage 
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
    x:Class="CommunityToolkit.Maui.Sample.Pages.Behaviors.TouchBehaviorPage">

   <HorizontalStackLayout HorizontalOptions="Center" VerticalOptions="Center">
        <HorizontalStackLayout.Behaviors>
            <toolkit:TouchBehavior
                DefaultAnimationDuration="250"
                DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
                PressedOpacity="0.6"
                PressedScale="0.8" />
        </HorizontalStackLayout.Behaviors>

        <ContentView
            HeightRequest="100"
            WidthRequest="10"
            BackgroundColor="Gold" />
        <Label Text="The entire layout receives touches" VerticalOptions="Center" LineBreakMode="TailTruncation"/>
        <ContentView
            HeightRequest="100"
            WidthRequest="10"
            BackgroundColor="Gold" />
    </HorizontalStackLayout>

</ContentPage>

C#

TouchBehavior 可在 C# 中按如下所示方式使用：

class TouchBehaviorPage : ContentPage
{
    public TouchBehaviorPage()
    {
        var firstContent = new ContentView
        {
            HeightRequest = 100,
            WidthRequest = 10,
            BackgroundColor = Colors.Gold
        };

        var label = new Label
        {
            Text = "The entire layout receives touches",
            VerticalOptions = LayoutOptions.Center,
            LineBreakMode = LineBreakMode.TailTruncation
        };

        var secondContent = new ContentView
        {
            HeightRequest = 100,
            WidthRequest = 10,
            BackgroundColor = Colors.Gold
        };

        var layout = new HorizontalStackLayout
        {
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.Center,
            Children = 
            {
                firstContent,
                label,
                secondContent
            }
        }

        var touchBehavior = new TouchBehavior
        {
            DefaultAnimationDuration = 250,
            DefaultAnimationEasing = Easing.CubicInOut,
            PressedOpacity = 0.6,
            PressedScale = 0.8
        };

        layout.Behaviors.Add(touchBehavior);

        Content = layout;
    }
}

C# 标记

我们的 CommunityToolkit.Maui.Markup 包提供一种更简洁的方式来在 C# 中使用此 Behavior。

using CommunityToolkit.Maui.Markup;

class TouchBehaviorPage : ContentPage
{
    public TouchBehaviorPage()
    {
        Content = new HorizontalStackLayout
        {
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.Center,
            Children = 
            {
                new ContentView()
                    .Size(10, 100)
                    .BackgroundColor(Colors.Gold),

                new Label
                {
                    LineBreakMode = LineBreakMode.TailTruncation
                }
                    .Text("The entire layout receives touches"
                    .CenterVertical(),

                new ContentView()
                    .Size(10, 100)
                    .BackgroundColor(Colors.Gold)
            }
        }
            .Behaviors(new TouchBehavior
            {
                DefaultAnimationDuration = 250,
                DefaultAnimationEasing = Easing.CubicInOut,
                PressedOpacity = 0.6,
                PressedScale = 0.8
            });
    }
}

其他示例

处理悬停交互

TouchBehavior 提供了根据鼠标是否悬停在元素上来自定义附加 VisualElement 的属性的功能。

以下示例展示了如何将 TouchBehavior 附加到 HorizontalStackLayout 并更改当用户将鼠标光标悬停在布局和任何子元素上时 HorizontalStackLayout 的 BackgroundColor 和 Scale。

<HorizontalStackLayout
    Padding="20"
    Background="Black"
    HorizontalOptions="Center">
    <HorizontalStackLayout.Behaviors>
        <toolkit:TouchBehavior
            HoveredBackgroundColor="{StaticResource Gray900}"
            HoveredScale="1.2" />
    </HorizontalStackLayout.Behaviors>
</HorizontalStackLayout>

处理长按交互

TouchBehavior 提供了处理用户长按时的情况的能力。 该长按时间段可以由 LongPressDuration 定义，单位为毫秒。

以下示例演示如何将 TouchBehavior 添加到 HorizontalStackLayout、将 LongPressCommand 绑定到后盾视图模型中定义的 IncreaseLongPressCountCommand，并将 LongPressDuration 设置为 750 毫秒。

<HorizontalStackLayout
    Padding="20"
    Background="Black"
    HorizontalOptions="Center"
    x:Name="TouchableHorizontalStackLayout">
    <HorizontalStackLayout.Behaviors>
        <toolkit:TouchBehavior
            BindingContext="{Binding Source={x:Reference Page}, Path=BindingContext, x:DataType=ContentPage}"
            LongPressDuration="750"
            LongPressCommand="{Binding Source={x:Reference Page}, Path=BindingContext.IncreaseLongPressCountCommand, x:DataType=ContentPage}"/>
    </HorizontalStackLayout.Behaviors>
</HorizontalStackLayout>

属性

属性	类型​​	描述
命令	ICommand	获取或设置当用户完成触摸手势时要调用的 ICommand。
CommandParameter	object	获取或设置要传递到 Command 属性的参数。
CurrentHoverState	HoverState	获取或设置行为的当前 HoverState。
CurrentHoverStatus	HoverStatus	获取或设置行为的当前 HoverStatus。
CurrentInteractionStatus	TouchInteractionStatus	获取或设置行为的当前 TouchInteractionStatus。
CurrentTouchState	TouchState	获取或设置行为的当前 TouchState。
CurrentTouchStatus	TouchStatus	获取或设置行为的当前 TouchStatus。
DefaultAnimationDuration	int	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时动画的持续时间。
DefaultAnimationEasing	Easing	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时动画的缓动。
DefaultBackgroundColor	Color	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素的背景色。
DefaultOpacity	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素的不透明度。
DefaultRotation	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素绕 X 轴和 Y 轴的旋转。
DefaultRotationX	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素绕 X 轴的旋转。
DefaultRotationY	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素绕 Y 轴的旋转。
DefaultScale	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素的比例。
DefaultTranslationX	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素的 X 平移。
DefaultTranslationY	double	获取或设置当 CurrentTouchState 属性为 TouchState.Default 时元素的 Y 平移。
DisallowTouchThreshold	int	获取或设置禁止触摸的阈值。
HoveredAnimationDuration	int	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时动画的持续时间。
HoveredAnimationEasing	Easing	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时动画的缓动。
HoveredBackgroundColor	Color	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素的背景色。
HoveredOpacity	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素的不透明度。
HoveredRotation	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素绕 X 轴和 Y 轴的旋转。
HoveredRotationX	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素绕 X 轴的旋转。
HoveredRotationY	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素绕 Y 轴的旋转。
HoveredScale	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素的比例。
HoveredTranslationX	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素的 X 平移。
HoveredTranslationY	double	获取或设置当 CurrentHoverState 属性为 HoverState.Hovered 时元素的 Y 平移。
IsEnabled	bool	获取或设置一个值，该值指示是否已启用行为。
LongPressCommand	ICommand	获取或设置当用户完成长按时要调用的 ICommand。
LongPressCommandParameter	object	获取或设置要传递到 LongPressCommand 属性的参数。
LongPressDuration	int	获取或设置触发长按手势所需的持续时间（以毫秒为单位）。
PressedAnimationDuration	int	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时动画的持续时间。
PressedAnimationEasing	Easing	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时动画的缓动。
PressedBackgroundColor	Color	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素的背景色。
PressedOpacity	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素的不透明度。
PressedRotation	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素绕 X 轴和 Y 轴的旋转。
PressedRotationX	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素绕 X 轴的旋转。
PressedRotationY	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素绕 Y 轴的旋转。
PressedScale	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素的比例。
PressedTranslationX	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素的 X 平移。
PressedTranslationY	double	获取或设置当 CurrentTouchState 属性为 TouchState.Pressed 时元素的 Y 平移。
ShouldMakeChildrenInputTransparent	bool	获取或设置一个值，该值指示元素的子元素是否应设置为输入透明。

事件

事件	说明
CurrentTouchStateChanged	当 CurrentTouchState 更改时触发。
CurrentTouchStatusChanged	当 CurrentTouchStatus 更改时触发。
HoverStateChanged	当 CurrentHoverState 更改时触发。
HoverStatusChanged	当 CurrentHoverStatus 更改时触发。
InteractionStatusChanged	当 CurrentInteractionStatus 更改时触发。
LongPressCompleted	当长按手势完成时触发。
TouchGestureCompleted	当触摸手势完成时触发。

示例

可以在 .NET MAUI 社区工具包示例应用程序中查找此行为的示例。

API

可以在 .NET MAUI 社区工具包 GitHub 存储库查看 TouchBehavior 的源代码

从 Xamarin 社区工具包迁移

在 Xamarin 社区工具包中，有 TouchEffect。如果要将应用从 Xamarin.Forms 升级到 .NET MAUI，则应注意以下几点中断性变更：

1. API 名称更改
2. TouchBehavior 现已实现为 PlatformBehavior

API 名称更改

Xamarin 社区工具包中的名称	MAUI 社区工具包中的名称
TouchEffect	TouchBehavior
NormalBackgroundColor	DefaultBackgroundColor
NormalScale	DefaultScale
NormalOpacity	DefaultOpacity
NormalTranslationX	DefaultTranslationX
NormalTranslationY	DefaultTranslationY
NormalRotation	DefaultRotation
NormalRotationX	DefaultRotationX
NormalRotationY	DefaultRotationY
NormalAnimationDuration	DefaultAnimationDuration
NormalAnimationEasing	DefaultAnimationEasing
NormalBackgroundImageSource	DefaultImageSource（已移动到 ImageTouchBehavior 中）
NormalBackgroundImageAspect	DefaultImageAspect（已移动到 ImageTouchBehavior 中）

TouchBehavior 现已实现为 PlatformBehavior

在 Xamarin 社区工具包中，TouchEffect 已实现为 AttachedEffect。 若要使用该效果，请使用附加属性，并应用于任何 VisualElement

在 .NET MAUI 中，TouchBehavior 已实现为 PlatformBehavior，现在应用于元素行为集合，有关详细信息，请参阅平台行为。

注意：默认情况下，在 .NET MAUI 中，PlatformBehavior 不会设置 BindingContext 属性，这是因为行为可以在样式中共享。 TouchBehavior 会将 BindingContext 属性设置为它要应用到的 VisualElement。 这意味着不应通过样式在元素之间共享 TouchBehavior。

下面是在 Xamarin.Forms 中将 TouchEffect 应用于视图的示例：

XAML

<StackLayout Orientation="Horizontal"
            HorizontalOptions="CenterAndExpand"
            xct:TouchEffect.AnimationDuration="250"
            xct:TouchEffect.AnimationEasing="{x:Static Easing.CubicInOut}"
            xct:TouchEffect.PressedScale="0.8"
            xct:TouchEffect.PressedOpacity="0.6"
            xct:TouchEffect.Command="{Binding Command}">
    <BoxView Color="Gold" />
    <Label Text="The entire layout receives touches" />
    <BoxView Color="Gold"/>
</StackLayout>

C#

var stackLayout = new StackLayout()
{
    HorizontalOptions = LayoutOptions.CenterAndExpand,
    Orientation = StackOrientation.Horizontal,
    Children =
    {
        new BoxView() { Color = Color.Gold, },
        new Label() { Text = "The entire layout receives touches", },
        new BoxView() { Color = Color.Gold, },
    }
};

TouchEffect.SetAnimationDuration(stackLayout, 250);
TouchEffect.SetAnimationEasing(stackLayout, Easing.CubicInOut);
TouchEffect.SetPressedScale(stackLayout, 0.8);
TouchEffect.SetPressedOpacity(stackLayout, 0.6);
TouchEffect.SetCommand(stackLayout, command);

.NET MAUI 中的等效项 TouchBehavior 如下所示：

XAML

<HorizontalStackLayout 
    HorizontalOptions="Center" 
    VerticalOptions="Center"
    x:Name="TouchableHorizontalLayout">
    <HorizontalStackLayout.Behaviors>
        <toolkit:TouchBehavior
            DefaultAnimationDuration="250"
            DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
            PressedOpacity="0.6"
            PressedScale="0.8"
            BindingContext="{Binding Path=BindingContext, Source={x:Reference TouchableHorizontalLayout}, x:DataType=HorizontalStackLayout}"
            Command="{Binding LayoutTappedCommand}" />
    </HorizontalStackLayout.Behaviors>

    <ContentView
        BackgroundColor="Gold"
        HeightRequest="100"
        WidthRequest="10" />
    <Label
        LineBreakMode="TailTruncation"
        Text="The entire layout receives touches"
        VerticalOptions="Center" />
    <ContentView
        BackgroundColor="Gold"
        HeightRequest="100"
        WidthRequest="10" />
</HorizontalStackLayout>

C#

var stackLayout = new HorizontalStackLayout()
{
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center,
    Children =
    {
        new ContentView()
        {
            BackgroundColor = Colors.Gold,
            HeightRequest = 100,
            WidthRequest = 10,
        },
        new Label()
        {
            LineBreakMode = LineBreakMode.TailTruncation,
            Text = "The entire layout receives touches",
            VerticalOptions = LayoutOptions.Center,
        },
        new ContentView()
        {
            BackgroundColor = Colors.Gold,
            HeightRequest = 100,
            WidthRequest = 10,
        },
    },
    Behaviors =
    {
        new TouchBehavior()
        {
            DefaultAnimationDuration = 250,
            DefaultAnimationEasing = Easing.CubicInOut,
            PressedOpacity = 0.6,
            PressedScale = 0.8,
            Command = command,
            BindingContext = this.BindingContext
        }
    }
};