A API HTML5 Drag and Drop

Esta postagem explica os conceitos básicos do recurso de arrastar e soltar.

Eric Bidelman

Rachel Andrew

Criar conteúdo arrastável

Na maioria dos navegadores, seleções de texto, imagens e links são arrastáveis por padrão. Por exemplo, se você arrastar um link em uma página da Web, verá uma pequena caixa com um título e URL que você pode colocar na barra de endereço ou na área de trabalho para criar uma ou navegue até o link. Para tornar outros tipos de conteúdo arrastáveis, você precisa usar as APIs de arrastar e soltar de HTML5.

Para tornar um objeto arrastável, defina draggable=true nesse elemento. Quase qualquer coisa pode ser arrastada, incluindo imagens, arquivos, links, arquivos ou qualquer na sua página.

O exemplo a seguir cria uma interface para reorganizar colunas que foram dispostos com a grade CSS. A marcação básica para as colunas é assim, com o atributo draggable para cada coluna definida como true:

<div class="container">
  <div draggable="true" class="box">A</div>
  <div draggable="true" class="box">B</div>
  <div draggable="true" class="box">C</div>
</div>

Este é o CSS para os elementos de contêiner e caixa. O único CSS relacionado o recurso de arrastar é o cursor: move . O restante do código controla o layout e o estilo do contêiner e de caixa.

.container {
  display: grid;
  grid-template-columns: repeat(5, 1fr);
  gap: 10px;
}

.box {
  border: 3px solid #666;
  background-color: #ddd;
  border-radius: .5em;
  padding: 10px;
  cursor: move;
}

Nesse ponto, é possível arrastar os itens, mas nada mais acontece. Para adicionar será necessário usar a API JavaScript.

Detectar eventos de arrastar

Para monitorar o processo de arrastar, você pode detectar qualquer um dos seguintes eventos:

• dragstart
• drag
• dragenter
• dragleave
• dragover
• drop
• dragend

Para processar o fluxo de arrastar, você precisa de algum tipo de elemento de origem (em que a ação a carga de dados (a coisa que está sendo arrastada) e um alvo (uma área para pegue a queda). O elemento de origem pode ser quase qualquer tipo de elemento. A o destino é a zona ou conjunto de zonas de soltar que aceita os dados que o usuário está tentando abandonar. Nem todos os elementos podem ser alvos. Por exemplo, seu destino não pode ser uma imagem.

Iniciar e terminar uma sequência de arrastar

Depois de definir os atributos draggable="true" no seu conteúdo, anexe um manipulador de eventos dragstart para iniciar a sequência de arrastar para cada coluna.

Esse código define a opacidade da coluna em 40% quando o usuário começa a arrastá-la, e retorne-a para 100% quando o evento de arrastar terminar.

function handleDragStart(e) {
  this.style.opacity = '0.4';
}

function handleDragEnd(e) {
  this.style.opacity = '1';
}

let items = document.querySelectorAll('.container .box');
items.forEach(function (item) {
  item.addEventListener('dragstart', handleDragStart);
  item.addEventListener('dragend', handleDragEnd);
});

Confira o resultado na demonstração do Glitch abaixo. Arraste um item e seu alterações de opacidade. Como o elemento de origem tem o evento dragstart, definir this.style.opacity a 40% dá ao usuário um feedback visual de que o elemento é a seleção atual que está sendo movida. Quando você solta o item, o elemento de origem retorna à opacidade de 100%, mesmo que você ainda não tenha definido o comportamento de soltar.

Adicionar outros elementos visuais

Para ajudar o usuário a entender como interagir com sua interface, use o Manipuladores de eventos dragenter, dragover e dragleave. Neste exemplo, as colunas são, além de serem arrastáveis, destinos de soltar. Ajude o usuário a entender isso fazendo a borda tracejada ao segurar um item arrastado sobre uma . Por exemplo, no seu CSS, é possível criar uma classe over para elementos que são destinos de soltar:

.box.over {
  border: 3px dotted #666;
}

Em seguida, em seu JavaScript, configure os manipuladores de eventos, adicione a classe over quando a coluna é arrastada e a remove quando o elemento arrastado sai. Em no gerenciador dragend, também não deixamos de remover as classes no final do arrastar.

document.addEventListener('DOMContentLoaded', (event) => {

  function handleDragStart(e) {
    this.style.opacity = '0.4';
  }

  function handleDragEnd(e) {
    this.style.opacity = '1';

    items.forEach(function (item) {
      item.classList.remove('over');
    });
  }

  function handleDragOver(e) {
    e.preventDefault();
    return false;
  }

  function handleDragEnter(e) {
    this.classList.add('over');
  }

  function handleDragLeave(e) {
    this.classList.remove('over');
  }

  let items = document.querySelectorAll('.container .box');
  items.forEach(function(item) {
    item.addEventListener('dragstart', handleDragStart);
    item.addEventListener('dragover', handleDragOver);
    item.addEventListener('dragenter', handleDragEnter);
    item.addEventListener('dragleave', handleDragLeave);
    item.addEventListener('dragend', handleDragEnd);
    item.addEventListener('drop', handleDrop);
  });
});

Há alguns pontos que valem a pena abordar neste código:

• A ação padrão para o evento dragover é definir a propriedade dataTransfer.dropEffect como "none". A propriedade dropEffect será abordada mais adiante nesta página. Por enquanto, mas isso impede que o evento drop seja disparado. Para substituir isso comportamento, chame e.preventDefault(). Outra boa prática é retornar false no mesmo gerenciador.

• O manipulador de eventos dragenter é usado para alternar a classe over em vez de dragover Se você usar dragover, o evento será disparado repetidamente enquanto o usuário mantém o item arrastado sobre uma coluna, fazendo com que a classe CSS alterne repetidamente. Isso faz com que o navegador realize muito trabalho de renderização desnecessário, o que pode afetar a experiência do usuário. Recomendamos minimizar é redesenhado e, se você precisar usar dragover, considere limitando ou devolvendo o listener de eventos.

Concluir o lançamento

Para processar a ação de soltar, adicione um listener para o evento drop. No drop é necessário impedir o comportamento padrão do navegador para quedas, o que costuma ser algum tipo de redirecionamento irritante. Para fazer isso, chame e.stopPropagation().

function handleDrop(e) {
  e.stopPropagation(); // stops the browser from redirecting.
  return false;
}

Registre o novo gerenciador junto com os outros gerenciadores:

  let items = document.querySelectorAll('.container .box');
  items.forEach(function(item) {
    item.addEventListener('dragstart', handleDragStart);
    item.addEventListener('dragover', handleDragOver);
    item.addEventListener('dragenter', handleDragEnter);
    item.addEventListener('dragleave', handleDragLeave);
    item.addEventListener('dragend', handleDragEnd);
    item.addEventListener('drop', handleDrop);
  });

Se você executar o código nesse ponto, o item não será entregue ao novo local. Para fazer isso acontecer, use o DataTransfer objeto.

A propriedade dataTransfer contém os dados enviados em uma ação de arrastar. dataTransfer é definido no evento dragstart e lido ou processado no evento de soltar. Ligando e.dataTransfer.setData(mimeType, dataPayload) permite definir o código MIME do objeto tipo e payload de dados.

Neste exemplo, vamos permitir que os usuários reorganizem a ordem das colunas. Para fazer isso, primeiro é necessário armazenar o HTML do elemento de origem quando a ação de arrastar começa em:

function handleDragStart(e) {
  this.style.opacity = '0.4';

  dragSrcEl = this;

  e.dataTransfer.effectAllowed = 'move';
  e.dataTransfer.setData('text/html', this.innerHTML);
}

No evento drop, processe a queda da coluna definindo o objeto HTML para o HTML da coluna de destino na qual você soltou os dados. Isso inclui verificar se o usuário não está retornando para a mesma coluna arrastado.

function handleDrop(e) {
  e.stopPropagation();

  if (dragSrcEl !== this) {
    dragSrcEl.innerHTML = this.innerHTML;
    this.innerHTML = e.dataTransfer.getData('text/html');
  }

  return false;
}

Confira o resultado na demonstração a seguir. Para que isso funcione, você precisará de um navegador para computador. A API Drag and Drop não é compatível com dispositivos móveis. Arrastar e solte a coluna A na parte superior da coluna B e observe como elas mudam de lugar:

Mais propriedades de arrastar

O objeto dataTransfer expõe propriedades para fornecer feedback visual para o usuário durante o processo de arrastar e controlar como cada destino de soltar responde a uma tipo de dado específico.

• dataTransfer.effectAllowed que restringe o "tipo de ação de arrastar" que o usuário pode realizar no elemento. Ela é usada no modelo de processamento de arrastar e soltar para inicializar o dropEffect durante os eventos dragenter e dragover. A propriedade pode ter o parâmetro seguintes valores: none, copy, copyLink, copyMove, link, linkMove, move, all e uninitialized.
• dataTransfer.dropEffect controla o feedback que o usuário recebe durante dragenter e dragover eventos. Quando o usuário mantém o ponteiro sobre um elemento de destino, o método cursor indica que tipo de operação vai ocorrer, como uma cópia ou um movimento. O efeito pode ter um dos seguintes valores: none, copy, link (move)
• e.dataTransfer.setDragImage(imgElement, x, y) significa que, em vez de usar a "imagem fantasma" padrão do navegador, feedback, você é possível definir um ícone de arrastar.

Upload de arquivo

Este exemplo simples usa uma coluna como origem e destino da ação de arrastar. Isso pode acontecer em uma IU que solicita que o usuário reorganize os itens. Em algumas situações, o destino e a origem da ação de arrastar podem ser tipos de elementos diferentes, como em uma interface em que o usuário precisa selecionar uma imagem como a principal de um produto, arrastando a imagem selecionada até um alvo.

O recurso de arrastar e soltar é usado com frequência para permitir que os usuários arrastem itens da área de trabalho para um aplicativo. A principal diferença está no gerenciador drop. Em vez de usar dataTransfer.getData() para acessar os arquivos, os dados estão contidos na Propriedade dataTransfer.files:

function handleDrop(e) {
  e.stopPropagation(); // Stops some browsers from redirecting.
  e.preventDefault();

  var files = e.dataTransfer.files;
  for (var i = 0, f; (f = files[i]); i++) {
    // Read the File objects in this FileList.
  }
}

Você pode encontrar mais informações sobre isso em Arrastar e soltar personalizados.

Mais recursos

• A especificação para arrastar e soltar
• API MDN HTML Drag and Drop
• Como criar um app de envio de arquivos com o recurso de arrastar e soltar usando o JavaScript Vanilla
• Como criar um jogo de estacionamento com a API HTML Drag and Drop
• Como usar a API HTML Drag-and-Drop no React