Udostępnij za pośrednictwem

Rozpoznawanie gestu przeciągania i upuszczania

  • Artykuł

Wieloplatformowy interfejs użytkownika aplikacji platformy .NET (.NET MAUI) do rozpoznawania gestów przeciągania i upuszczania umożliwia przeciąganie elementów i skojarzonych z nimi pakietów danych z jednej lokalizacji na ekranie do innej lokalizacji przy użyciu gestu ciągłego. Przeciąganie i upuszczanie może odbywać się w jednej aplikacji lub może być uruchamiane w jednej aplikacji i kończyć się w innej.

Źródło przeciągania, czyli element, na którym zainicjowano gest przeciągania, może dostarczać dane, które mają być przesyłane przez wypełnienie obiektu pakietu danych. Po zwolnieniu źródła przeciągania następuje upuszczanie. Obiekt docelowy upuszczania, który jest elementem pod źródłem przeciągania, a następnie przetwarza pakiet danych.

Proces włączania przeciągania i upuszczania w aplikacji jest następujący:

  1. Włącz przeciąganie elementu, dodając DragGestureRecognizer obiekt do kolekcji GestureRecognizers . Aby uzyskać więcej informacji, zobacz Włączanie przeciągania.
  2. [opcjonalnie] Tworzenie pakietu danych. Program .NET MAUI automatycznie wypełnia pakiet danych dla kontrolek obrazów i tekstu, ale w przypadku innego pakietu danych należy skonstruować własny pakiet danych. Aby uzyskać więcej informacji, zobacz Tworzenie pakietu danych.
  3. Włącz upuszczanie elementu przez dodanie DropGestureRecognizer obiektu do jego GestureRecognizers kolekcji. Aby uzyskać więcej informacji, zobacz Włączanie upuszczania.
  4. [opcjonalnie] DropGestureRecognizer.DragOver Obsłuż zdarzenie, aby wskazać typ operacji dozwolonej przez miejsce docelowe upuszczania. Aby uzyskać więcej informacji, zobacz Handle the DragOver event (Obsługa zdarzenia DragOver).
  5. [opcjonalnie] Przetwórz pakiet danych, aby otrzymać porzuconą zawartość. Program .NET MAUI automatycznie pobiera dane obrazu i tekstu z pakietu danych, ale w przypadku innej zawartości należy przetworzyć pakiet danych. Aby uzyskać więcej informacji, zobacz Przetwarzanie pakietu danych.

Włącz przeciąganie

W programie .NET MAUI funkcja rozpoznawania gestów przeciągania jest dostarczana przez klasę DragGestureRecognizer . Ta klasa definiuje następujące właściwości:

Te właściwości są wspierane przez BindableProperty obiekty, co oznacza, że mogą być obiektami docelowymi powiązań danych i stylizowanymi.

Klasa DragGestureRecognizer definiuje DragStarting DropCompleted również zdarzenia, które są uruchamiane, jeśli CanDrag właściwość ma wartość true. DragGestureRecognizer Gdy obiekt wykryje gest przeciągania, wykonuje DragStartingCommand obiekt i wywołuje DragStarting zdarzenie. Następnie, gdy DragGestureRecognizer obiekt wykryje ukończenie gestu upuszczania, wykonuje DropCompletedCommand zdarzenie i wywołuje DropCompleted zdarzenie.

Obiekt DragStartingEventArgs , który towarzyszy DragStarting zdarzeniu, definiuje następujące właściwości:

  • Cancel, typu bool, wskazuje, czy zdarzenie powinno zostać anulowane.
  • Data, typu DataPackage, wskazuje pakiet danych, który towarzyszy źródle przeciągania. Jest to właściwość tylko do odczytu.
  • PlatformArgs, typu PlatformDragStartingEventArgs?, reprezentuje argumenty specyficzne dla platformy skojarzone ze zdarzeniem.

W systemie Android PlatformDragStartingEventArgs klasa definiuje następujące właściwości:

  • Sender, typu View, reprezentuje widok natywny dołączony do zdarzenia.
  • MotionEvent, typu MotionEvent, reprezentuje zdarzenie zawierające informacje o stanie przeciągania i upuszczania.

Ponadto w systemie Android PlatformDragStartingEventArgs klasa definiuje następujące metody:

  • SetDragShadowBuilder, który ustawia View.DragShadowBuilder parametr do użycia podczas przeciągania.
  • SetClipData, który ustawia parametr ClipData do użycia podczas przeciągania.
  • SetLocalData, który ustawia dane lokalne do użycia podczas przeciągania.
  • SetDragFlags, który ustawia DragFlags parametr do użycia podczas przeciągania.

Na przykład użyj SetClipData metody , aby skojarzyć ClipData z przeciągniętym elementem:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
#if ANDROID
    string content = "insert your content here";
    e.PlatformArgs.SetClipData(Android.Content.ClipData.NewPlainText("Drag data", content));
#endif
}

Obiekt DropCompletedEventArgs , który towarzyszy DropCompleted zdarzeniu definiuje PlatformArgs właściwość typu PlatformDropCompletedEventArgs?, która reprezentuje argumenty specyficzne dla platformy skojarzone ze zdarzeniem.

W systemie Android PlatformDropCompletedEventArgs klasa definiuje następujące właściwości:

  • Sender, typu View, reprezentuje widok natywny dołączony do zdarzenia.
  • DragEvent, typu DragEvent, reprezentuje zdarzenie wysyłane w różnych momentach podczas operacji przeciągania i upuszczania.

Poniższy przykład XAML przedstawia DragGestureRecognizer dołączony element do elementu Image:

<Image Source="monkeyface.png">
    <Image.GestureRecognizers>
        <DragGestureRecognizer />
    </Image.GestureRecognizers>
</Image>

W tym przykładzie można zainicjować gest przeciągania w obiekcie Image.

Napiwek

Gest przeciągania jest inicjowany za pomocą długiego naciśnięcia, po którym następuje przeciąganie.

Tworzenie pakietu danych

Program .NET MAUI automatycznie skompiluje pakiet danych po zainicjowaniu przeciągania dla następujących kontrolek:

W poniższej tabeli przedstawiono właściwości odczytywane i wszelkie próby konwersji po zainicjowaniu przeciągania w kontrolce tekstu:

Kontrolka Właściwości Konwersja
CheckBox IsChecked boolprzekonwertowany na .string
DatePicker Date DateTimeprzekonwertowany na .string
Editor Text
Entry Text
Label Text
RadioButton IsChecked boolprzekonwertowany na .string
Switch IsToggled boolprzekonwertowany na .string
TimePicker Time TimeSpanprzekonwertowany na .string

W przypadku zawartości innej niż tekst i obrazy należy samodzielnie skompilować pakiet danych.

Pakiety danych są reprezentowane przez klasę DataPackage , która definiuje następujące właściwości:

Klasa DataPackagePropertySet reprezentuje torbę właściwości przechowywaną Dictionary<string,object>jako . Aby uzyskać informacje o DataPackageView klasie, zobacz Przetwarzanie pakietu danych.

Przechowywanie danych obrazu lub tekstu

Dane obrazu lub tekstu można skojarzyć ze źródłem przeciągania, przechowując dane we DataPackage.Image właściwości lub DataPackage.Text . Możesz dodać dane w procedurze obsługi dla DragStarting zdarzenia.

W poniższym przykładzie XAML pokazano, DragGestureRecognizer że program obsługi dla zdarzenia DragStarting jest rejestrowany:

<Path Stroke="Black"
      StrokeThickness="4">
    <Path.GestureRecognizers>
        <DragGestureRecognizer DragStarting="OnDragStarting" />
    </Path.GestureRecognizers>
    <Path.Data>
        <!-- PathGeometry goes here -->
    </Path.Data>
</Path>

W tym przykładzie obiekt DragGestureRecognizer jest dołączony do Path obiektu. Zdarzenie DragStarting jest zgłaszane po wykryciu gestu przeciągania na Pathobiekcie , który wykonuje program obsługi zdarzeń OnDragStarting :

void OnDragStarting(object sender, DragStartingEventArgs e)
{
    e.Data.Text = "My text data goes here";
}

Obiekt DragStartingEventArgs , który towarzyszy DragStarting zdarzeniu, ma Data właściwość typu DataPackage. W tym przykładzie Text właściwość DataPackage obiektu jest ustawiona stringna wartość . Następnie DataPackage można uzyskać dostęp do obiektu po upuszczaniu, aby pobrać element string.

Przechowywanie danych w torbie właściwości

Wszystkie dane, w tym obrazy i tekst, mogą być skojarzone ze źródłem przeciągania, przechowując dane w kolekcji DataPackage.Properties . Możesz dodać dane w procedurze obsługi dla DragStarting zdarzenia.

W poniższym przykładzie XAML pokazano, DragGestureRecognizer że program obsługi dla zdarzenia DragStarting jest rejestrowany:

<Rectangle Stroke="Red"
           Fill="DarkBlue"
           StrokeThickness="4"
           HeightRequest="200"
           WidthRequest="200">
    <Rectangle.GestureRecognizers>
        <DragGestureRecognizer DragStarting="OnDragStarting" />
    </Rectangle.GestureRecognizers>
</Rectangle>

W tym przykładzie obiekt DragGestureRecognizer jest dołączony do Rectangle obiektu. Zdarzenie DragStarting jest zgłaszane po wykryciu gestu przeciągania na Rectangleobiekcie , który wykonuje program obsługi zdarzeń OnDragStarting :

void OnDragStarting(object sender, DragStartingEventArgs e)
{
    Shape shape = (sender as Element).Parent as Shape;
    e.Data.Properties.Add("Square", new Square(shape.Width, shape.Height));
}

Obiekt DragStartingEventArgs , który towarzyszy DragStarting zdarzeniu, ma Data właściwość typu DataPackage. Kolekcja Properties DataPackage obiektu, który jest kolekcją Dictionary<string, object> , można zmodyfikować w celu przechowywania wszelkich wymaganych danych. W tym przykładzie Properties słownik jest modyfikowany w celu przechowywania Square obiektu reprezentującego rozmiar Rectangle klucza "Kwadrat".

Włącz upuszczanie

W programie .NET MAUI funkcja rozpoznawania gestów upuszczania jest dostarczana przez klasę DropGestureRecognizer . Ta klasa definiuje następujące właściwości:

  • AllowDrop, typu bool, który wskazuje, czy element, do którego jest dołączony aparat rozpoznawania gestów, może być obiektem docelowym upuszczania. Wartość domyślna tej właściwości to true.
  • DragOverCommand, typu ICommand, który jest wykonywany, gdy źródło przeciągania jest przeciągane na obiekt docelowy upuszczania.
  • DragOverCommandParameter, typu object, który jest parametrem przekazanym do .DragOverCommand
  • DragLeaveCommand, typu ICommand, który jest wykonywany, gdy źródło przeciągania jest przeciągane z miejsca docelowego upuszczania.
  • DragLeaveCommandParameter, typu object, który jest parametrem przekazanym do .DragLeaveCommand
  • DropCommand, typu ICommand, który jest wykonywany, gdy źródło przeciągania jest porzucane przez obiekt docelowy upuszczania.
  • DropCommandParameter, typu object, który jest parametrem przekazanym do .DropCommand

Te właściwości są wspierane przez BindableProperty obiekty, co oznacza, że mogą być obiektami docelowymi powiązań danych i stylizowanymi.

Klasa DropGestureRecognizer definiuje DragOverrównież zdarzenia , DragLeavei Drop , które są uruchamiane, jeśli AllowDrop właściwość ma wartość true. DropGestureRecognizer Gdy element rozpozna źródło przeciągania nad obiektem docelowym upuszczania, wykonuje DragOverCommand zdarzenie i wywołuje jeDragOver. Następnie, jeśli źródło przeciągania jest przeciągane z miejsca docelowego upuszczania, DropGestureRecognizer polecenie wykonuje DragLeaveCommand i wywołuje DragLeave zdarzenie. Na koniec po rozpoznaniu DropGestureRecognizer gestu upuszczania nad obiektem docelowym upuszczania wykonuje DropCommand i wywołuje Drop zdarzenie.

Klasa DragEventArgs , która towarzyszy DragOver zdarzeń i DragLeave , definiuje następujące właściwości:

  • Data, typu DataPackage, który zawiera dane skojarzone ze źródłem przeciągania. Ta właściwość jest tylko do odczytu.
  • AcceptedOperation, typu DataPackageOperation, który określa, które operacje są dozwolone przez obiekt docelowy upuszczania.
  • PlatformArgs, typu PlatformDragEventArgs?, reprezentuje argumenty specyficzne dla platformy skojarzone ze zdarzeniem.

W systemie Android PlatformDragEventArgs klasa definiuje następujące właściwości:

  • Sender, typu View, reprezentuje widok natywny dołączony do zdarzenia.
  • DragEvent, typu DragEvent, reprezentuje zdarzenie wysyłane w różnych momentach podczas operacji przeciągania i upuszczania.

Aby uzyskać informacje na temat wyliczenia, zobacz Handle the DataPackageOperation DragOver event (Obsługa zdarzenia DragOver).

Klasa DropEventArgs , która towarzyszy Drop zdarzeniu, definiuje następujące właściwości:

  • Data, typu DataPackageView, który jest wersją pakietu danych tylko do odczytu.
  • Handled, typu bool, wskazuje, czy program obsługi zdarzeń obsłużył zdarzenie, czy też program .NET MAUI powinien kontynuować własne przetwarzanie.
  • PlatformArgs, typu PlatformDropEventArgs?, reprezentuje argumenty specyficzne dla platformy skojarzone ze zdarzeniem.

W systemie Android PlatformDropEventArgs klasa definiuje następujące właściwości:

  • Sender, typu View, reprezentuje widok natywny dołączony do zdarzenia.
  • DragEvent, typu DragEvent, reprezentuje zdarzenie wysyłane w różnych momentach podczas operacji przeciągania i upuszczania.

Poniższy przykład XAML przedstawia DropGestureRecognizer dołączony element do elementu Image:

<Image BackgroundColor="Silver"
       HeightRequest="300"
       WidthRequest="250">
    <Image.GestureRecognizers>
        <DropGestureRecognizer />
    </Image.GestureRecognizers>
</Image>

W tym przykładzie, gdy źródło przeciągania jest porzucane na Image cel upuszczania, źródło przeciągania zostanie skopiowane do miejsca docelowego upuszczania, jeśli źródło przeciągania jest ImageSource. Program .NET MAUI automatycznie kopiuje przeciągane obrazy i tekst do zgodnych celów upuszczania.

Obsługa zdarzenia DragOver

Zdarzenie DropGestureRecognizer.DragOver można opcjonalnie obsłużyć, aby wskazać, który typ operacji jest dozwolony przez cel upuszczania. Dozwolone operacje można wskazać, ustawiając AcceptedOperation właściwość typu DataPackageOperation, na DragEventArgs obiekcie, który towarzyszy DragOver zdarzeniu.

Wyliczenie DataPackageOperation definiuje następujące elementy członkowskie:

  • None, wskazuje, że nie zostanie wykonana żadna akcja.
  • Copy, wskazuje, że zawartość źródłowa przeciągania zostanie skopiowana do miejsca docelowego upuszczania.

Ważne

Po utworzeniu DragEventArgs obiektu właściwość jest domyślnie ustawiona AcceptedOperation na DataPackageOperation.Copy.

W poniższym przykładzie XAML pokazano, DropGestureRecognizer że program obsługi dla zdarzenia DragOver jest rejestrowany:

<Image BackgroundColor="Silver"
       HeightRequest="300"
       WidthRequest="250">
    <Image.GestureRecognizers>
        <DropGestureRecognizer DragOver="OnDragOver" />
    </Image.GestureRecognizers>
</Image>

W tym przykładzie obiekt DropGestureRecognizer jest dołączony do Image obiektu. Zdarzenie DragOver jest wywoływane, gdy źródło przeciągania jest przeciągane przez obiekt docelowy upuszczania, ale nie zostało porzucone, co powoduje wykonanie OnDragOver programu obsługi zdarzeń:

void OnDragOver(object sender, DragEventArgs e)
{
    e.AcceptedOperation = DataPackageOperation.None;
}

W tym przykładzie AcceptedOperation DragEventArgs właściwość obiektu jest ustawiona na DataPackageOperation.Nonewartość . Ta wartość gwarantuje, że nie zostanie podjęta żadna akcja, gdy źródło przeciągania zostanie porzucone przez obiekt docelowy upuszczania.

Przetwarzanie pakietu danych

Zdarzenie Drop jest zgłaszane, gdy źródło przeciągania jest zwalniane przez obiekt docelowy upuszczania. Program .NET MAUI automatycznie próbuje pobrać dane z pakietu danych, gdy źródło przeciągania zostanie porzucone na następujące kontrolki:

W poniższej tabeli przedstawiono właściwości ustawione i dowolną konwersję, która jest podejmowana, gdy źródło przeciągania opartego na tekście jest porzucane w kontrolce tekstu:

Kontrolka Właściwości Konwersja
CheckBox IsChecked string element jest konwertowany na element bool.
DatePicker Date string element jest konwertowany na element DateTime.
Editor Text
Entry Text
Label Text
RadioButton IsChecked string element jest konwertowany na element bool.
Switch IsToggled string element jest konwertowany na element bool.
TimePicker Time string element jest konwertowany na element TimeSpan.

W przypadku zawartości innego niż tekst i obrazy należy samodzielnie przetworzyć pakiet danych.

Klasa DropEventArgs , która towarzyszy Drop zdarzeniu definiuje Data właściwość typu DataPackageView. Ta właściwość reprezentuje wersję pakietu danych tylko do odczytu.

Pobieranie danych obrazu lub tekstu

Dane obrazu lub tekstu można pobrać z pakietu danych w procedurze obsługi zdarzenia Drop przy użyciu metod zdefiniowanych w DataPackageView klasie.

Klasa DataPackageView zawiera GetImageAsync metody i GetTextAsync . Metoda GetImageAsync pobiera obraz z pakietu danych przechowywanego DataPackage.Image we właściwości i zwraca wartość Task<ImageSource>. GetTextAsync Podobnie metoda pobiera tekst z pakietu danych przechowywanego DataPackage.Text we właściwości i zwraca wartość Task<string>.

W poniższym przykładzie przedstawiono procedurę obsługi zdarzeń Drop , która pobiera tekst z pakietu danych dla elementu Path:

async void OnDrop(object sender, DropEventArgs e)
{
    string text = await e.Data.GetTextAsync();

    // Perform logic to take action based on the text value.
}

W tym przykładzie dane tekstowe są pobierane z pakietu danych przy użyciu GetTextAsync metody . Następnie można wykonać akcję opartą na wartości tekstowej.

Pobieranie danych z torby właściwości

Wszystkie dane można pobrać z pakietu danych w procedurze obsługi zdarzenia Drop , korzystając Properties z kolekcji pakietu danych.

Klasa DataPackageView definiuje Properties właściwość typu DataPackagePropertySetView. Klasa DataPackagePropertySetView reprezentuje torbę właściwości tylko do odczytu przechowywaną Dictionary<string, object>jako .

Poniższy przykład przedstawia procedurę Drop obsługi zdarzeń, która pobiera dane z torby właściwości pakietu danych dla elementu Rectangle:

void OnDrop(object sender, DropEventArgs e)
{
    Square square = (Square)e.Data.Properties["Square"];

    // Perform logic to take action based on retrieved value.
}

W tym przykładzie Square obiekt jest pobierany z torby właściwości pakietu danych, określając klucz słownika "Square". Następnie można wykonać akcję opartą na pobranej wartości.

Przeciąganie i upuszczanie między aplikacjami

W systemach iOS, Mac Catalyst i Windows przeciągnięcie może rozpocząć się w jednej aplikacji z odpowiednią operacją upuszczania kończącą się w aplikacji .NET MAUI. Aplikacja, z której element jest przeciągany, to aplikacja źródłowa, a aplikacja .NET MAUI, na której jest porzucony element, jest aplikacją docelową.

Nie można przeciągać z aplikacji źródłowej do aplikacji docelowej .NET MAUI w systemie Android.

Uzyskiwanie położenia gestu

Położenie, w którym wystąpił gest przeciągania lub upuszczania, można uzyskać, wywołując metodę GetPosition DragEventArgsw obiekcie , DragStartingEventArgslub DropEventArgs . Metoda GetPosition akceptuje Element? argument i zwraca pozycję jako Point? obiekt:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
    // Position relative to screen
    Point? screenPosition = e.GetPosition(null);

    // Position relative to specified element
    Point? relativeToImagePosition = e.GetPosition(image);
}

Argument Element? definiuje element, z który należy uzyskać pozycję względem. Podanie wartości jako tego argumentu null oznacza, że GetPosition metoda zwraca Point? obiekt, który definiuje położenie gestu przeciągania lub upuszczania względem ekranu.