Partilhar 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 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 tem suporte no iOS, Android e na Plataforma Universal do Windows (UWP). No entanto, no iOS, é necessária uma plataforma mínima de iOS 11.

A origem do gesto de arrastar, 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 do gesto de arrastar é liberada, o item é solto. O destino do gesto de soltar, que é o elemento sob a origem do gesto de arrastar, processa o pacote de dados.

O processo para habilitar arrastar e soltar em um aplicativo é o seguinte:

  1. Habilite arrastar um elemento adicionando um objeto DragGestureRecognizer à sua coleção GestureRecognizers. Para obter mais informações, confira 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 outros conteúdos você precisará construir seu próprio pacote de dados. Para obter mais informações, confira Criar um pacote de dados.
  3. Habilite a queda em um elemento adicionando um DropGestureRecognizer objeto à sua GestureRecognizers coleção. Para obter mais informações, confira Habilitar soltar.
  4. [opcional] Manipule o evento DropGestureRecognizer.DragOver para indicar o tipo de operação permitido pelo destino de soltar. Para obter mais informações, confira 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 outros conteúdos, você precisará processar o pacote de dados. Para obter mais informações, confira Processar o pacote de dados.

Observação

No momento, não há suporte para arrastar itens de e para a CollectionView .

Habilitar o gesto de arrastar

Em 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 arrastar. 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 origem do gesto de arrastar é 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 são acionados, desde que a CanDrag propriedade seja true. Quando um objeto DragGestureRecognizer detecta um gesto de arrastar, ele executa DragStartingCommand e invoca o evento DragStarting. Em seguida, quando o objeto DragGestureRecognizer detecta a conclusão de um gesto de soltar, ele executa DropCompletedCommand e invoca o evento DropCompleted.

O objeto DragStartingEventArgs que acompanha o evento DragStarting 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 fonte de arrastar. 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 de arrastar pode ser iniciado no Image.

Dica

No iOS, Android e UWP, um gesto de arrastar é iniciado com um toque longo seguido por um arrasto.

Criar um pacote de dados

Xamarin.Forms criará automaticamente um pacote de dados para você, quando um arrasto for iniciado, para os seguintes controles:

A tabela a seguir mostra as propriedades que são lidas e qualquer tentativa de conversão que seja feita quando um gesto de 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ê precisará criar um pacote de dados por conta própria.

Os pacotes de dados são representados pela classe DataPackage, que define as seguintes propriedades:

  • Properties, do tipo DataPackagePropertySet, que é uma coleção de propriedades que compreendem os dados contidos no DataPackage. Esta propriedade é uma 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 classe DataPackagePropertySet representa um conjunto de propriedades armazenado como um Dictionary<string,object>. Para obter informações sobre a classe DataPackageView, confira Processar o pacote de dados.

Armazenar dados de imagem ou texto

Dados de imagem ou texto podem ser associados a uma fonte de arrastar armazenando os dados na propriedade DataPackage.Image ou DataPackage.Text. Isso pode ser feito no manipulador do DragStarting evento.

O exemplo XAML a seguir mostra um DragGestureRecognizer que registra um manipulador para o evento DragStarting:

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

Neste exemplo, a origem DragGestureRecognizer é anexada a um objeto Path. O DragStarting evento é acionado quando um gesto de arrastar é detectado Pathno , que executa o OnDragStarting manipulador de eventos:

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

O objeto DragStartingEventArgs que acompanha o evento DragStarting tem uma propriedade Data, do tipo DataPackage. Neste exemplo, a propriedade Text do objeto DataPackage é definida como um string. Em seguida, o DataPackage pode ser acessado na lista suspensa, para recuperar o string.

Armazenar dados no conjunto de propriedades

Todos os dados, incluindo imagens e texto, podem ser associados a uma origem de gesto de arrastar armazenando os dados na coleção DataPackage.Properties. Isso pode ser feito no manipulador do DragStarting evento.

O exemplo XAML a seguir mostra um DragGestureRecognizer que registra um manipulador para o evento DragStarting:

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

Neste exemplo, a origem DragGestureRecognizer é anexada a um objeto Rectangle. O DragStarting evento é acionado quando um gesto de arrastar é detectado Rectangleno , 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 objeto DragStartingEventArgs que acompanha o evento DragStarting tem uma propriedade Data, do tipo DataPackage. A coleção Properties do objeto DataPackage, que é uma coleção Dictionary<string, object>, pode ser modificada para armazenar todos os 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 "Quadrado".

Habilitar o gesto de soltar

Em Xamarin.Forms, o reconhecimento de gestos DropGestureRecognizer de soltar é 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 para 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, DragLeave, e Drop eventos que são acionados desde que a AllowDrop propriedade seja true. Quando um DropGestureRecognizer reconhece uma origem de gesto de arrastar sobre o destino do gesto de soltar, ele executa DragOverCommand e invoca o evento DragOver. Em seguida, se a origem do gesto de arrastar for arrastada para fora do destino do gesto de soltar, DropGestureRecognizer executará DragLeave e invocará o evento DragLeaveCommand. Por fim, quando DropGestureRecognizer o reconhece um gesto de soltar sobre o destino do gesto de soltar, ele executa DropCommand e invoca o evento Drop.

A DragEventArgs classe, que acompanha os DragOver eventos and DragLeave , define as seguintes propriedades:

  • Data, do tipo DataPackage, que contém os dados associados à fonte de arrastar. Esta propriedade é somente para leitura.
  • AcceptedOperation, do tipo DataPackageOperation, que especifica quais operações são permitidas pelo destino de soltar.

Para obter informações sobre a enumeração DataPackageOperation, confira Manipular o evento DragOver.

A classe DropEventArgs que acompanha o evento Drop 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 origem de arrastar será copiada para o destino de soltar, desde que a origem de arrastar seja um ImageSource. Isso ocorre porque Xamarin.Forms copia automaticamente as imagens arrastadas e o texto para destinos de soltura compatíveis.

Manipular o evento DragOver

O evento DropGestureRecognizer.DragOver pode ser tratado opcionalmente para indicar quais tipos de operações são permitidas pelo destino de soltar. 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 da origem de arrastar será copiado para o destino de soltar.

Importante

Quando um objeto DragEventArgs é criado, a propriedade AcceptedOperation usa como padrão DataPackageOperation.Copy.

O exemplo XAML a seguir mostra um DropGestureRecognizer que registra um manipulador para o evento DragOver:

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

Neste exemplo, DropGestureRecognizer é anexado a um objeto Image. O DragOver evento é acionado quando uma fonte 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 propriedade AcceptedOperation do objeto DragEventArgs é definida como DataPackageOperation.None. Isso garante que nenhuma ação seja executada quando uma fonte de arrastar for solta sobre o destino de soltar.

Processar o pacote de dados

O Drop evento é acionado quando uma fonte de arrastar é liberada sobre um destino de soltar. Quando isso ocorrer, Xamarin.Forms tentará recuperar automaticamente os 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 tentativa de conversão 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.
DatePicker Date string é convertido em um DateTime.
Editor Text
Entry Text
Label Text
RadioButton IsChecked string é convertido em um bool.
Switch IsToggled string é convertido em um bool.
TimePicker Time string é convertido em um TimeSpan.

Para conteúdo diferente de texto e imagens, você precisará processar o pacote de dados por conta própria.

A classe DropEventArgs que acompanha o evento Drop define uma propriedade Data, do tipo DataPackageView. Esta propriedade representa uma versão somente leitura do pacote de dados.

Recuperar dados de imagem ou texto

Dados de imagem ou texto podem ser recuperados de um pacote de dados no manipulador do evento Drop, usando métodos definidos na classe DataPackageView.

A classe DataPackageView inclui métodos GetImageAsync e GetTextAsync. O GetImageAsync método recupera uma imagem do pacote de dados, que foi armazenada DataPackage.Image na propriedade, e retorna Task<ImageSource>. Da mesma forma, o GetTextAsync método recupera o texto do pacote de dados, que foi armazenado na DataPackage.Text propriedade, e retorna Task<string>.

O exemplo a seguir mostra um manipulador de eventos Drop que recupera o 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 método GetTextAsync. Uma ação com base no valor de texto pode ser executada.

Recuperar dados do recipiente de propriedades

Todos os dados podem ser recuperados de um pacote de dados no manipulador do evento Drop acessando a coleção Properties do pacote de dados.

A classe DataPackageView define uma propriedade, Properties do tipo DataPackagePropertySetView. A classe DataPackagePropertySetView representa um conjunto de propriedades somente leitura armazenado como um Dictionary<string, object>.

O exemplo a seguir mostra um manipulador de eventos Drop que recupera dados do recipiente 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 objeto Square é recuperado do conjunto de propriedades do pacote de dados, especificando à chave de dicionário "Square". Uma ação com base no valor recuperado pode ser executada.