Adicionar reconhecedores de gestos de arrastar e soltar
Um gesto de arrastar e soltar permite que os itens e seus pacotes de dados associados sejam arrastados de um local na tela para outro local usando um gesto contínuo. Arrastar e soltar pode ocorrer em um único aplicativo, ou pode começar em um aplicativo e terminar em outro.
Importante
O reconhecimento de gestos de arrastar e soltar é compatível com iOS, Android e na Plataforma Universal do Windows (UWP). No entanto, no iOS é necessária uma plataforma mínima de iOS 11.
A origem de arraste, que é o elemento no qual o gesto de arrastar é iniciado, pode fornecer dados a serem transferidos preenchendo um objeto de pacote de dados. Quando a origem de arrastar é liberada, ocorre soltar. O destino de soltar, que é o elemento sob a origem de arraste, processa o pacote de dados.
O processo para habilitar o arrastar e soltar em um aplicativo é o seguinte:
- Habilite arrastar em um elemento adicionando um
DragGestureRecognizer
objeto à suaGestureRecognizers
coleção. Para obter mais informações, consulte Habilitar arrastar. - [opcional] Crie um pacote de dados. Xamarin.Forms preenche automaticamente o pacote de dados para controles de imagem e texto, mas para outro conteúdo, você precisará construir seu próprio pacote de dados. Para obter mais informações, consulte Criar um pacote de dados.
- Habilite soltar em um elemento adicionando um
DropGestureRecognizer
objeto à suaGestureRecognizers
coleção. Para obter mais informações, consulte Habilitar drop. - [opcional] Manipule o
DropGestureRecognizer.DragOver
evento para indicar o tipo de operação permitida pelo destino de descarte. Para obter mais informações, consulte Manipular o evento DragOver. - [opcional] Processe o pacote de dados para receber o conteúdo descartado. Xamarin.Forms recuperará automaticamente os dados de imagem e texto do pacote de dados, mas para outro conteúdo, você precisará processar o pacote de dados. Para obter mais informações, consulte Processar o pacote de dados.
Observação
No momento, não há suporte para arrastar itens de e para um CollectionView
no momento.
Ativar arrastar
No Xamarin.Forms, o reconhecimento de gestos DragGestureRecognizer
de arrastar é fornecido pela classe. Essa classe define as seguintes propriedades:
CanDrag
, do tipobool
, que indica se o elemento ao qual o reconhecedor de gestos está anexado pode ser uma fonte de arraste. O valor padrão dessa propriedade étrue
.DragStartingCommand
, do tipoICommand
, que é executado quando um gesto de arrastar é reconhecido pela primeira vez.DragStartingCommandParameter
, do tipoobject
, que é o parâmetro passado paraDragStartingCommand
.DropCompletedCommand
, do tipoICommand
, que é executado quando a fonte de arraste é solta.DropCompletedCommandParameter
, do tipoobject
, que é o parâmetro passado paraDropCompletedCommand
.
Essas propriedades são apoiadas por objetos BindableProperty
, o que significa que podem ser alvos de associações de dados e ser estilizada.
A DragGestureRecognizer
classe também define DragStarting
e DropCompleted
eventos que disparam desde que a CanDrag
propriedade seja true
. Quando um DragGestureRecognizer
objeto detecta um gesto de arrastar, ele executa o DragStartingCommand
e invoca o DragStarting
evento. Em seguida, quando o DragGestureRecognizer
objeto detecta a conclusão de um gesto de soltar, ele executa o DropCompletedCommand
e invoca o DropCompleted
evento.
O DragStartingEventArgs
objeto que acompanha o DragStarting
evento define as seguintes propriedades:
Handled
, do tipobool
, indica se o manipulador de eventos manipulou o evento ou se Xamarin.Forms deve continuar seu próprio processamento.Cancel
, do tipobool
, indica se o evento deve ser cancelado.Data
, do tipoDataPackage
, indica o pacote de dados que acompanha a origem de arraste. Trata-se de uma propriedade somente leitura.
O exemplo XAML a seguir mostra um DragGestureRecognizer
anexado a um Image
:
<Image Source="monkeyface.png">
<Image.GestureRecognizers>
<DragGestureRecognizer />
</Image.GestureRecognizers>
</Image>
Neste exemplo, um gesto Image
de arrastar pode ser iniciado no .
Dica
No iOS, Android e UWP, um gesto de arrastar é iniciado com uma pressão longa seguida de um arrasto.
Criar um pacote de dados
Xamarin.Forms criará automaticamente um pacote de dados para você, quando um arrastar for iniciado, para os seguintes controles:
- Controles de texto. Os valores de texto podem ser arrastados de
CheckBox
,DatePicker
,Editor
,Entry
,Label
,RadioButton
,Switch
eTimePicker
objetos. - Controles de imagem. As imagens podem ser arrastadas de
Button
,Image
eImageButton
controles.
A tabela a seguir mostra as propriedades que são lidas e qualquer conversão que é tentada, quando um arrastar é iniciado em um controle de texto:
Controle | Propriedade | Conversão |
---|---|---|
CheckBox |
IsChecked |
bool convertido em um string . |
DatePicker |
Date |
DateTime convertido em um string . |
Editor |
Text |
|
Entry |
Text |
|
Label |
Text |
|
RadioButton |
IsChecked |
bool convertido em um string . |
Switch |
IsToggled |
bool convertido em um string . |
TimePicker |
Time |
TimeSpan convertido em um string . |
Para conteúdo diferente de texto e imagens, você mesmo precisará criar um pacote de dados.
Os pacotes de dados são representados pela DataPackage
classe, que define as seguintes propriedades:
Properties
, do tipoDataPackagePropertySet
, que é uma coleção de propriedades que compõem os dados contidos noDataPackage
. Esta propriedade é somente leitura.Image
, do tipoImageSource
, que é a imagem contida noDataPackage
.Text
, do tipostring
, que é o texto contido noDataPackage
.View
, do tipoDataPackageView
, que é uma versão somente leitura doDataPackage
.
A DataPackagePropertySet
classe representa um conjunto de propriedades armazenado como um Dictionary<string,object>
arquivo . Para obter informações sobre a DataPackageView
classe, consulte Processar o pacote de dados.
Armazenar dados de imagem ou texto
Os dados de imagem ou texto podem ser associados a uma fonte de arrastar armazenando os dados na DataPackage.Image
propriedade ou DataPackage.Text
. Isso pode ser realizado no manipulador do DragStarting
evento.
O exemplo XAML a seguir mostra um DragGestureRecognizer
que registra um manipulador para o DragStarting
evento:
<Path Stroke="Black"
StrokeThickness="4">
<Path.GestureRecognizers>
<DragGestureRecognizer DragStarting="OnDragStarting" />
</Path.GestureRecognizers>
<Path.Data>
<!-- PathGeometry goes here -->
</Path.Data>
</Path>
Neste exemplo, o é anexado DragGestureRecognizer
a um Path
objeto. O DragStarting
evento é disparado quando um gesto Path
de arrastar é detectado no , que executa o OnDragStarting
manipulador de eventos:
void OnDragStarting(object sender, DragStartingEventArgs e)
{
e.Data.Text = "My text data goes here";
}
O DragStartingEventArgs
objeto que acompanha o DragStarting
evento tem uma Data
propriedade, do tipo DataPackage
. Neste exemplo, a Text
DataPackage
propriedade do objeto é definida como um string
arquivo . O DataPackage
pode então ser acessado em drop, para recuperar o string
.
Armazenar dados no pacote de propriedades
Todos os dados, incluindo imagens e texto, podem ser associados a uma fonte de arrastar armazenando os dados na DataPackage.Properties
coleção. Isso pode ser realizado no manipulador do DragStarting
evento.
O exemplo XAML a seguir mostra um DragGestureRecognizer
que registra um manipulador para o DragStarting
evento:
<Rectangle Stroke="Red"
Fill="DarkBlue"
StrokeThickness="4"
HeightRequest="200"
WidthRequest="200">
<Rectangle.GestureRecognizers>
<DragGestureRecognizer DragStarting="OnDragStarting" />
</Rectangle.GestureRecognizers>
</Rectangle>
Neste exemplo, o é anexado DragGestureRecognizer
a um Rectangle
objeto. O DragStarting
evento é disparado quando um gesto Rectangle
de arrastar é detectado no , que executa o OnDragStarting
manipulador de eventos:
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));
}
O DragStartingEventArgs
objeto que acompanha o DragStarting
evento tem uma Data
propriedade, do tipo DataPackage
. A Properties
coleção do DataPackage
objeto, que é uma Dictionary<string, object>
coleção, pode ser modificada para armazenar quaisquer dados necessários. Neste exemplo, o Properties
dicionário é modificado para armazenar um Square
objeto, que representa o tamanho do , em relação a Rectangle
uma chave "Square".
Ativar drop
No Xamarin.Forms, o reconhecimento de gestos DropGestureRecognizer
de queda é fornecido pela classe. Essa classe define as seguintes propriedades:
AllowDrop
, do tipobool
, que indica se o elemento ao qual o reconhecedor de gestos está anexado pode ser um destino de soltar. O valor padrão dessa propriedade étrue
.DragOverCommand
, do tipoICommand
, que é executado quando a origem de arrastar é arrastada sobre o destino de soltar.DragOverCommandParameter
, do tipoobject
, que é o parâmetro passado paraDragOverCommand
.DragLeaveCommand
, do tipoICommand
, que é executado quando a origem de arrastar é arrastada para fora do destino de soltar.DragLeaveCommandParameter
, do tipoobject
, que é o parâmetro passado paraDragLeaveCommand
.DropCommand
, do tipoICommand
, que é executado quando a origem de arrastar é solta sobre o destino de soltar.DropCommandParameter
, do tipoobject
, que é o parâmetro passado paraDropCommand
.
Essas propriedades são apoiadas por objetos BindableProperty
, o que significa que podem ser alvos de associações de dados e ser estilizada.
A DropGestureRecognizer
classe também define DragOver
, DragLeave
e Drop
eventos que disparam desde que a AllowDrop
propriedade seja true
. Quando um DropGestureRecognizer
reconhece uma origem de arrastar sobre o destino de soltar, ele executa o DragOverCommand
e invoca o DragOver
evento. Em seguida, se a origem de arrastar for arrastada para fora do destino de soltar, o DropGestureRecognizer
executará o DragLeaveCommand
e invocará o DragLeave
evento. Finalmente, quando o reconhece um gesto DropGestureRecognizer
de soltar sobre o destino de soltar, ele executa o DropCommand
e invoca o Drop
evento.
A DragEventArgs
classe, que acompanha os DragOver
eventos e DragLeave
define as seguintes propriedades:
Data
, do tipoDataPackage
, que contém os dados associados à origem de arraste. Esta propriedade é somente para leitura.AcceptedOperation
, do tipoDataPackageOperation
, que especifica quais operações são permitidas pelo destino de descarte.
Para obter informações sobre a DataPackageOperation
enumeração, consulte Manipular o evento DragOver.
A DropEventArgs
classe que acompanha o Drop
evento define as seguintes propriedades:
Data
, do tipoDataPackageView
, que é uma versão somente leitura do pacote de dados.Handled
, do tipobool
, indica se o manipulador de eventos manipulou o evento ou se Xamarin.Forms deve continuar seu próprio processamento.
O exemplo XAML a seguir mostra um DropGestureRecognizer
anexado a um Image
:
<Image BackgroundColor="Silver"
HeightRequest="300"
WidthRequest="250">
<Image.GestureRecognizers>
<DropGestureRecognizer />
</Image.GestureRecognizers>
</Image>
Neste exemplo, quando uma origem de arrastar é solta no Image
destino de soltar, a fonte de arrastar será copiada para o destino de soltar, desde que a origem de arrastar seja um ImageSource
arquivo . Isso ocorre porque Xamarin.Forms copia automaticamente imagens arrastadas e texto para destinos de soltar compatíveis.
Manipular o evento DragOver
O DropGestureRecognizer.DragOver
evento pode ser opcionalmente manipulado para indicar que tipo de operações são permitidas pelo destino de descarte. Isso pode ser feito definindo a AcceptedOperation
propriedade, do tipo DataPackageOperation
, do DragEventArgs
objeto que acompanha o DragOver
evento.
A enumeração DataPackageOperation
define os seguintes membros:
None
, indica que nenhuma ação será executada.Copy
, indica que o conteúdo de origem de arrastar será copiado para o destino de soltar.
Importante
Quando um DragEventArgs
objeto é criado, o padrão da AcceptedOperation
propriedade é DataPackageOperation.Copy
.
O exemplo XAML a seguir mostra um DropGestureRecognizer
que registra um manipulador para o DragOver
evento:
<Image BackgroundColor="Silver"
HeightRequest="300"
WidthRequest="250">
<Image.GestureRecognizers>
<DropGestureRecognizer DragOver="OnDragOver" />
</Image.GestureRecognizers>
</Image>
Neste exemplo, o é anexado DropGestureRecognizer
a um Image
objeto. O DragOver
evento é acionado quando uma origem de arrastar é arrastada sobre o destino de soltar, mas não foi solta, o que executa o OnDragOver
manipulador de eventos:
void OnDragOver(object sender, DragEventArgs e)
{
e.AcceptedOperation = DataPackageOperation.None;
}
Neste exemplo, a AcceptedOperation
DragEventArgs
propriedade do objeto é definida como DataPackageOperation.None
. Isso garante que nenhuma ação seja executada quando uma fonte de arrastar é solta sobre o destino de soltar.
Processar o pacote de dados
O Drop
evento é acionado quando uma fonte de arraste é liberada sobre um destino de soltar. Quando isso ocorrer, Xamarin.Forms tentará recuperar automaticamente dados do pacote de dados, quando uma fonte de arrastar for solta nos seguintes controles:
- Controles de texto. Os valores de texto podem ser descartados em
CheckBox
objetos ,DatePicker
,Editor
,Entry
,Label
,RadioButton
,Switch
eTimePicker
. - Controles de imagem. As imagens podem ser soltas no
Button
,Image
eImageButton
nos controles.
A tabela a seguir mostra as propriedades definidas e qualquer conversão tentada quando uma fonte de arrastar baseada em texto é solta em um controle de texto:
Controle | Propriedade | Conversão |
---|---|---|
CheckBox |
IsChecked |
string é convertido em um bool arquivo . |
DatePicker |
Date |
string é convertido em um DateTime arquivo . |
Editor |
Text |
|
Entry |
Text |
|
Label |
Text |
|
RadioButton |
IsChecked |
string é convertido em um bool arquivo . |
Switch |
IsToggled |
string é convertido em um bool arquivo . |
TimePicker |
Time |
string é convertido em um TimeSpan arquivo . |
Para conteúdo diferente de texto e imagens, você mesmo precisará processar o pacote de dados.
A DropEventArgs
classe que acompanha o Drop
evento define uma Data
propriedade, do tipo DataPackageView
. Essa propriedade representa uma versão somente leitura do pacote de dados.
Recuperar dados de imagem ou texto
Os dados de imagem ou texto podem ser recuperados de um pacote de dados no manipulador Drop
do evento, usando métodos definidos na DataPackageView
classe.
A DataPackageView
classe inclui GetImageAsync
e GetTextAsync
métodos. O GetImageAsync
método recupera uma imagem do pacote de dados, que foi armazenada na DataPackage.Image
propriedade, e retorna Task<ImageSource>
. Da mesma forma, o GetTextAsync
método recupera texto do pacote de dados, que foi armazenado na DataPackage.Text
propriedade, e retorna Task<string>
.
O exemplo a seguir mostra um Drop
manipulador de eventos que recupera texto do pacote de dados para um Path
:
async void OnDrop(object sender, DropEventArgs e)
{
string text = await e.Data.GetTextAsync();
// Perform logic to take action based on the text value.
}
Neste exemplo, os dados de texto são recuperados do pacote de dados usando o GetTextAsync
método. Uma ação com base no valor do texto pode então ser executada.
Recuperar dados do pacote de propriedades
Todos os dados podem ser recuperados de um pacote de dados no manipulador Drop
do evento, acessando a Properties
coleção do pacote de dados.
A DataPackageView
classe define uma Properties
propriedade, do tipo DataPackagePropertySetView
. A DataPackagePropertySetView
classe representa um conjunto de propriedades somente leitura armazenado como um Dictionary<string, object>
arquivo .
O exemplo a seguir mostra um Drop
manipulador de eventos que recupera dados do conjunto de propriedades de um pacote de dados para um Rectangle
:
void OnDrop(object sender, DropEventArgs e)
{
Square square = (Square)e.Data.Properties["Square"];
// Perform logic to take action based on retrieved value.
}
Neste exemplo, o Square
objeto é recuperado do conjunto de propriedades do pacote de dados, especificando a chave de dicionário "Square". Uma ação baseada no valor recuperado pode então ser executada.