识别平移手势

项目
05/14/2024

.NET Multi-platform App UI (.NET MAUI) 平移手势识别器可检测屏幕周围的手指移动，并可用于将该移动应用于内容。平移手势的常见使用场景是水平和垂直平移图像，以便在小于图像尺寸的视区中显示图像内容时，可以查看所有图像内容。这可通过在视区内移动图像来完成。

在 .NET MAUI 中，平移手势识别由 PanGestureRecognizer 类提供。此类定义 TouchPoints 属性，类型为 int，表示手势中的触摸点数。此属性的默认值为 1。此属性由 BindableProperty 对象提供支持，这意味着它可以作为数据绑定的目标，并进行样式设置。

PanGestureRecognizer 类还定义了在检测到的平移手势发生更改时引发的 PanUpdated 事件。此事件附带的 PanUpdatedEventArgs 对象定义以下属性：

GestureId，类型为 int，表示引发事件的手势的 ID。
StatusType，类型为 GestureStatus，指示是否已为新启动的手势、正在运行的手势、已完成的手势或已取消的手势引发事件。
TotalX，类型为 double，指示手势开始后 X 方向上的总体变化。
TotalY，类型为 double，指示手势开始后 Y 方向上的总体变化。

创建 PanGestureRecognizer

若要使 View 识别平移手势，请创建一个 PanGestureRecognizer 对象，处理 PanUpdated 事件，并将新的手势识别器添加到视图上的 GestureRecognizers 集合。下面的代码示例展示了附加到 Image 上的 PanGestureRecognizer：

<Image Source="monkey.jpg">
    <Image.GestureRecognizers>
        <PanGestureRecognizer PanUpdated="OnPanUpdated" />
    </Image.GestureRecognizers>
</Image>

OnPanUpdated 事件处理程序的代码应添加到代码隐藏文件中：

void OnPanUpdated(object sender, PanUpdatedEventArgs e)
{
    // Handle the pan
}

等效 C# 代码如下：

PanGestureRecognizer panGesture = new PanGestureRecognizer();
panGesture.PanUpdated += (s, e) =>
{
    // Handle the pan
};
image.GestureRecognizers.Add(panGesture);

创建平移容器

任意形式的平移通常适用于在图像或地图内导航。以下示例所示的 PanContainer 类是执行任意形式的平移的通用帮助程序类：

public class PanContainer : ContentView
{
    double panX, panY;

    public PanContainer()
    {
        // Set PanGestureRecognizer.TouchPoints to control the
        // number of touch points needed to pan
        PanGestureRecognizer panGesture = new PanGestureRecognizer();
        panGesture.PanUpdated += OnPanUpdated;
        GestureRecognizers.Add(panGesture);
    }

    void OnPanUpdated(object sender, PanUpdatedEventArgs e)
    {
        switch (e.StatusType)
        {
            case GestureStatus.Running:
                // Translate and pan.
                double boundsX = Content.Width;
                double boundsY = Content.Height;
                Content.TranslationX = Math.Clamp(panX + e.TotalX, -boundsX, boundsX);
                Content.TranslationY = Math.Clamp(panY + e.TotalY, -boundsY, boundsY);
                break;

            case GestureStatus.Completed:
                // Store the translation applied during the pan
                panX = Content.TranslationX;
                panY = Content.TranslationY;
                break;
        }
    }
}

在此示例中，OnPanUpdated 方法根据用户的平移手势更新包装视图的可查看内容。这是通过以下方式来实现的：使用 PanUpdatedEventArgs 实例的 TotalX 和 TotalY 属性的值来计算平移的方向和距离。然后，通过将包装的用户元素的 TranslationX 和 TranslationY 属性设置为已计算值，对该元素进行平移。对未占据整个屏幕的元素中的内容进行平移时，可以从该元素的 Height 和 Width 属性中获取视区的高度和宽度。

PanContainer 类可以包装在 View 周围，以便识别的平移手势将平移包装视图。以下 XAML 示例演示了包装 Image 的 PanContainer：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:PanGesture"
             x:Class="PanGesture.MainPage">
    <AbsoluteLayout>
        <local:PanContainer>
            <Image Source="monkey.jpg" WidthRequest="1024" HeightRequest="768" />
        </local:PanContainer>
    </AbsoluteLayout>
</ContentPage>

在此示例中，当 Image 接收到平移手势时，将平移显示的图像。

通过

识别平移手势

创建 PanGestureRecognizer

创建平移容器

其他资源