Polecenia wycinania i kopiowania

W przeglądarce IE10 i nowszych dodaliśmy obsługę poleceń „wytnij” i „Kopiuj” za pomocą metody Document.execCommand(). Od wersji Chrome 43 te polecenia są też obsługiwane w Chrome.

Tekst wybrany 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.

Przydaje się to w połączeniu z interfejsem Selection API, który pozwala automatycznie zaznaczać tekst w celu określenia, co jest kopiowane do schowka. Omówimy go bardziej szczegółowo w dalszej części tego artykułu.

Prosty przykład

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

Dodamy adres e-mail w kodzie HTML z przyciskiem rozpoczynającym kopiowanie po jego kliknięciu:

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

W swoim JavaScripcie chcemy dodać do przycisku moduł obsługi zdarzeń kliknięcia, w którym wybieramy tekst adresu e-mail z kotwicy js-emaillink, wykonujemy polecenie kopiowania, aby umieścić adres e-mail w schowku użytkownika, a następnie odznaczamy adres e-mail, aby użytkownik nie widział tego adresu.

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 ankru, 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 sprawdzić odpowiedź document.execCommand(); zwraca ona false, jeśli polecenie nie jest obsługiwane lub włączone. Kody execCommand() dodajemy do metody try-catch, bo w niektórych sytuacjach polecenia „cut” i „copy” mogą powodować błąd.

Polecenia „wytnij” można użyć w polach tekstowych, z których chcesz usunąć zawartość tekstową i udostępnić ją ze schowka.

Zastosowanie 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 funkcji document.execCommand() upewnij się, że ten interfejs API jest obsługiwany za pomocą metody document.queryCommandSupported(). W powyższym przykładzie możemy ustawić stan wyłączenia przycisku na podstawie sposobu obsługi:

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 wybierasz tekstu automatycznie i chcesz mieć pewność, że polecenie działa zgodnie z oczekiwaniami lub gdy użytkownik zobaczy komunikat.

Obsługa przeglądarek

Polecenia te obsługują przeglądarki IE 10 i nowsze, Chrome 43 i nowsze, Firefox 41 i nowsze oraz Opera 29 i nowsze.

Safari nie obsługuje tych poleceń.

Znane błędy