Dodawanie rozpoznawania gestów przeciągania i upuszczania

Artykuł
04/14/2021

Gest 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.

Ważne

Rozpoznawanie gestów przeciągania i upuszczania jest obsługiwane w systemach iOS, Android i platforma uniwersalna systemu Windows (UWP). Jednak w systemie iOS wymagana jest minimalna platforma systemu iOS 11.

Ź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:

Włącz przeciąganie elementu, dodając DragGestureRecognizer obiekt do kolekcji GestureRecognizers . Aby uzyskać więcej informacji, zobacz Włączanie przeciągania.
[opcjonalnie] Tworzenie pakietu danych. Xamarin.Forms 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.
Włącz upuszczanie elementu przez dodanie DropGestureRecognizer obiektu jego GestureRecognizers kolekcji. Aby uzyskać więcej informacji, zobacz Włączanie upuszczania.
[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).
[opcjonalnie] Przetwórz pakiet danych, aby otrzymać porzuconą zawartość. Xamarin.Forms Program 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.

Uwaga

Przeciąganie elementów do i z elementu CollectionView jest obecnie nieobsługiwane.

Włącz przeciąganie

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

CanDrag, typu bool, który wskazuje, czy element, do którego jest dołączony aparat rozpoznawania gestów, może być źródłem przeciągania. Wartość domyślna tej właściwości to true.
DragStartingCommand, typu ICommand, który jest wykonywany po pierwszym rozpoznaniu gestu przeciągania.
DragStartingCommandParameter, typu object, który jest parametrem przekazanym do .DragStartingCommand
DropCompletedCommand, typu ICommand, który jest wykonywany, gdy źródło przeciągania jest porzucone.
DropCompletedCommandParameter, typu object, który jest parametrem przekazanym do .DropCompletedCommand

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, pod warunkiem, że CanDrag właściwość to 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:

Handled, typu bool, wskazuje, czy program obsługi zdarzeń obsłużył zdarzenie, czy Xamarin.Forms też powinien kontynuować własne przetwarzanie.
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.

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

W systemach iOS, Android i UWP gest przeciągania jest inicjowany za pomocą długiego naciśnięcia, a następnie przeciągania.

Tworzenie pakietu danych

Xamarin.Forms automatycznie skompiluje pakiet danych po zainicjowaniu przeciągania dla następujących kontrolek:

Kontrolki tekstu. Wartości tekstowe można przeciągać z CheckBoxobiektów , , EntryLabelEditorRadioButtonDatePickerSwitch, i .TimePicker
Kontrolki obrazu. Obrazy można przeciągać z Buttonkontrolek , Imagei ImageButton .

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`	`bool`przekonwertowany na .`string`
`DatePicker`	`Date`	`DateTime`przekonwertowany na .`string`
`Editor`	`Text`
`Entry`	`Text`
`Label`	`Text`
`RadioButton`	`IsChecked`	`bool`przekonwertowany na .`string`
`Switch`	`IsToggled`	`bool`przekonwertowany na .`string`
`TimePicker`	`Time`	`TimeSpan`przekonwertowany 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:

Properties, typu DataPackagePropertySet, który jest kolekcją właściwości, które składają się na dane zawarte w obiekcie DataPackage. Ta właściwość jest właściwością tylko do odczytu.
Image, typu ImageSource, który jest obrazem zawartym w obiekcie DataPackage.
Text, typu string, który jest tekstem zawartym w obiekcie DataPackage.
View, typu DataPackageView, który jest wersją tylko do odczytu elementu DataPackage.

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żna to zrobić w procedurze obsługi zdarzenia DragStarting .

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 wyzwalane po wykryciu gestu przeciągania na Pathobiekcie , który wykonuje procedurę OnDragStarting obsługi zdarzeń:

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żna to zrobić w procedurze obsługi zdarzenia DragStarting .

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 wyzwalane po wykryciu gestu przeciągania na Rectangleobiekcie , który wykonuje procedurę OnDragStarting obsługi zdarzeń:

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, który reprezentuje rozmiar Rectangleobiektu , względem klucza "Kwadrat".

Włącz upuszczanie

W Xamarin.Formspliku 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ą wyzwalane pod warunkiem, że AllowDrop właściwość to 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.

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 Xamarin.Forms też powinien kontynuować własne przetwarzanie.

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 zostanie porzucone na Image miejscu docelowym upuszczania, źródło przeciągania zostanie skopiowane do miejsca docelowego upuszczania, pod warunkiem, że źródło przeciągania to ImageSource. Dzieje się tak, ponieważ Xamarin.Forms automatycznie kopiuje przeciągane obrazy i tekst do zgodnych miejsc docelowych 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. Można to osiągnąć, ustawiając AcceptedOperation właściwość typu DataPackageOperation, DragEventArgs obiektu, 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 wyzwalane, gdy źródło przeciągania jest przeciągane przez obiekt docelowy upuszczania, ale nie zostało usunięte, 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ść . Dzięki temu nie zostanie podjęta żadna akcja, gdy źródło przeciągania zostanie porzucone przez obiekt docelowy upuszczania.

Przetwarzanie pakietu danych

Zdarzenie Drop jest wyzwalane, gdy źródło przeciągania jest zwalniane przez obiekt docelowy upuszczania. W takim przypadku Xamarin.Forms program automatycznie podejmie próbę pobrania danych z pakietu danych po upuszczonym źródle przeciągania na następujące kontrolki:

Kontrolki tekstu. Wartości tekstowe można porzucić na CheckBoxobiektach , , DatePicker, LabelEditorEntry, RadioButton, , Switch, i TimePicker .
Kontrolki obrazu. Obrazy można porzucać na Buttonkontrolki , Imagei ImageButton .

W poniższej tabeli przedstawiono właściwości, które zostały ustawione, oraz wszelkie próby konwersji, gdy źródło przeciągania opartego na tekście jest porzucane na 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.

Udostępnij za pośrednictwem