diff options
Diffstat (limited to 'files/pt-br/dragdrop/drag_and_drop/index.html')
-rw-r--r-- | files/pt-br/dragdrop/drag_and_drop/index.html | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/files/pt-br/dragdrop/drag_and_drop/index.html b/files/pt-br/dragdrop/drag_and_drop/index.html new file mode 100644 index 0000000000..10e5592b91 --- /dev/null +++ b/files/pt-br/dragdrop/drag_and_drop/index.html @@ -0,0 +1,258 @@ +--- +title: Arrastar e soltar +slug: DragDrop/Drag_and_Drop +tags: + - Avançado + - Guia(2) + - HTML5 + - Visão Geral + - XUL + - arrastar e soltar + - eventos +translation_of: Web/API/HTML_Drag_and_Drop_API +--- +<p>{{DefaultAPISidebar("HTML Drag and Drop API")}}</p> + +<p>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 (<em>draggable</em>) com o mouse, arrastar elementos até um elemento soltável (<em>droppable</em>), e soltar o elemento ao soltar o botão do mouse. Uma representação translúcida de elementos arrastáveis (<em>draggable)</em> seguem o ponteiro do mouse durante a operação de arrastar (drag).</p> + +<p>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).</p> + +<p><strong>NT: </strong>Para manter a tradução mais precisa e coesa, a partir daqui iremos manter os termos <em>drag</em> e <em>drop</em> e seus variantes conforme texto original. Sendo portanto mantidos também os termos <em>draggable</em> e <em>droppable</em>.</p> + +<p>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.</p> + +<h2 id="Eventos_Drag">Eventos Drag</h2> + +<p>O drag and drop em HTML usa o {{domxref("Event","modelo de eventos DOM")}} e os <em>{{domxref("DragEvent","eventos drag")}}</em> são hereditários dos {{domxref("MouseEvent","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 {{event("drag")}} e {{event("dragover")}}.</p> + +<p>Todos os <a href="/en-US/docs/Web/API/DragEvent#Event_types">tipos de evento drag</a> são associados a um <a href="/en-US/docs/Web/API/DragEvent#GlobalEventHandlers">manipulador global de eventos</a>. 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.</p> + +<table> + <tbody> + <tr> + <th scope="col">Event</th> + <th scope="col">On Event Handler</th> + <th scope="col">Description</th> + </tr> + <tr> + <td>{{event('drag')}}</td> + <td>{{domxref('GlobalEventHandlers.ondrag','ondrag')}}</td> + <td>Acionado quando um elemento ou seleção de texto está sendo arrastado.</td> + </tr> + <tr> + <td>{{event('dragend')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragend','ondragend')}}</td> + <td>Acionado quando uma operação de arrastar está terminando (por eexmplo, ao soltar o botão do mouse ou pressionar a tecla esc). (Veja <a href="/en-US/docs/DragDrop/Drag_Operations#dragend" title="Finishing a Drag">Terminando um evento Drag</a>.)</td> + </tr> + <tr> + <td>{{event('dragenter')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragenter','ondragenter')}}</td> + <td>Acionado quando um elemento arrastável ou seleção de texto entra em um ponto de soltura (drop target). (Veja <a href="/en-US/docs/DragDrop/Drag_Operations#droptargets" title="Specifying Drop Targets">Determinando Drop Targets</a>.)</td> + </tr> + <tr> + <td>{{event('dragexit')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragexit','ondragexit')}}</td> + <td>Acionado quando um elemento não é mais o ponto de seleção imediata da operação drag.</td> + </tr> + <tr> + <td>{{event('dragleave')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragleave','ondragleave')}}</td> + <td>Acionado quando um elemento arrastável ou seleção de texto abandona um ponto de soltura (drop target) válido.</td> + </tr> + <tr> + <td>{{event('dragover')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragover','ondragover')}}</td> + <td>Acionado quando um elemento ou seleção de texto está sendo arrastado sobre um ponto de soltura válido (a cada aproximadamente 100 milisegundos).</td> + </tr> + <tr> + <td>{{event('dragstart')}}</td> + <td>{{domxref('GlobalEventHandlers.ondragstart','ondragstart')}}</td> + <td>Acionado quando o usuário começa a arrastar um elemento válido ou seleção de texto. (Veja <a href="/en-US/docs/DragDrop/Drag_Operations#dragstart" title="Starting a Drag Operation">Começando uma Operação Drag</a>.)</td> + </tr> + <tr> + <td>{{event('drop')}}</td> + <td>{{domxref('GlobalEventHandlers.ondrop','ondrop')}}</td> + <td>Acionado quando um elemento ou seleção de texto é solta em um ponto d soltura (drop target) válido. (Veja <a href="/en-US/docs/DragDrop/Drag_Operations#drop" title="Performing a Drop">Realizando um Drop</a>.)</td> + </tr> + </tbody> +</table> + +<p>Note que eventos <code>dragstart</code> e <code>dragend</code> não são acionados ao arrastar um arquivo vindo do sistema operacional para o navegador.</p> + +<h2 id="Interfaces">Interfaces</h2> + +<p>A interface HTML drag and drop é composta pelos eventos {{domxref("DragEvent")}}, {{domxref("DataTransfer")}}, {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}}.</p> + +<p>A interface {{domxref("DragEvent")}} consiste de um construtor e uma propriedade, a propriedade {{domxref("DragEvent.dataTransfer","dataTransfer")}} que é um objeto {{domxref("DataTransfer")}}. Os objetos {{domxref("DataTransfer")}} incluem estados do evento drag como o tipo de drag sendo feito (por exemplo <code>copy</code> ou <code>move</code>), os dados do do evento drag (um ou mais itens) e o tipo de cada <em>item drag</em> (um MIME type). Objetos {{domxref("DataTransfer")}} também contém métodos para adicionar itens aos dados do drag e remover um item. As interfaces {{domxref("DragEvent")}} e {{domxref("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 {{anch("Gecko specific interfaces","Gecko-specific extensions")}} ao objeto {{domxref("DataTransfer")}}, apesar de entretanto essas extensões funcionarem apenas no Firefox.</p> + +<p>Cada objeto {{domxref("DataTransfer")}} contém uma propriedade {{domxref("DataTransfer.items","items")}} que é uma {{domxref("DataTransferItemList","lista")}} dos objetos {{domxref("DataTransferItem")}}. Cada objeto {{domxref("DataTransferItem")}} representa um único <em>drag item</em> e cada item tem uma propriedade {{domxref("DataTransferItem.kind","kind (tipo)")}} que é o <em>tipo(kind)</em> de data (seja ela <code>string</code> ou <code>file</code>) e uma propriedade {{domxref("DataTransferItem.type","type (tipo)")}} que é o tipo de dado do item (ou seja, MIME type). O objeto {{domxref("DataTransferItem")}} também contém métodos para conseguir dados do item arrastável.</p> + +<p>O objeto {{domxref("DataTransferItemList")}} é uma lista de objetos {{domxref("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.</p> + +<p>A diferença chave entre das interfaces {{domxref("DataTransfer")}} e {{domxref("DataTransferItem")}} é que a primeira usa o método síncrono {{domxref("DataTransfer.getData","getData()")}} para acessar os dados de um item arrastável, e a segunda usa o método assíncrono {{domxref("DataTransferItem.getAsString","getAsString()")}} para acessá-lo.</p> + +<p>Note: as interfaces {{domxref("DragEvent")}} e a {{domxref("DataTransfer")}} são vastamente interoperáveis com navegadores desktop. Entretanto, as interfaces {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}} tem suporte limitado entre navegadores. Veja {{anch("Interoperabildade")}} para mais informações.</p> + +<h3 id="Interfaces_específicas_para_o_Gecko">Interfaces específicas para o Gecko</h3> + +<p>A Mozilla e o Firefox suportam algumas funcionalidades fora dos padrões do modelo drag and drop. Elas são <em>cfunções convenientes</em> 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 <a href="/en-US/docs/DragDrop/Dragging_and_Dropping_Multiple_Items" title="Dragging and Dropping Multiple Items">Dragging and Dropping Multiple Items</a>. Para mais informações, veja a página de referência {{domxref("DataTransfer")}} para todas as <a href="/en-US/docs/Web/API/DataTransfer#Gecko_properties">propriedades específicas para o Gecko</a> e <a href="/en-US/docs/Web/API/DataTransfer#Gecko_methods">Métodos específicos para o Gecko</a>.</p> + +<h2 id="O_básico">O básico</h2> + +<p>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.</p> + +<h3 id="Identificando_o_que_é_arrastável_draggable">Identificando o que é arrastável <em>(draggable)</em></h3> + +<p>Para fazer um elemento se tornar arrastável, é necessária a adição de um atributo {{htmlattrxref("draggable")}} além da adição do manipulador de eventos global {{domxref("GlobalEventHandlers.ondragstart","ondragstart")}}, conforme descrito no exemplo a seguir</p> + +<pre>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); +} + +<body> + <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">Este elemento é arrastável.</p> +</body> +</pre> + +<p>Veja a <a href="/en-US/docs/Web/HTML/Global_attributes/draggable" title="draggable global attribute">referência do atributo draggable</a> e o <a href="/en-US/docs/Web/Guide/HTML/Drag_operations#draggableattribute">Guia de operações drag</a> para mais informações.</p> + +<h3 id="Defina_os_dados_do_drag">Defina os dados do drag</h3> + +<p>A aplicação é livre para incluir qualquer quantidade de dados do item em uma operação drag. Cada dado de um item é uma {{domxref("DOMString","string")}} de um tipo particular, tipicamente um MIME type como por exemplo <code>text/html</code>.</p> + +<p>Cada {{domxref("DragEvent","evento drag")}} tem uma propriedade {{domxref("DragEvent.dataTransfer","dataTransfer")}} que <em>segura</em> os dados do evento. Essa propridade (que é um objeto {{domxref("DataTransfer")}}) também tem um método para <em>gerenciar</em> os dados do arraste (drag). O método {{domxref("DataTransfer.setData","setData()")}} é usado para adicionar um item aos dados do arraste, como demonstrado no exemplo a seguir.</p> + +<pre>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"); +} +</pre> + +<p>Para uma lista de tipos de dados mais comuns utilizados pelo drag and drop (como texto, HTML, links, e files), veja <a href="/en-US/docs/DragDrop/Recommended_Drag_Types" title="Recommended Drag Types">Tipos recomendados de Drag Types</a> e para mais informações sobre os dados do arraste (drag data), veja <a href="/en-US/docs/Web/Guide/HTML/Drag_operations#dragdata" title="Drag Data">Drag Data</a>.</p> + +<h3 id="Defina_uma_imagem_de_arraste_drag_image">Defina uma imagem de arraste (drag image)</h3> + +<p>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 {{domxref("DataTransfer.setDragImage","setDragImage()")}} como demonstrado no exemplo a seguir.</p> + +<pre>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); +} +</pre> + +<p>Para aprender mais sobre arrastar imagens de retorno, veja <a href="/en-US/docs/DragDrop/Drag_Operations#dragfeedback" title="Setting the Drag Feedback Image">Definindo a imagem de retorno do arraste (Drag)</a>.</p> + +<h3 id="Defina_o_efeito_do_arraste_Drag_effect">Defina o <em>efeito</em> do arraste (<em>Drag effect</em>)</h3> + +<p>A propriedade {{domxref("DataTransfer.dropEffect","dropEffect")}} é usada para controlar o retorno (geralmente visual) que é dado ao usuário durante uma operação drag and drop. Ela afeta qual cursor o navegador irá mostrar enquanto o arraste é realizado. Por exemplo, quando o usuário passa sobre (famoso <em>hover</em>) o ponto de soltura (drop target), o cursor do navegador pode indicar o tipo de operação que irá acontecer.</p> + +<p>Três efeitos podem ser definidos: </p> + +<p><code>copy</code> indica que os dados sendo arrastados podem ser copiados da localização atual para a localização de destino (localização do <em>drop</em>). </p> + +<p><code>move</code> indica que os dados sendo arrastados irá ser movido.</p> + +<p><code>link</code> indica que alguma forma de relação ou conexão será criada entre a localização de origem (source) e de destino (drop). </p> + +<p>Durante a operação de arraste, os efeitos do arraste (drag) podem ser modificados para determinar que certos efeitos são permitidos em determinadas localizações. Se permitido, uma soltura (drop) pode ocorrer naquela localização.</p> + +<p>O exemplo a seguir mostra como utilizar essa propriedade.</p> + +<pre>function dragstart_handler(ev) { + // Determina o efeito de arraste para copy + ev.dataTransfer.dropEffect = "copy"; +} +</pre> + +<p>Veja <a href="/en-US/docs/Web/Guide/HTML/Drag_operations#drageffects" title="Drag Effects">Efeitos do Arraste (Drag Effects)</a> para mais detalhes.</p> + +<h3 id="Defina_uma_zona_de_soltura_drop_zone">Defina uma zona de soltura <em>(drop zone)</em></h3> + +<p>Por padrão, o navegador previne tudo que possa acontecer ao soltar alguma coisa em um elemento HTML. Para mudar esse comportamento de forma que um elemento se torne uma zona de soltura (d<em>rop zone)</em> ou que seja soltável <em>(droppable)</em>, o elemento precisa ter ambos os atributos {{domxref("GlobalEventHandlers.ondragover","ondragover")}} e {{domxref("GlobalEventHandlers.ondrop","ondrop")}}. O exemplo a seguir mostra como utilizar esses atributos e inclui manipuladores básicos de evento para cada um.</p> + +<pre>function dragover_handler(ev) { + ev.preventDefault(); + // Define o dropEffect para ser do tipo move + ev.dataTransfer.dropEffect = "move" +} +function drop_handler(ev) { + ev.preventDefault(); + // Pega o id do alvo e adiciona o elemento que foi movido para o DOM do alvo + var data = ev.dataTransfer.getData("text"); + ev.target.appendChild(document.getElementById(data)); +} +<body> + <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Zona de Soltura (Drop Zone)</div> +</body> +</pre> + +<p>Note que cada manipulador chama {{domxref("Event.preventDefault","preventDefault()")}} para previnir o processamento adicional de eventos (como eventos touch ou eventos pointer).</p> + +<p>Para mais informações, veja <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_operations#droptargets">Especificando pontos de soltura (Drop Targets)</a>.</p> + +<h3 id="Manipulando_o_efeito_de_soltura_drop">Manipulando o <em>efeito</em> de soltura (drop)</h3> + +<p>O manipulador do evento {{event("drop")}} é livre para processar os dados do arraste (drag) de maneira específica em uma aplicação. Tipicamente, uma aplicação usaria o método {{domxref("DataTransfer.getData","getData()")}} para reter os itens arrastados e processá-los de acordo. A semântica da aplicação pode ser diferente dependendo do valor do {{domxref("DataTransfer.dropEffect","dropEffect")}} e/ou o estado da chave que o modifica.</p> + +<p>O exemplo a seguir mostra o manipulador de soltura (drop handler) pegando o id do elemento de origem atráves dos dados de drag (drag data) e então usando o id para mover o elemento de sua origem para o elemento de soltura (drop element).</p> + +<pre>function dragstart_handler(ev) { + // Adiciona o id do elemento alvo para o objeto de transferência de dados + ev.dataTransfer.setData("text/plain", ev.target.id); + ev.dropEffect = "move"; +} +function dragover_handler(ev) { + ev.preventDefault(); + // Define o dropEffect para ser do tipo move + ev.dataTransfer.dropEffect = "move" +} +function drop_handler(ev) { + ev.preventDefault(); + // Pega o id do alvo e adiciona o elemento que foi movido para o DOM do alvo + var data = ev.dataTransfer.getData("text"); + ev.target.appendChild(document.getElementById(data)); +} +<body> + <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">Este elemento é arrastável.</p> + <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Zona de Soltura (Drop Zone)</div> +</body> +</pre> + +<p>Para mais informações, veja <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_operations#drop">Realizando uma soltura (Drop)</a>.</p> + +<h3 id="Fim_da_soltura_Drag_end">Fim da soltura (Drag end)</h3> + +<p>No início da operação de arraste (drag), o evento {{event("dragend")}} é acionado no elemento de origem (<em>source)</em> - o elemento que foi o alvo do início do arraste (drag start). Este evento é acionado sempre quando o arraste é completado ou cancelado. O manipulador de eventos {{event("dragend")}} pode verificar o valor da propriedade {{domxref("DataTransfer.dropEffect","dropEffect")}} para determinar se a operação de arraste foi bem sucedida ou não.</p> + +<p>Para mais informações sobre manipular o final de uma operação de arraste, veja <a href="/en-US/docs/DragDrop/Drag_Operations#dragend" title="Finishing a Drag">Finalizando um arraste (Drag)</a>.</p> + +<h2 id="Interoperabilidade">Interoperabilidade</h2> + +<p>Como podem ser visto no <a href="/en-US/docs/Web/API/DataTransferItem#Browser_compatibility">DataTransferItem interface's Browser Compatibility table</a>, drag-and-drop a interoperabilidade é relativamente ampla emtre ps brpwsers desktop (exceto as interfaces {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}} que tem o menor suport). Estes dados tambem indica que o suporte ao drag and drop entre browser mobile é muito menor.</p> + +<h2 id="Examples_and_demos" name="Examples_and_demos">Exemplos e demonstrações</h2> + +<ul> + <li><a href="https://mdn.github.io/dom-examples/drag-and-drop/copy-move-DataTransfer.html">Copiando e movendo elementos com a interface <code>DataTransfer</code></a></li> + <li><a href="http://mdn.github.io/dom-examples/drag-and-drop/copy-move-DataTransferItemList.html">Copiando e movendo elementos com a interface <code>DataTransferListItem</code></a></li> + <li>Arrastando e soltando arquivos; Apenas para o Firefox: <a href="http://jsfiddle.net/9C2EF/" title="http://jsfiddle.net/9C2EF/">http://jsfiddle.net/9C2EF/</a></li> + <li>Arrastando e soltando arquivos; Todos os navegadores: <a href="https://jsbin.com/hiqasek/edit?html,js,output" title="https://jsbin.com/hiqasek">https://jsbin.com/hiqasek/</a></li> +</ul> + +<h2 id="See_also" name="See_also">Veja também</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Drag_operations" title="Drag Operations">Operações de Arraste</a></li> + <li><a href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Multiple_items" title="Dragging and Dropping Multiple Items">Arrastando e Soltando múltiplos elementos</a></li> + <li><a href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Recommended_drag_types" title="Recommended Drag Types">Tipos re arraste (Drag Types) recomendados</a></li> + <li><a href="https://html.spec.whatwg.org/multipage/interaction.html#dnd" title="Drag and Drop Standard">HTML5 Living Standard: Drag and Drop</a></li> + <li><a href="http://caniuse.com/#search=draganddrop" title="Drag and Drop interoperability data from CanIUse">Dados de unteroperabilidade Drag and Drop de acordo com o CanIUse</a></li> +</ul> |