Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

DataTransfer.effectAllowed — operações de arrastamento permitidas

DataTransfer.effectAllowed especifica as operações que a origem do arrastamento permite. Não seleciona a operação final: dropEffect descreve essa operação e tem de ser compatível com o conjunto permitido.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

dataTransfer.effectAllowed
 dataTransfer.effectAllowed = "copyMove";

DataTransfer.effectAllowed é uma propriedade de cadeia de caracteres de uma interface do browser, não uma funcionalidade ECMAScript. Durante um arrastamento, a origem define-a no manipulador de dragstart, quando o armazenamento de dados do arrastamento está em modo de leitura e escrita. Noutros modos ou com um valor inválido, a atribuição não altera o valor anterior.

Os valores permitidos são none (nenhuma operação), copy, link, move, os pares copyLink, copyMove, linkMove, bem como all (as três) e uninitialized (o estado predefinido, sem uma restrição explícita). A distinção entre maiúsculas e minúsculas é relevante. Um arrastamento real começa com uninitialized.

dropEffect descreve a operação selecionada, não o conjunto de operações permitidas. Normalmente, o destino cancela dragover com preventDefault() e define um dropEffect compatível. Uma incompatibilidade impede a operação de largar; effectAllowed, por si só, não copia nem move dados da aplicação.

Na execução verificada no Chromium, a consola mostra que, no objeto autónomo criado com new DataTransfer(), o valor permanece none tanto após a atribuição do valor válido copyMove como após a atribuição do valor inválido COPY. Este resultado difere do que a norma HTML prevê: o armazenamento de dados de um objeto criado com new DataTransfer() está em modo de leitura e escrita, pelo que a atribuição válida deveria definir effectAllowed como copyMove e a atribuição inválida posterior de COPY deveria manter o valor copyMove. O resultado na consola mostra o comportamento observado nessa execução no Chromium, não a regra de atribuição especificada para todos os browsers.

Quando o utilizador inicia um arrastamento, o manipulador de dragstart define copyMove em event.dataTransfer; a atribuição posterior de COPY não modifica esse valor. O exemplo destina-se a browsers; a presença de Node 24 num repositório não demonstra que esta API é suportada.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>DataTransfer.effectAllowed</title>
</head>
<body>
  <h1>Allowed drag operations</h1>
  <p id="source" draggable="true">Drag this text, then press Escape to cancel.</p>
  <p id="status" role="status">Start a drag to see which operations the source allows.</p>
  <script>
    const standalone = new DataTransfer();
    standalone.effectAllowed = 'copyMove';
    console.log('Standalone after copyMove: ' + standalone.effectAllowed);
    standalone.effectAllowed = 'COPY';
    console.log('Standalone after COPY: ' + standalone.effectAllowed);

    document.getElementById('source').addEventListener('dragstart', (event) => {
      const transfer = event.dataTransfer;
      transfer.setData('text/plain', 'Example drag');
      transfer.effectAllowed = 'copyMove';
      const accepted = transfer.effectAllowed;
      transfer.effectAllowed = 'COPY';
      document.getElementById('status').textContent =
        'Drag source after copyMove: ' + accepted +
        '. After invalid COPY: ' + transfer.effectAllowed + '.';
    });
  </script>
</body>
</html>

Resultado

Standalone after copyMove: none
Standalone after COPY: none

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes