Recortar e copiar comandos

O IE10 e as versões mais recentes adicionaram suporte aos comandos "cut" e "copy" por meio do método Document.execCommand(). A partir do Chrome versão 43, esses comandos também serão compatíveis com o Chrome.

Qualquer texto selecionado no navegador quando um desses comandos for executado será recortado ou copiado para a área de transferência do usuário. Isso permite oferecer ao usuário uma maneira simples de selecionar uma parte do texto e copiá-la para a área de transferência.

Isso se torna extremamente útil quando você os combina com a API Selection para selecionar o texto programaticamente para determinar o que é copiado para a área de transferência. Veremos isso em mais detalhes posteriormente neste artigo.

Exemplo simples

Por exemplo, vamos adicionar um botão que copia um endereço de e-mail para a área de transferência do usuário.

Adicionamos o endereço de e-mail ao HTML com um botão para iniciar a cópia quando ele é clicado:

<p>Email me at <a class="js-emaillink" href="mailto:matt@example.co.uk">matt@example.co.uk</a></p>

<p><button class="js-emailcopybtn"><img src="./images/copy-icon.png" /></button></p>

Em seguida, em nosso JavaScript, queremos adicionar um manipulador de eventos de clique ao botão. Nele, selecionamos o texto do endereço de e-mail na âncora js-emaillink, executamos um comando de cópia para que o endereço de e-mail esteja na área de transferência do usuário e, em seguida, desmarcamos o endereço para que o usuário não veja a seleção.

var copyEmailBtn = document.querySelector('.js-emailcopybtn');
copyEmailBtn.addEventListener('click', function(event) {
    // Select the email link anchor text
    var emailLink = document.querySelector('.js-emaillink');
    var range = document.createRange();
    range.selectNode(emailLink);
    window.getSelection().addRange(range);

    try {
    // Now that we've selected the anchor text, execute the copy command
    var successful = document.execCommand('copy');
    var msg = successful ? 'successful' : 'unsuccessful';
    console.log('Copy email command was ' + msg);
    } catch(err) {
    console.log('Oops, unable to copy');
    }

    // Remove the selections - NOTE: Should use
    // removeRange(range) when it is supported
    window.getSelection().removeAllRanges();
});

O que estamos fazendo aqui é usar um método da API Selection, window.getSelection(), para definir de maneira programática a "seleção" do texto como âncora, que é o texto que queremos copiar para a área de transferência do usuário. Depois de chamar document.execCommand(), podemos remover a seleção chamando window.getSelection().removeAllRanges(). Se você quiser confirmar que tudo funcionou como esperado, examine a resposta de document.execCommand() que retornará "false" se o comando não for compatível ou não estiver ativado. Envolvemos execCommand() em um try and catch, já que os comandos "cut" e "copy" podem gerar um erro em alguns cenários.

O comando "cut" pode ser usado para campos de texto onde você quer remover o conteúdo do texto e torná-lo acessível por meio da área de transferência.

Usando uma área de texto e um botão no HTML:

<p><textarea class="js-cuttextarea">Hello I'm some text</textarea></p>

<p><button class="js-textareacutbtn" disable>Cut Textarea</button></p>

Podemos fazer o seguinte para cortar o conteúdo:

var cutTextareaBtn = document.querySelector('.js-textareacutbtn');

cutTextareaBtn.addEventListener('click', function(event) {
    var cutTextarea = document.querySelector('.js-cuttextarea');
    cutTextarea.select();

    try {
    var successful = document.execCommand('cut');
    var msg = successful ? 'successful' : 'unsuccessful';
    console.log('Cutting text command was ' + msg);
    } catch(err) {
    console.log('Oops, unable to cut');
    }
});

queryCommandSupported e queryCommandEnabled

Antes de chamar document.execCommand(), verifique se essa API é compatível com o método document.queryCommandSupported(). No exemplo acima, podemos definir o estado desativado do botão com base no suporte:

copyEmailBtn.disabled = !document.queryCommandSupported('copy');

A diferença entre document.queryCommandSupported() e document.queryCommandEnabled() é que recortar e copiar pode ser compatível com um navegador, mas se nenhum texto estiver selecionado, eles não serão ativados. Isso é útil em cenários em que você não está configurando a seleção de texto de maneira programática e quer garantir que o comando seja executado conforme o esperado. Caso contrário, apresenta uma mensagem ao usuário.

Compatibilidade com navegadores

O IE 10+, o Chrome 43+, o Firefox 41+ e o Opera 29+ são compatíveis com esses comandos.

O Safari não é compatível com esses comandos.

Bugs conhecidos