MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

Tipos de Drag recomendados

Esta tradução está incompleta. Por favor, ajude a traduzir este artigo.

Arrastar e soltar HTML suporta arrastar vários tipos de dados incluindo texto simples, URLs, código HTML, arquivos e etc. O documento descreve as melhores práticas para arrastar tipos de dados comuns.

Cuidado:
Todos os métodos e propriedades neste documento que tem o prefico moz (tal como mozSetDataAt() são interfaces específicas Gecko. Essas interfaces devem somente trabalhar em nevegadores baseados no Gecko.

Arrastando Texto

Quando estiver arrastando texto, use o tipo text/plain. Os dados devem estar na string arrastada. Por exemplo: 

event.dataTransfer.setData("text/plain", "This is text to drag")

Arrastando texto em caixas de texto e seleções am páginas web são feitas automaticamente, então você não deve precisar lidar com os dados retornados do objeto arrastado.

Isso é recomendado sempre que você adicionar dados de um tipo text/plain como um retorno para aplicações ou os destinos para soltar os elementos não suportarem outros tipos, a menos que não haja outra alternativa. Sempre adicione o tipo plain/text por ser menos específico.

Nota: no antigo código, você também pode encontrar text/unicode ou o tipo Text. Ambos são equivalentes text/plain e podem ao invés dele salvar ou retornar um texto simples. 

Links podem incluir dados de dois tipos; o primeiro pode ser a URL usando o tipo text/uri-list, e o segundo é a URL usando o tipo text/plain (texto simples). Ambos os tipos podem usar o mesmo dado, a URL do link. Por exemplo:

var dt = event.dataTransfer;
dt.setData("text/uri-list", "http://www.mozilla.org");
dt.setData("text/plain", "http://www.mozilla.org");

Como de costume, defina o tipo text/plain em último caso por ser menos específico do que o tipo uri.

Nota: o tipo URL é definido uri-list com um 'I', não como 'L'.

Para arrastar múltiplos links, você pode também separa cada link por uma quebra de linha. Uma linha iniciada com um sinal númérico (#) é um comentário e não será considerada como uma URL válida. Você pode usar um comentário para indicar o propósito de um link, ou manter o título associado com o link. A versão text/plain (texto simples) de soltar dado pode incluir todos os links mas não pode incluir comentários.

Por exemplo:

http://www.mozilla.org
#A second link
http://www.example.com

Este exemplo de dado do tipo text/uri-list contém dois links e um comentário.

Quando retornar um link arrastado, você ter dados de retorno caso múltiplos links sejam arrastados, incluindo alguns comentários que apareçam nos dados. Por comodidade, o tipo especial URL pode ser usdo para referenciar um link válido dentro do dado do tipo text/uri-list. Você não pode adicionar dados usando o tipo URL;  tente apenas definir o tipo text/uri-list ao invés disso.

var url = event.dataTransfer.getData("URL");

Você pode também ver o dado usando um tipo específico do Mozilla text/x-moz-url. Se isso aparecer, pode ser usado antes do tipo text/uri-list. Isso contém a URL do link seguido do título do link, separado por quebras de linha. Por exemplo:

http://www.mozilla.org
Mozilla
http://www.example.com
Example

Dragging HTML and XML

HTML content may use the text/html type. The data for this type should be the serialized HTML to drag. For instance, it would be suitable to set the data value for this type to the value of the innerHTML property of an element.

XML content may use the text/xml type, but you should ensure that the data value is well-formed XML.

You may also include a plain text representation of the HTML or XML data using the text/plain type. The data should be just the text and should not include any of the source tags or attributes. For instance:

var dt = event.dataTransfer;
dt.setData("text/html", "Hello there, <strong>stranger</strong>");
dt.setData("text/plain", "Hello there, stranger");

Dragging Files

A local file is dragged using the application/x-moz-file type with a data value that is an nsIFile object. Non-privileged web pages are not able to retrieve or modify data of this type. Because a file is not a string, you must use the mozSetDataAt() method to assign the data. Similarly, when retrieving the data, you must use the mozGetDataAt() method.

event.dataTransfer.mozSetDataAt("application/x-moz-file", file, 0);

If possible, you may also include the file URL of the file using both the text/uri-list and/or text/plain types. These types should be added last so that the more specific application/x-moz-file type has higher priority.

Multiple files will be received during a drop as multiple items in the data transfer. See Dragging and Dropping Multiple Items for more details about this.

The following example shows how to create an area for receiving dropped files:

<listbox ondragenter="return checkDrag(event)"
         ondragover="return checkDrag(event)"
         ondrop="doDrop(event)"/>

<script>
function checkDrag(event)
{
  return event.dataTransfer.types.contains("application/x-moz-file");
}

function doDrop(event)
{
  var file = event.dataTransfer.mozGetDataAt("application/x-moz-file", 0);
  if (file instanceof Components.interfaces.nsIFile)
    event.currentTarget.appendItem(file.leafName);
}
</script>

In this example, the event returns false only if the data transfer contains the application/x-moz-file type. During the drop event, the data associated with the file type is retrieved, and the filename of the file is added to the listbox. Note that the instanceof operator is used here as the mozGetDataAt() method will return an nsISupports that needs to be checked and converted into an nsIFile. This is also a good extra check in case someone made a mistake and added a non-file for this type.

Dragging Images

Direct image dragging is not commonly done. In fact, Mozilla does not support direct image dragging on Mac or Linux platforms. Instead, images are usually dragged only by their URLs. To do this, use the text/uri-list type as with other URL links. The data should be the URL of the image or a data URL if the image is not stored on a web site or disk. For more information about data URLs, see the data URL scheme.

As with other links, the data for the text/plain type should also contain the URL. However, a data URL is not usually as useful in a text context, so you may wish to exclude the text/plain data in this situation.

In chrome or other privileged code, you may also use the image/jpeg, image/png or image/gif types, depending on the type of image. The data should be an object which implements the nsIInputStream interface. When this stream is read, it should provide the data bits for the image, as if the image was a file of that type.

You should also include the application/x-moz-file type if the image is located on disk. In fact, this a common way in which image files are dragged.

It is important to set the data in the right order, from most specific to least specific. The image type such as image/jpeg should come first, followed by the application/x-moz-file type. Next, you should set the text/uri-list data and finally the text/plain data. For example:

var dt = event.dataTransfer;
dt.mozSetDataAt("image/png", stream, 0);
dt.mozSetDataAt("application/x-moz-file", file, 0);
dt.setData("text/uri-list", imageurl);
dt.setData("text/plain", imageurl);

Note the mozGetDataAt() method is used for non-text data. As some contexts may only include some of these types, it is important to check which type is made available when receiving dropped images.

Dragging Nodes

Nodes and elements in a document may be dragged using the application/x-moz-node type. The data for the type should be a DOM node. This allows the drop target to receive the actual node where the drag was started from. Note that callers from a different domain will not be able to access the node even when it has been dropped.

You should always include a plain text alternative for the node.

Dragging Custom Data

You can also use other types that you make up for custom purposes. You should strive to always include a plain text alternative unless that object being dragged is specific to a particular site or application. In this case, the custom type ensures that the data cannot be dropped elsewhere.

Dragging files to an operating system folder

There are cases in which you may want to add a file to an existing drag event session, and you may also want to write the file to disk when the drop operation happens over a folder in the operating system when your code receives notification of the target folder's location. This only works in extensions (or other privileged code) and the data type "application/moz-file-promise" should be used. The following sample offers an overview of this advanced case:

// currentEvent is a given existing drag operation event

currentEvent.dataTransfer.setData("text/x-moz-url", URL);
currentEvent.dataTransfer.setData("application/x-moz-file-promise-url", URL);
currentEvent.dataTransfer.setData("application/x-moz-file-promise-dest-filename", leafName);
currentEvent.dataTransfer.mozSetDataAt('application/x-moz-file-promise',
                  new dataProvider(success,error),
                  0, Components.interfaces.nsISupports);

function dataProvider(){} 

dataProvider.prototype = {
  QueryInterface : function(iid) {
    if (iid.equals(Components.interfaces.nsIFlavorDataProvider)
                  || iid.equals(Components.interfaces.nsISupports))
      return this;
    throw Components.results.NS_NOINTERFACE;
  },
  getFlavorData : function(aTransferable, aFlavor, aData, aDataLen) {
    if (aFlavor == 'application/x-moz-file-promise') {
  
       var urlPrimitive = {};
       var dataSize = {};
  
       aTransferable.getTransferData('application/x-moz-file-promise-url', urlPrimitive, dataSize);
       var url = urlPrimitive.value.QueryInterface(Components.interfaces.nsISupportsString).data;
       console.log("URL file orignal is = " + url);
      
       var namePrimitive = {};
       aTransferable.getTransferData('application/x-moz-file-promise-dest-filename', namePrimitive, dataSize);
       var name = namePrimitive.value.QueryInterface(Components.interfaces.nsISupportsString).data;
  
       console.log("target filename is = " + name);
  
       var dirPrimitive = {};
       aTransferable.getTransferData('application/x-moz-file-promise-dir', dirPrimitive, dataSize);
       var dir = dirPrimitive.value.QueryInterface(Components.interfaces.nsILocalFile);
  
       console.log("target folder is = " + dir.path);
  
       var file = Cc['@mozilla.org/file/local;1'].createInstance(Components.interfaces.nsILocalFile);
       file.initWithPath(dir.path);
       file.appendRelativePath(name);
  
       console.log("output final path is =" + file.path);
  
       // now you can write or copy the file yourself...
    } 
  }
}

See Also

Etiquetas do documento e colaboradores

 Colaboradores desta página: MarcoRibeiro
 Última atualização por: MarcoRibeiro,