Arrastar e soltar

As interfaces de Drag and Drop (arrastar e soltar) habilitam aplicações a usar funcionalidades de arrastar e soltar através do navegador. Por exemplo, com essas funcionalidades, o usuário pode selecionar elementos arrastáveis (draggable) com o mouse, arrastar elementos até um elemento soltável (droppable), e soltar o elemento ao soltar o botão do mouse. Uma representação translúcida de elementos arrastáveis (draggable) seguem o ponteiro do mouse durante a operação de arrastar (drag).

Para web sites, extensões e aplicações XUL, você pode customizar os tipos de elementos que podem se tornar arrastáveis (draggable) e o tipo de retorno que o elemento arrastável produz, assim como os elementos soltáveis (droppable).

NT: Para manter a tradução mais precisa e coesa, a partir daqui iremos manter os termos drag e drop e seus variantes conforme texto original. Sendo portanto mantidos também os termos draggable e droppable.

Este documento é uma visão geral do drag and drop no HTML. Ele inclui uma descrição de suas interfaces, funcionalidades básicas de como permitir a adesão de funcionalidades arrastar e soltar em uma aplicação e um sumário da interoperabilidade entre interfaces.

Eventos Drag

O drag and drop em HTML usa o modelo de eventos DOM e os eventos drag são hereditários dos eventos do mouse. Uma operação típica de drag começa quando o usuário seleciona um elemento arrastável com o mouse, move o mouse até um elemento soltável (droppable) e solta o mouse. Durante as operações, diversos tipos de evento são acionados e alguns podem até ser acionados multiplas vezes (como por exemplo os tipos de evento drag e dragover.

Todos os tipos de evento drag são associados a um manipulador global de eventos. Cada tipo de evento drag e cada atributo drag global tem um documento de referência que o descreve. A tabela a seguir descreve brevemente os tipos de evento e um link de referência para seu documento.

Event	On Event Handler	Description
`drag`	`ondrag`	Acionado quando um elemento ou seleção de texto está sendo arrastado.
`dragend`	`ondragend`	Acionado quando uma operação de arrastar está terminando (por eexmplo, ao soltar o botão do mouse ou pressionar a tecla esc). (Veja Terminando um evento Drag.)
`dragenter`	`ondragenter`	Acionado quando um elemento arrastável ou seleção de texto entra em um ponto de soltura (drop target). (Veja Determinando Drop Targets.)
`dragexit`	`ondragexit`	Acionado quando um elemento não é mais o ponto de seleção imediata da operação drag.
`dragleave`	`ondragleave`	Acionado quando um elemento arrastável ou seleção de texto abandona um ponto de soltura (drop target) válido.
`dragover`	`ondragover`	Acionado quando um elemento ou seleção de texto está sendo arrastado sobre um ponto de soltura válido (a cada aproximadamente 100 milisegundos).
`dragstart`	`ondragstart`	Acionado quando o usuário começa a arrastar um elemento válido ou seleção de texto. (Veja Começando uma Operação Drag.)
`drop`	`ondrop`	Acionado quando um elemento ou seleção de texto é solta em um ponto d soltura (drop target) válido. (Veja Realizando um Drop.)

Note que eventos dragstart e dragend não são acionados ao arrastar um arquivo vindo do sistema operacional para o navegador.

Interfaces

A interface HTML drag and drop é composta pelos eventos DragEvent, DataTransfer, DataTransferItem e DataTransferItemList.

A interface DragEvent consiste de um construtor e uma propriedade, a propriedade dataTransfer que é um objeto DataTransfer. Os objetos DataTransfer incluem estados do evento drag como o tipo de drag sendo feito (por exemplo copy ou move), os dados do do evento drag (um ou mais itens) e o tipo de cada item drag (um MIME type). Objetos DataTransfer também contém métodos para adicionar itens aos dados do drag e remover um item. As interfaces DragEvent e DataTransfer devem as únicas necessárias para adicionar capacidades de drag and drop para uma aplicação. Entretanto, note que o Firefox provê suporte para apenas algumas Gecko-specific extensions ao objeto DataTransfer, apesar de entretanto essas extensões funcionarem apenas no Firefox.

Cada objeto DataTransfer contém uma propriedade items que é uma lista dos objetos DataTransferItem. Cada objeto DataTransferItem representa um único drag item e cada item tem uma propriedade kind (tipo) que é o tipo(kind) de data (seja ela string ou file) e uma propriedade type (tipo) que é o tipo de dado do item (ou seja, MIME type). O objeto DataTransferItem também contém métodos para conseguir dados do item arrastável.

O objeto DataTransferItemList é uma lista de objetos DataTransferItem. A lista de objetos contém métodos para: adicionar um item para uma lista, remover um item de uma lista e limpar a lista com todos os itens.

A diferença chave entre das interfaces DataTransfer e DataTransferItem é que a primeira usa o método síncrono getData() para acessar os dados de um item arrastável, e a segunda usa o método assíncrono getAsString() para acessá-lo.

Note: as interfaces DragEvent e a DataTransfer são vastamente interoperáveis com navegadores desktop. Entretanto, as interfaces DataTransferItem e DataTransferItemList tem suporte limitado entre navegadores. Veja Interoperabildade para mais informações.

Interfaces específicas para o Gecko

A Mozilla e o Firefox suportam algumas funcionalidades fora dos padrões do modelo drag and drop. Elas são cfunções convenientes para facilitar o arraste múltiplo de elementos e a manipulação de dados que não são strings (como arquivos). Para mais informações, veja Dragging and Dropping Multiple Items. Para mais informações, veja a página de referência DataTransfer para todas as propriedades específicas para o Gecko e Métodos específicos para o Gecko.

O básico

Esta seção dispõe de um resumo das etapas básicas para adicionar a funcionalidade drag and drop à uma aplicação. Cada seção inclui uma descrição da etapa, um breve exemplo em código, e links para informações adicionais.

Identificando o que é arrastável (draggable)

Para fazer um elemento se tornar arrastável, é necessária a adição de um atributo draggable além da adição do manipulador de eventos global ondragstart, conforme descrito no exemplo a seguir

function dragstart_handler(ev) {
  console.log("dragStart");
  // Adiciona o id do elemento em questão ao objeto de transferência de dados (dataTransfer)
  ev.dataTransfer.setData("text/plain", ev.target.id);
}

html

<body>
  <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">
    Este elemento é arrastável.
  </p>
</body>

Veja a referência do atributo draggable e o Guia de operações drag para mais informações.

Defina os dados do drag

A aplicação é livre para incluir qualquer quantidade de dados do item em uma operação drag. Cada dado de um item é uma string de um tipo particular, tipicamente um MIME type como por exemplo text/html.

Cada evento drag tem uma propriedade dataTransfer que segura os dados do evento. Essa propridade (que é um objeto DataTransfer) também tem um método para gerenciar os dados do arraste (drag). O método setData() é usado para adicionar um item aos dados do arraste, como demonstrado no exemplo a seguir.

function dragstart_handler(ev) {
  // Adiciona os dados do arraste (drag)
  ev.dataTransfer.setData("text/plain", ev.target.id);
  ev.dataTransfer.setData("text/html", "<p>Parágrafo de exemplo</p>");
  ev.dataTransfer.setData("text/uri-list", "http://developer.mozilla.org");
}

Para uma lista de tipos de dados mais comuns utilizados pelo drag and drop (como texto, HTML, links, e files), veja Tipos recomendados de Drag Types e para mais informações sobre os dados do arraste (drag data), veja Drag Data.

Defina uma imagem de arraste (drag image)

Por padrão, o navegador provê uma imagem que aparece por trás do ponteiro do mouse durante uma operação de arraste. Entretanto, uma aplicação pode definir uma imagem customizada utilizando o método setDragImage() como demonstrado no exemplo a seguir.

function dragstart_handler(ev) {
  // Cria uma imagem e então a utiliza como a "drag image".
  // NOTA: mude "example.gif" como uma imagem existente, caso contrário
  // ela não será criada e a imagem padrão será utilizada como padrão.
  var img = new Image();
  img.src = "example.gif";
  ev.dataTransfer.setDragImage(img, 10, 10);
}

Para aprender mais sobre arrastar imagens de retorno, veja Definindo a imagem de retorno do arraste (Drag).

Defina o efeito do arraste (Drag effect)

A propriedade