Clipboard API: копирование и вставка в React

navigator.clipboard.writeText(text) записывает строку в системный буфер обмена и возвращает промис. Это современная замена устаревшему подходу с execCommand. Всегда используйте await для ожидания промиса и обрабатывайте возможное отклонение, например если пользователь запретил доступ к буферу обмена.

navigator.clipboard.readText() читает текущее содержимое буфера обмена как строку и также возвращает промис. Для чтения требуется разрешение clipboard-read, которое браузер предлагает пользователю предоставить. На практике в обычных приложениях React чтение из буфера обмена используется реже, чем запись.

Браузеры требуют, чтобы clipboard.writeText вызывался только внутри обработчика действия пользователя, например события щелчка или нажатия клавиши. Вызов внутри useEffect или асинхронно после действия приведёт к ошибке безопасности. Всегда запускайте запись непосредственно из обработчика onClick.

Стандартный шаблон выглядит так: пользователь нажимает кнопку копирования, обработчик вызывает navigator.clipboard.writeText(value), при успехе вы устанавливаете состояние copied в значение true, а кнопка на короткое время показывает галочку или метку «Скопировано!». После небольшой задержки кнопка возвращается в обычное состояние.

Инкапсулируйте логику в хуке useCopyToClipboard, который возвращает кортеж: [copied, copyFn]. Логическое значение copied управляет уведомлением в интерфейсе, а copyFn принимает текст для копирования. Хук самостоятельно обрабатывает асинхронную запись и возможные ошибки, поэтому компоненты остаются простыми.

Внутри хука после успешного копирования вызовите setCopied(true) и запланируйте сброс с помощью setTimeout(() => setCopied(false), 2000). Сохраните идентификатор таймера и очистите его в функции очистки useEffect, чтобы предотвратить обновление состояния после размонтирования. Это позволяет избежать предупреждения «невозможно обновить состояние размонтированного компонента».

Старые браузеры и страницы без HTTPS не поддерживают интерфейс буфера обмена. Устаревший запасной вариант создаёт временный textarea, устанавливает его значение, добавляет его в тело документа, вызывает document.execCommand('copy') и удаляет элемент. Этот подход синхронный и работает повсюду, хотя считается устаревшим.

Перед использованием интерфейса буфера обмена проверьте: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Если он недоступен, используйте устаревший подход с execCommand. Такая защитная проверка предотвращает ошибки выполнения в окружениях, где этот интерфейс не поддерживается.

Для чтения буфера обмена требуется разрешение пользователя через API разрешений. Текущее состояние можно запросить так: navigator.permissions.query({ name: 'clipboard-read' }) возвращает PermissionStatus со значением state — granted, denied или prompt. Браузер автоматически запросит разрешение при вызове readText().

Интерфейс буфера обмена доступен только в защищённых контекстах — HTTPS или на локальном хосте. На страницах HTTP значение navigator.clipboard равно undefined. Это ограничение безопасности, поскольку содержимое буфера обмена может быть конфиденциальным. Всегда проверяйте доступность интерфейса перед обращением к его методам, чтобы избежать ошибок обращения к отсутствующему объекту.

jsdom (используемый Jest) не реализует API буфера обмена. Имитируйте его в настройке тестов: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). Это позволяет проверить, что компонент вызывает writeText с правильным аргументом без настоящего браузерного окружения.

Когда в браузере безопасно вызывать navigator.clipboard.writeText()?

Используйте navigator.clipboard.writeText() внутри обработчика нажатия, чтобы скопировать текст. Создайте хук useCopyToClipboard, возвращающий [copied, copyFn], со сбросом через заданный промежуток времени. Всегда проверяйте доступность API, предусмотрите запасной вариант с execCommand для старых браузеров и имитируйте navigator.clipboard в тестах Jest.