Распознавание жеста перетаскивания

Статья
05/14/2024

Мультиплатформенный пользовательский интерфейс приложения .NET (.NET MAUI) позволяет распознаватель жестов перетаскивания и элементы, связанные с ними пакеты данных, перетаскиваться из одного расположения на экране в другое расположение с помощью непрерывного жеста. Перетаскивание можно выполнять в одном приложении или запустить в одном приложении и закончить в другом.

Источник перетаскивания, являющийся элементом, на котором инициируется жест перетаскивания, может обеспечить передачу данных путем заполнения объекта пакета данных. Когда источник перетаскивания освобождается, происходит отпускание. Целевой объект перетаскивания, который является элементом источника перетаскивания, обрабатывает пакет данных.

Процесс включения перетаскивания в приложении выглядит следующим образом:

Включите перетаскивание элемента, добавив объект DragGestureRecognizer в его коллекцию GestureRecognizers. Дополнительные сведения см. в разделе Включение перетаскивания.
[Необязательно] Создайте пакет данных. .NET MAUI автоматически заполняет пакет данных для элементов управления изображением и текстом, но для другого содержимого необходимо создать собственный пакет данных. Дополнительные сведения см. в разделе Создание пакета данных.
Включите удаление элемента, добавив DropGestureRecognizer объект в свою GestureRecognizers коллекцию. Дополнительные сведения см. в разделе Включение отпускания.
[Необязательно] Обработайте событие DropGestureRecognizer.DragOver, чтобы указать тип операции, разрешенной целью отпускания. Дополнительные сведения см. в разделе Обработка события DragOver.
[Необязательно] Обработайте пакет данных для получения отпускаемого содержимого. .NET MAUI автоматически извлекает изображения и текстовые данные из пакета данных, но для другого содержимого необходимо обработать пакет данных. Дополнительные сведения см. в разделе Обработка пакета данных.

Включение перетаскивания

В .NET MAUI распознавание жестов обеспечивается классом DragGestureRecognizer . Этот класс определяет приведенные ниже свойства.

CanDrag с типом bool, который указывает, может ли элемент, к которому прикреплен распознаватель жестов, быть источником перетаскивания. Значение по умолчанию этого свойства равно true.
DragStartingCommand с типом ICommand, который выполняется при первом распознавании жеста перетаскивания.
DragStartingCommandParameter с типом object, который передается как параметр в DragStartingCommand.
DropCompletedCommand с типом ICommand, который выполняется при отпускании источника перетаскивания.
DropCompletedCommandParameter с типом object, который передается как параметр в DropCompletedCommand.

Эти свойства поддерживаются объектами BindableProperty, то есть эти свойства можно указывать в качестве целевых для привязки и стилизации данных.

Класс DragGestureRecognizer также определяет и DropCompleted события, которые запускаютDragStarting, если CanDrag свойство равноtrue. Когда объект DragGestureRecognizer обнаруживает жест перетаскивания, он выполняет DragStartingCommand и вызывает событие DragStarting. Далее, когда объект DragGestureRecognizer обнаруживает завершение жеста отпускания, он выполняет DropCompletedCommand и вызывает событие DropCompleted.

Объект DragStartingEventArgs, который прилагается к событию DragStarting, содержит приведенные ниже свойства.

Cancel с типом bool — указывает, следует ли отменять событие.
Data с типом DataPackage — указывает пакет данных, сопровождающий источник перетаскивания. Это свойство доступно только для чтения.
PlatformArgsPlatformDragStartingEventArgs?Тип , представляет аргументы, связанные с событием, зависящие от платформы.

В Android PlatformDragStartingEventArgs класс определяет следующие свойства:

SenderViewТип , представляет собственное представление, присоединенное к событию.
MotionEventMotionEventТип , представляет событие, содержащее сведения о состоянии перетаскивания.

Кроме того, в Android PlatformDragStartingEventArgs класс определяет следующие методы:

SetDragShadowBuilder, который задает View.DragShadowBuilder использование при перетаскивании начинается.
SetClipData, который задает используемый ClipData при перетаскивании начинается.
SetLocalData, который задает локальные данные для использования при перетаскивании.
SetDragFlags, который задает DragFlags использование при перетаскивании начинается.

Например, используйте SetClipData метод для связывания ClipData с перетаскиваемого элемента:

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
}

В iOS и Mac Catalyst PlatformDragStartingEventArgs класс определяет следующие свойства:

SenderUIViewТип , представляет собственное представление, присоединенное к событию.
GestureRecognizerUIGestureRecognizerТип , указывает собственное событие или обработчик, подключенный к представлению.

Кроме того, в iOS и Mac Catalyst PlatformDragStartingEventArgs класс определяет следующие методы:

SetItemProvider, который задает NSItemProvider использование при перетаскивании начинается.
SetPreviewProvider, который задает UIDragPreview использование при перетаскивании начинается.
SetDragItems, который задает массив, используемый UIDragItem при перетаскивании начинается.
SetPrefersFullSizePreview, который задает func, который запрашивает перетаскивание предварительных просмотров, полный размер при перетаскивании начинается.

Например, используйте SetPreviewProvider метод, чтобы задать объект для использования в качестве предварительного просмотра перетаскиваемого элемента:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
#if IOS || MACCATALYST
    Func<UIKit.UIDragPreview> action = () =>
    {
        var image = UIKit.UIImage.FromFile("dotnet_bot.png");
        UIKit.UIImageView imageView = new UIKit.UIImageView(image);
        imageView.ContentMode = UIKit.UIViewContentMode.Center;
        imageView.Frame = new CoreGraphics.CGRect(0, 0, 250, 250);
        return new UIKit.UIDragPreview(imageView);
    };

    e.PlatformArgs.SetPreviewProvider(action);
#endif
}

В этом примере предварительный просмотр перетаскиваемого элемента заменяется изображением.

Чтобы установить предварительный просмотр перетаскивания на полный размер, используйте SetPrefersFullSizePreview метод:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
#if IOS || MACCATALYST
    e.PlatformArgs.SetPrefersFullSizePreviews((interaction, session) => { return true; });
#endif
}

В Windows PlatformDragStartingEventArgs класс определяет следующие свойства:

SenderFrameworkElementТип , представляет собственное представление, присоединенное к событию.
DragStartingEventArgs( тип DragStartingEventArgs) предоставляет данные о событиях для собственного события.
HandledboolТип , определяет, изменились ли аргументы события. Это свойство должно иметь значение true при изменении DragStartingEventArgs , чтобы изменения не переопределены.

Объект DropCompletedEventArgs , который сопровождает DropCompleted событие, определяет PlatformArgs свойство типа PlatformDropCompletedEventArgs?, представляющее аргументы конкретной платформы, связанные с событием.

В Android PlatformDropCompletedEventArgs класс определяет следующие свойства:

SenderViewТип , представляет собственное представление, присоединенное к событию.
DragEventDragEventТип , представляет событие, которое отправляется в разное время во время операции перетаскивания и перетаскивания.

В iOS и Mac Catalyst PlatformDropCompletedEventArgs класс определяет следующие свойства:

SenderUIViewТип , представляет собственное представление, присоединенное к событию.
DragInteractionUIDragInteractionТип , указывает взаимодействие, используемое для перетаскивания элементов. Это свойство используется при PlatformDropCompletedEventArgs вызове из SessionWillEnd.
DragSessionIUIDragSessionТип , извлекает связанные сведения из сеанса перетаскивания. Это свойство используется при PlatformDropCompletedEventArgs вызове из SessionWillEnd.
DropOperationUIDropOperationТип , представляет ответ на падение. Это свойство используется при PlatformDropCompletedEventArgs вызове из SessionWillEnd.
DropInteractionUIDropInteractionТип , указывает взаимодействие, используемое для удаления элементов. Это свойство используется при PlatformDropCompletedEventArgs вызове из PerformDrop.
DropSessionIUIDropSessionТип , извлекает связанные сведения из сеанса удаления. Это свойство используется при PlatformDropCompletedEventArgs вызове из PerformDrop.

В Windows PlatformDropCompletedEventArgs класс определяет следующие свойства:

SenderFrameworkElementТип , представляет собственное представление, присоединенное к событию.
DropCompletedEventArgs( тип DropCompletedEventArgs) предоставляет данные о событиях для собственного события.

В следующем примере кода XAML показан DragGestureRecognizer, присоединенный к Image:

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

В этом примере можно инициировать жест перетаскивания в Image.

Совет

Жест перетаскивания инициируется длинным нажатием, за которым следует перетаскивание.

Создание пакета данных

.NET MAUI автоматически создает пакет данных при инициировании перетаскивания для следующих элементов управления:

Текстовые элементы управления. Текстовые значения можно перетаскивать из объектов CheckBox, DatePicker, Editor, Entry, Label, RadioButton, Switch и TimePicker.
Элементы управления изображениями. Изображения можно перетаскивать из элементов управления Button, Image и ImageButton.

В следующей таблице показаны свойства, которые считываются, и все попытки преобразования, которые выполняются при инициировании перетаскивания текстовых элементов управления.

Элемент управления	Свойство	Преобразование
CheckBox	`IsChecked`	`bool` преобразуется в `string`.
DatePicker	`Date`	`DateTime` преобразуется в `string`.
Editor	`Text`
Entry	`Text`
Label	`Text`
RadioButton	`IsChecked`	`bool` преобразуется в `string`.
Switch	`IsToggled`	`bool` преобразуется в `string`.
TimePicker	`Time`	`TimeSpan` преобразуется в `string`.

Для содержимого, отличного от текста и изображений, необходимо самостоятельно создать пакет данных.

Пакеты данных представлены классом DataPackage, который определяет приведенные ниже свойства.

Properties с типом DataPackagePropertySet, который представляет собой коллекцию свойств, составляющих данные, содержащиеся в DataPackage. Это свойство доступно только для чтения.
Image с типом ImageSource, который является изображением, содержащимся в DataPackage.
Text с типом string, который является текстом, содержащимся в DataPackage.
View с типом DataPackageView, который является версией DataPackage только для чтения.

Класс DataPackagePropertySet представляет контейнер свойств, хранящийся как Dictionary<string,object>. Дополнительные сведения о классе DataPackageView см. в разделе Обработка пакета данных.

Хранение изображений или текстовых данных

Изображения или текстовые данные могут быть связаны с источником перетаскивания путем сохранения данных в свойстве DataPackage.Image или DataPackage.Text. Вы можете добавить данные в обработчик события DragStarting .

В следующем примере XAML показан DragGestureRecognizer, регистрирующий обработчик для события DragStarting:

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

В этом примере DragGestureRecognizer присоединяется к объекту Path. Событие DragStarting возникает при обнаружении жеста перетаскивания на объекте Path, который выполняет OnDragStarting обработчик событий:

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

Объект DragStartingEventArgs, сопровождающий событие DragStarting, имеет свойство Data с типом DataPackage. В этом примере свойству Text объекта DataPackage присваивается string. Затем к DataPackage можно получить доступ при отпускании, чтобы получить string.

Хранение данных в контейнере свойств

Любые данные, включая изображения и текст, могут быть связаны с источником перетаскивания путем сохранения данных в коллекции DataPackage.Properties. Вы можете добавить данные в обработчик события DragStarting .

В следующем примере XAML показан DragGestureRecognizer, регистрирующий обработчик для события DragStarting:

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

В этом примере DragGestureRecognizer присоединяется к объекту Rectangle. Событие DragStarting возникает при обнаружении жеста перетаскивания на объекте Rectangle, который выполняет 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));
}

Объект DragStartingEventArgs, сопровождающий событие DragStarting, имеет свойство Data с типом DataPackage. Коллекция Properties объекта DataPackage, который является коллекцией Dictionary<string, object>, можно изменить для хранения необходимых данных. В этом примере Properties словарь изменяется для хранения Square объекта, представляющего размер Rectangle ключа Square.

Включение отпускания

В .NET MAUI распознавание жестов перетаскивания предоставляется классом DropGestureRecognizer . Этот класс определяет приведенные ниже свойства.

AllowDrop с типом bool, который указывает, может ли элемент, к которому прикреплен распознаватель жестов, быть источником отпускания. Значение по умолчанию этого свойства равно true.
DragOverCommand с типом ICommand, который выполняется при перетаскивании источника перетаскивания над целевым объектом отпускания.
DragOverCommandParameter с типом object, который передается как параметр в DragOverCommand.
DragLeaveCommand с типом ICommand, который выполняется при перетаскивании источника перетаскивания на целевой объект. перетаскивания
DragLeaveCommandParameter с типом object, который передается как параметр в DragLeaveCommand.
DropCommand с типом ICommand, который выполняется при отпускании источника перетаскивания над целевым объектом отпускания.
DropCommandParameter с типом object, который передается как параметр в DropCommand.

Класс DropGestureRecognizer также определяет и Drop DragLeaveсобытия, которые запускаютDragOver, если AllowDrop это свойствоtrue. Когда DropGestureRecognizer распознает источник перетаскивания для цели перетаскивания, он выполняет DragOverCommand и вызывает событие DragOver. Затем, если источник перетаскивания перетаскивается из целевого объекта перетаскивания, DropGestureRecognizer выполняет DragLeaveCommand и вызывает событие DragLeave. Затем, когда DropGestureRecognizer распознает жест перетаскивания на целевой объект перетаскивания, выполняется DropCommand и вызывается событие Drop.

Класс DragEventArgs , который сопровождает DragOver события и DragLeave события, определяет следующие свойства:

Data с типом DataPackage, который содержит данные, связанные с источником перетаскивания. Это свойство доступно только для чтения.
AcceptedOperation с типом DataPackageOperation, который указывает, какие операции разрешены целевым объектом отпускания.
PlatformArgsPlatformDragEventArgs?Тип , представляет аргументы, связанные с событием, зависящие от платформы.

В Android PlatformDragEventArgs класс определяет следующие свойства:

SenderViewТип , представляет собственное представление, присоединенное к событию.
DragEventDragEventТип , представляет событие, которое отправляется в разное время во время операции перетаскивания и перетаскивания.

В iOS и Mac Catalyst PlatformDragEventArgs класс определяет следующие свойства:

SenderUIViewТип , представляет собственное представление, присоединенное к событию.
DropInteractionUIDropInteractionТип , указывает взаимодействие, используемое для удаления элементов.
DropSessionIUIDropSessionТип , извлекает связанные сведения из сеанса удаления.

Кроме того, в iOS и Mac Catalyst PlatformDragEventArgs класс определяет SetDropProposal метод. Этот метод задает значение, используемое UIDropProposal при перетаскивании элемента по представлению:

void OnDragOver(object sender, DragEventArgs e)
{
#if IOS || MACCATALYST
    e.PlatformArgs.SetDropProposal(new UIKit.UIDropProposal(UIKit.UIDropOperation.Move));
#endif
}

В этом примере указывается, что данные, представленные элементом перетаскивания, UIDropOperation должны быть перемещены, а не скопированы.

В Windows PlatformDragEventArgs класс определяет следующие свойства:

SenderFrameworkElementТип , представляет собственное представление, присоединенное к событию.
DragEventArgs( тип DragEventArgs) предоставляет данные о событиях для собственного события.
HandledboolТип , определяет, изменились ли аргументы события. Это свойство должно иметь значение true при изменении DragEventArgs , чтобы изменения не переопределены.

Например, DragEventArgs свойство можно использовать для доступа к собственным свойствам:

void OnDragOver(object sender, DragEventArgs e)
{
#if WINDOWS
    var dragUI = e.PlatformArgs.DragEventArgs.DragUIOverride;
    dragUI.IsCaptionVisible = false;
    dragUI.IsGlyphVisible = false;
#endif
}

В этом примере глиф перетаскивания отключен и подпись текст, который накладывает визуальный элемент перетаскивания, также отключен.

Дополнительные сведения о перечислении DataPackageOperation см. в разделе Обработка события DragOver.

Класс DropEventArgs, который прилагается к событию Drop, содержит приведенные ниже свойства.

Data с типом DataPackageView, который является версией пакета данных только для чтения.
HandledboolТип , указывает, обрабатывает ли обработчик событий событие или следует ли продолжить собственную обработку .NET MAUI.
PlatformArgsPlatformDropEventArgs?Тип , представляет аргументы, связанные с событием, зависящие от платформы.

В Android PlatformDropEventArgs класс определяет следующие свойства:

SenderViewТип , представляет собственное представление, присоединенное к событию.
DragEventDragEventТип , представляет событие, которое отправляется в разное время во время операции перетаскивания и перетаскивания.

В iOS и Mac Catalyst PlatformDropEventArgs класс определяет следующие свойства:

SenderUIViewТип , представляет собственное представление, присоединенное к событию.
DropInteractionUIDropInteractionТип , указывает взаимодействие, используемое для удаления элементов.
DropSessionIUIDropSessionТип , извлекает связанные сведения из сеанса удаления.

В Windows PlatformDropEventArgs класс определяет следующие свойства:

SenderFrameworkElementТип , представляет собственное представление, присоединенное к событию.
DragEventArgs( тип DragEventArgs) предоставляет данные о событиях для собственного события. -->

В следующем примере кода XAML показан DropGestureRecognizer, присоединенный к Image:

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

В этом примере при удалении источника перетаскивания на целевом Image объекте перетаскивания источник перетаскивания будет скопирован в целевой объект перетаскивания, если источник перетаскивания является ImageSourceисточником перетаскивания. .NET MAUI автоматически копирует перетаскиваемые изображения и текст в совместимые целевые объекты удаления.

Обработка события DragOver

Событие DropGestureRecognizer.DragOver можно дополнительно обработать, чтобы указать, какие типы операций разрешены целевым объектом отпускания. Можно указать допустимые операции, задав AcceptedOperation свойство типа DataPackageOperationв DragEventArgs объекте, который сопровождает DragOver событие.

Перечисление DataPackageOperation определяет следующие члены:

None указывает, что действие не будет выполнено.
Copyуказывает, что содержимое источника перетаскивания будет скопировано в целевой объект отпускания.

Внимание

При создании объекта DragEventArgs свойству AcceptedOperation по умолчанию присвоено значение DataPackageOperation.Copy.

В следующем примере XAML показан DropGestureRecognizer, регистрирующий обработчик для события DragOver:

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

В этом примере DropGestureRecognizer присоединяется к объекту Image. Событие DragOver возникает при перетаскивании источника перетаскивания, но не было удалено, которое выполняет OnDragOver обработчик событий:

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

В этом примере свойству AcceptedOperation объекта DragEventArgs присваивается DataPackageOperation.None. Это значение гарантирует, что при удалении источника перетаскивания по целевому объекту перетаскивания не выполняется никаких действий.

Обработка пакета данных

Событие Drop возникает при освобождении источника перетаскивания по целевому объекту перетаскивания. .NET MAUI автоматически пытается получить данные из пакета данных при удалении источника перетаскивания на следующие элементы управления:

Текстовые элементы управления. Текстовые значения можно отпустить над объектами CheckBox, DatePicker, Editor, Entry, Label, RadioButton, Switch и TimePicker.
Элементы управления изображениями. Изображения можно отпускать над элементами управления Button, Image и ImageButton.

В следующей таблице показаны свойства, заданные и любые попытки преобразования при удалении источника перетаскивания на текстовом элементе управления:

Элемент управления	Свойство	Преобразование
CheckBox	`IsChecked`	`string` преобразуется в `bool`.
DatePicker	`Date`	`string` преобразуется в `DateTime`.
Editor	`Text`
Entry	`Text`
Label	`Text`
RadioButton	`IsChecked`	`string` преобразуется в `bool`.
Switch	`IsToggled`	`string` преобразуется в `bool`.
TimePicker	`Time`	`string` преобразуется в `TimeSpan`.

Для содержимого, отличного от текста и изображений, необходимо самостоятельно обработать пакет данных.

Класс DropEventArgs, который прилагается к событию Drop, указывает свойство Data с типом DataPackageView. Это свойство является версией пакета данных только для чтения.

Получение изображений или текстовых данных

Изображения или текстовые данные можно получить из пакета данных в обработчике события Drop с помощью методов, определенных в классе DataPackageView.

Класс DataPackageView включает в себя методы GetImageAsync и GetTextAsync. Метод GetImageAsync извлекает изображение из пакета данных, хранящегося в свойстве и возвращаемогоTask<ImageSource>DataPackage.Image. GetTextAsync Аналогичным образом метод извлекает текст из пакета данных, хранящегося в свойстве и возвращаемогоTask<string>DataPackage.Text.

В следующем примере показан обработчик событий Drop, который извлекает текст из пакета данных для Path:

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

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

В этом примере текстовые данные извлекаются из пакета данных с помощью метода GetTextAsync. Затем можно выполнить действие, основанное на текстовом значении.

Извлечение данных из контейнера свойств

Любые данные можно получить из пакета данных в обработчике события Drop, обратившись к коллекции Properties пакета данных.

Класс DataPackageView определяет свойство Properties с типом DataPackagePropertySetView. Класс DataPackagePropertySetView представляет контейнер свойств только для чтения, хранящийся как Dictionary<string, object>.

В следующем примере показан обработчик событий Drop, который извлекает данные из контейнера свойств пакета данных для Rectangle:

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

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

В этом примере объект Square извлекается из контейнера свойств пакета данных путем указания ключа Square словаря. Затем можно выполнить действие, основанное на извлеченном значении.

Получение позиции жеста

Положение, в котором произошло жест перетаскивания, можно получить путем вызова GetPosition метода в объекте DragEventArgsили DragStartingEventArgs DropEventArgs объекте. Метод GetPosition принимает Element? аргумент и возвращает позицию в качестве Point? объекта:

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);
}

Аргумент Element? определяет элемент, к который должна быть получена позиция относительно. null Указание значения в качестве этого аргумента означает, что GetPosition метод возвращает Point? объект, определяющий положение жеста перетаскивания относительно экрана.

Поделиться через