Polecenia wycinania i kopiowania

W IE10 i nowszych wersjach dodano obsługę poleceń „wytnij” i „kopiuj” za pomocą metody Document.execCommand(). Od wersji 43 Chrome te polecenia są też obsługiwane w Chrome.

Tekst zaznaczony w przeglądarce podczas wykonywania jednego z tych poleceń zostanie wycięty lub skopiowany do schowka użytkownika. Dzięki temu użytkownik może w prosty sposób zaznaczyć fragment tekstu i skopiować go do schowka.

Ta funkcja staje się niezwykle przydatna, gdy połączysz ją z interfejsem Selection API, aby za pomocą programowania zaznaczać tekst i określać, co ma zostać skopiowane do schowka. Więcej informacji na ten temat znajdziesz w dalszej części tego artykułu.

Prosty przykład

Dla przykładu dodajmy przycisk, który kopiuje adres e-mail na schowek użytkownika.

Dodajemy adres e-mail w HTML za pomocą przycisku, który po kliknięciu inicjuje kopiowanie:

<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>

Następnie w języku JavaScript dodajemy do przycisku obsługę zdarzenia kliknięcia, w której wybieramy tekst adresu e-mail z ankiety js-emaillink, wykonujemy polecenie kopiowania, aby adres e-mail znalazł się w schowku użytkownika, a potem odznaczamy adres e-mail, aby użytkownik nie widział tej selekcji.

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();
});

Wykorzystujemy tutaj metodę interfejsu Selection API, window.getSelection(), aby programowo ustawić „wybór” tekstu w kotwicy, czyli tekst, który chcemy skopiować do schowka użytkownika. Po wywołaniu document.execCommand() możemy usunąć zaznaczenie, wywołując window.getSelection().removeAllRanges(). Jeśli chcesz sprawdzić, czy wszystko działa zgodnie z oczekiwaniami, możesz zbadać odpowiedź document.execCommand(); zwraca ona wartość false, jeśli polecenie nie jest obsługiwane lub włączone. Funkcję execCommand() otaczamy instrukcją try-catch, ponieważ polecenia „cut” i „copy” mogą wywołać błąd w kilku sytuacjach.

Polecenie „Wytnij” można stosować w przypadku pól tekstowych, w których chcesz usunąć zawartość tekstową i uzyskać do niej dostęp za pomocą schowka.

Użycie pola tekstowego i przycisku w kodzie HTML:

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

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

Aby wyciąć treści, możemy:

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 i queryCommandEnabled

Przed wywołaniem metody document.execCommand() musisz się upewnić, że ten interfejs API jest obsługiwany, korzystając z metody document.queryCommandSupported(). W przykładzie powyżej stan przycisku wyłączonego na podstawie obsługi można ustawić tak:

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

Różnica między funkcjami document.queryCommandSupported() i document.queryCommandEnabled() polega na tym, że funkcja wycinania i kopiowania może być obsługiwana przez przeglądarkę, ale jeśli nie ma obecnie wybranego tekstu, funkcje te nie będą włączone. Jest to przydatne w sytuacjach, gdy nie ustawiasz zaznaczenia tekstu programowo i chcesz mieć pewność, że polecenie będzie działać zgodnie z oczekiwaniami. W przeciwnym razie wyświetl użytkownikowi wiadomość.

Obsługa przeglądarek

Te polecenia są obsługiwane w przeglądarkach Internet Explorer 10 i nowszych, Chrome 43 i nowszych, Firefox 41 i nowszych oraz Opera 29 i nowszych.

Safari nie obsługuje tych poleceń.

Znane błędy