Arrastar e soltar em HTML

Adobe AIR 1.0 e posterior

Para arrastar dados para dentro e fora de um aplicativo baseado em HTML (ou para dentro e fora do HTML exibido em um HTMLLoader), você pode usar eventos de arrastar e soltar HTML. A API de arrastar e soltar HTML permite que você arraste para e de elementos DOM no conteúdo HTML.

Nota: Você também pode usar as APIs NativeDragEvent e NativeDragManager do AIR ouvindo eventos no objeto HTMLLoader contendo o conteúdo HTML. No entanto, a API HTML é melhor integrada com o DOM HTML e oferece a você controle do comportamento padrão.

Comportamento padrão de arrastar e soltar

O ambiente HTML fornece o comportamento padrão para gestos de arrastar e soltar envolvendo texto, imagens e URLs. Usando o comportamento padrão, você sempre pode arrastar esses tipos de dados para fora de um elemento. No entanto, você pode apenas arrastar texto em um elemento e apenas a elementos em uma região editável de uma página. Quando você arrasta texto entre ou dentro de regiões editáveis de uma página, o comportamento padrão executa uma ação de mover. Quando você arrasta texto para uma região editável de uma região não editável ou de fora do aplicativo, o comportamento padrão executa uma ação de copiar.

Você pode substituir o comportamento padrão manipulando os eventos de arrastar e soltar sozinho. Para cancelar o comportamento padrão, você deve chamar os métodos preventDefault() dos objetos despachados para os eventos de arrastar e soltar. Você pode então inserir dados no destino de soltar e remover dados da origem de arrastar conforme necessário para executar a ação escolhida.

Por padrão, o usuário pode selecionar e arrastar qualquer texto e arrastar imagens e links. Você pode usar a propriedade WebKit CSS, -webkit-user-select , para controlar como qualquer elemento HTML pode ser selecionado. Por exemplo, se você definir -webkit-user-select como none , o conteúdo do elemento não podem ser selecionados e, portanto, não podem ser arrastados. Você também pode usar a propriedade CSS -webkit-user-drag para controlar se um elemento como um todo pode ser arrastado. No entanto, o conteúdo do elemento é tratado separadamente. O usuário poderia ainda arrastar uma parte selecionada do texto. Para obter mais informações, consulte CSS no AIR .

Eventos de arrastar e soltar em HTML

Os eventos despachados pelo elemento iniciador do qual uma ação de arrastar se origina são:

Evento

Descrição

dragstart

Despachado quando o usuário inicia o gesto de arrastar. O manipulador desse evento pode impedir a ação de arrastar, se necessário, chamando o método preventDefault() do objeto de evento. Para controlar se os dados arrastados podem ser copiados, vinculados ou movidos, defina a propriedade effectAllowed. Texto, imagens e links selecionados são colocados na área de transferência pelo comportamento padrão, mas você pode definir dados diferentes para o gesto de arrastar usando a propriedade dataTransfer do objeto de evento.

arrastar

Despachado continuamente durante o gesto de arrastar.

dragend

Despachado quando o usuário libera o botão do mouse para encerrar o gesto de arrastar.

Os eventos despachados por um destino de arrastar são:

Evento

Descrição

dragover

Despachado continuamente enquanto o gesto de arrastar permanece dentro dos limites do elemento. O manipulador para esse evento deve definir a propriedade dataTransfer.dropEffect para indicar se a ação de soltar resultará em uma ação de copiar, mover ou vincular se o usuário liberar o mouse.

dragenter

Despachado quando o gesto de soltar entrar nos limites de um elemento.

Se você alterar alguma propriedade de um objeto dataTransfer em um manipulador de eventos dragenter, essas alterações serão rapidamente substituídas pelo próximo evento dragover. Por outro lado, existe um pequeno atraso entre um evento dragenter e o primeiro dragover que pode fazer com que o cursor pisque se diferentes propriedades forem definidas. Em vários casos, você pode usar o mesmo manipulador de eventos para ambos os eventos.

dragleave

Despachado quando o gesto de arrastar deixa os limites do elemento.

drop

Despachado quando o usuário solta os dados no elemento. Os dados sendo arrastados podem apenas ser acessados dentro do manipulador desse evento.

O objeto de evento despachado em resposta a esses eventos é similar a um evento do mouse. Você pode usar propriedades de evento de mouse como ( clientX , clientY ) e ( screenX , screenY ), para determinar a posição do mouse.

A propriedade mais importante de um objeto de evento arrastar é dataTransfer , que contém os dados que estão sendo arrastados. O objeto dataTransfer em si possui as seguintes propriedades e métodos:

Propriedade ou método

Descrição

effectAllowed

O efeito permitido pela origem da ação de arrastar. Normalmente, o manipulador do evento dragstart define esse valor. Consulte Efeitos de arrastar em HTML .

dropEffect

O efeito escolhido pelo destino ou usuário. Se você define dropEffect em um manipulador de eventos dragover ou dragenter , o AIR atualiza o cursor do mouse para indicar o efeito que ocorre se o usuário libera o mouse. Se a definição de dropEffect não corresponder a um dos efeitos permitidos, nenhuma ação de soltar será permitida e o cursor unavailable será exibido. Se não tiver definido dropEffect em resposta a um evento dragover ou dragenter mais recente, o usuário poderá escolher dentre os efeitos permitidos com as teclas do modificador do sistema operacional padrão.

O efeito final é relatado pela propriedade dropEffect do objeto despachado para dragend . Se o usuário abandonar a ação de soltar liberando o mouse fora de um destino aceitável, dropEffect será definido como none .

tipos

Uma matriz contendo as sequências de caracteres de tipo MIME para cada formato de dados é apresentada no objeto dataTransfer .

getData(mimeType)

Obtém os dados no formato especificado pelo parâmetro mimeType .

O método getData() pode apenas ser chamado em resposta ao evento drop .

setData(mimeType)

Adiciona dados a dataTransfer no formato especificado pelo parâmetro mimeType. Você pode adicionar dados em vários formatos chamando setData() para cada tipo MIME. Qualquer dado colocado no objeto dataTransfer pelo comportamento de arrastar padrão é limpo.

O método setData() pode apenas ser chamado em resposta ao evento dragstart .

clearData(mimeType)

Limpa qualquer dado no formato especificado pelo parâmetro mimeType .

setDragImage(image, offsetX, offsetY)

Define uma imagem de arrastar personalizada. O método setDragImage() só pode ser chamado em resposta ao evento dragstart e somente quando um elemento inteiro de HTML é arrastado ao se definir seu estilo CSS -webkit-user-drag ao element . O parâmetro image pode ser um elemento JavaScript ou um objeto Image.

Tipos MIME para arrastar e soltar HTML

Os tipos MIME a usar com o objeto dataTransfer de um evento arrastar e soltar HTML incluem:

Formato de dados

Tipo MIME

Texto

"text/plain"

HTML

"text/html"

URL

"text/uri-list"

Bitmap

"image/x-vnd.adobe.air.bitmap"

Lista de arquivos

"application/x-vnd.adobe.air.file-list"

Você também pode usar outras sequências de caracteres MIME, incluindo as definidas por aplicativo. No entanto, outros aplicativos não podem reconhecer ou usar os dados transferidos. É sua responsabilidade adicionar dados ao objeto dataTransfer no formato esperado.

Importante: Apenas código em execução na caixa de proteção do aplicativo pode acessar arquivos soltos. Tentar ler ou definir qualquer propriedade de um objeto File em uma caixa de proteção de não aplicativo gera um erro de segurança. Consulte Tratamento de arquivos soltos em caixas de proteção HTML de não aplicativo para obter mais informações.

Efeitos de arrastar em HTML

O iniciador do gesto de arrastar pode limitar os efeitos de arrastar permitido definindo a propriedade dataTransfer.effectAllowed no manipulador para o evento dragstart . Os seguintes valores de sequências de caracteres podem ser usados:

Valor de string

Descrição

"none"

Nenhuma operação de arrastar é permitida.

"copiar"

Os dados serão copiados ao destino, deixando o original no lugar.

"link"

Os dados serão compartilhados com o destino de soltar usando um link de volta ao original.

"mover”

Os dados serão copiados para o destino e removidos do local original.

"copyLink"

Os dados podem ser copiados ou vinculados.

"copyMove"

Os dados podem ser copiados ou movidos.

"linkMove"

Os dados podem ser vinculados ou movidos.

"all"

Os dados podem ser copiados, movidos ou vinculados. All é o efeito padrão quando você impede o comportamento padrão.

O destino do gesto de arrastar pode definir a propriedade dataTransfer.dropEffect para indicar a ação tomada se o usuário concluir a ação de soltar. Se o efeito de soltar for uma das ações permitidas, o sistema exibe o cursor apropriado de copiar, mover ou vincular. Caso contrário, o sistema exibe o cursor unavailable . Se nenhum efeito de soltar for definido pelo destino, o usuário poderá escolher dentre as ações permitidas com as teclas do modificador.

Defina o valor dropEffect nos manipuladores para os eventos dragover e dragenter : 

function doDragStart(event) { 
    event.dataTransfer.setData("text/plain","Text to drag"); 
    event.dataTransfer.effectAllowed = "copyMove"; 
} 
 
function doDragOver(event) { 
    event.dataTransfer.dropEffect = "copy"; 
} 
 
function doDragEnter(event) { 
    event.dataTransfer.dropEffect = "copy"; 
}
Nota: Embora você deva sempre definir a propriedade dropEffect no manipulador para dragenter , esteja ciente que o próximo evento dragover redefine a propriedade para seu valor padrão. Defina dropEffect em resposta aos dois eventos.