Compartilhar via

Adicionar reconhecedores de gestos de arrastar e soltar

  • Artigo

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:

  1. Habilite arrastar em um elemento adicionando um DragGestureRecognizer objeto à sua GestureRecognizers coleção. Para obter mais informações, consulte Habilitar arrastar.
  2. [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.
  3. Habilite soltar em um elemento adicionando um DropGestureRecognizer objeto à sua GestureRecognizers coleção. Para obter mais informações, consulte Habilitar drop.
  4. [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.
  5. [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 tipo bool, 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 tipo ICommand, que é executado quando um gesto de arrastar é reconhecido pela primeira vez.
  • DragStartingCommandParameter, do tipo object, que é o parâmetro passado para DragStartingCommand.
  • DropCompletedCommand, do tipo ICommand, que é executado quando a fonte de arraste é solta.
  • DropCompletedCommandParameter, do tipo object, que é o parâmetro passado para DropCompletedCommand.

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 tipo bool, indica se o manipulador de eventos manipulou o evento ou se Xamarin.Forms deve continuar seu próprio processamento.
  • Cancel, do tipo bool, indica se o evento deve ser cancelado.
  • Data, do tipo DataPackage, 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 Imagede 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:

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 tipo DataPackagePropertySet, que é uma coleção de propriedades que compõem os dados contidos no DataPackage. Esta propriedade é somente leitura.
  • Image, do tipo ImageSource, que é a imagem contida no DataPackage.
  • Text, do tipo string, que é o texto contido no DataPackage.
  • View, do tipo DataPackageView, que é uma versão somente leitura do DataPackage.

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 Pathde 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 TextDataPackage propriedade do objeto é definida como um stringarquivo . 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 Rectanglede 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 Rectangleuma 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 tipo bool, 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 tipo ICommand, que é executado quando a origem de arrastar é arrastada sobre o destino de soltar.
  • DragOverCommandParameter, do tipo object, que é o parâmetro passado para DragOverCommand.
  • DragLeaveCommand, do tipo ICommand, que é executado quando a origem de arrastar é arrastada para fora do destino de soltar.
  • DragLeaveCommandParameter, do tipo object, que é o parâmetro passado para DragLeaveCommand.
  • DropCommand, do tipo ICommand, que é executado quando a origem de arrastar é solta sobre o destino de soltar.
  • DropCommandParameter, do tipo object, que é o parâmetro passado para DropCommand.

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, DragLeavee 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 tipo DataPackage, que contém os dados associados à origem de arraste. Esta propriedade é somente para leitura.
  • AcceptedOperation, do tipo DataPackageOperation, 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 tipo DataPackageView, que é uma versão somente leitura do pacote de dados.
  • Handled, do tipo bool, 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 ImageSourcearquivo . 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 AcceptedOperationDragEventArgs 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:

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 boolarquivo .
DatePicker Date string é convertido em um DateTimearquivo .
Editor Text
Entry Text
Label Text
RadioButton IsChecked string é convertido em um boolarquivo .
Switch IsToggled string é convertido em um boolarquivo .
TimePicker Time string é convertido em um TimeSpanarquivo .

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.