Polecenia wycinania i kopiowania

IE10 i nowsze wersje dodały obsługę poleceń „cut” i „copy” za pomocą metody Document.execCommand(). Od wersji Chrome 43 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 w przypadku połączenia jej z interfejsem Selection API do programowego wybierania tekstu w celu określenia, co ma być kopiowane do schowka. Bardziej szczegółowe informacje o tym omówimy w dalszej części tego artykułu.

Prosty przykład

Dodajmy na przykład przycisk, który kopiuje adres e-mail do schowka użytkownika.

Dodajemy do kodu HTML adres e-mail za pomocą przycisku inicjowania kopiowania po 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>

Następnie w języku JavaScript chcemy dodać do przycisku moduł obsługi zdarzeń kliknięcia, w którym wybieramy tekst adresu e-mail z kotwice js-emaillink, wykonujemy polecenie kopiowania, aby skopiować adres e-mail do schowka użytkownika. Następnie odznaczamy adres e-mail, aby użytkownik nie widział wyboru.

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

W tym przypadku używamy metody interfejsu Selection API window.getSelection(), która służy do programowego ustawiania „zaznaczenia” tekstu na kotwicę, czyli tekstu, który chcemy skopiować do schowka użytkownika. Po wywołaniu metody document.execCommand() możemy usunąć wybór, wywołując metodę window.getSelection().removeAllRanges(). Jeśli chcesz sprawdzić, czy wszystko działało zgodnie z oczekiwaniami, możesz sprawdzić odpowiedź metody document.execCommand(). Jeśli polecenie nie jest obsługiwane lub włączone, zwraca wartość false (fałsz). Zamykamy execCommand() w ramach typu try and catch, ponieważ w kilku sytuacjach polecenia „cut” i „copy” mogą spowodować błąd.

Polecenia „wytnij” można używać w przypadku pól tekstowych, z których chcesz usunąć treść tekstową i udostępnić ją w schowku.

Za pomocą obszaru 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>

Oto co możemy zrobić, by wyciąć treść:

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

queryCommandSupportedqueryCommandEnabled

Przed wywołaniem funkcji document.execCommand() sprawdź, czy ten interfejs API jest obsługiwany za pomocą metody document.queryCommandSupported(). W naszym przykładzie możemy ustawić stan przycisku wyłączonego na podstawie takiej możliwości:

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

Różnica między document.queryCommandSupported() a document.queryCommandEnabled() jest taka, że wycinanie i kopiowanie może być obsługiwane przez przeglądarkę, ale jeśli nie jest aktualnie zaznaczony tekst, nie zostaną one włączone. Jest to przydatne w sytuacjach, gdy nie ustawiasz wyboru tekstu automatycznie, a chcesz mieć pewność, że polecenie będzie działać zgodnie z oczekiwaniami, a w przeciwnym razie wyświetlić użytkownikowi komunikat.

Obsługa przeglądarek

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

Safari nie obsługuje tych poleceń.

Znane błędy