Clipboard API ломается в TypeScript: 4 недокументированных кейса, которые подкинут вам седых волос
navigator.clipboard.writeText выглядит безобидно, пока ваше приложение не падает в продакшне без единой ошибки — вот 4 грабли, которые вы обречены собрать.
Казалось бы, что может пойти не так с копированием текста в буфер обмена? Ну, нажми кнопку, вызови navigator.clipboard.writeText() — и готово. Но нет, TypeScript и браузеры решили, что это было бы слишком скучно. Разработчик JTorchia нарылся на четырёх граблях, которые документация скромно обходит стороной. Делимся опытом, чтобы вы не повторяли его путь.
Четыре кейса, которые сломают ваш день
- Небезопасный контекст — Clipboard API работает только через HTTPS или localhost. Если ваше приложение висит на HTTP, API просто молча вернёт
undefined. Никаких ошибок, просто тишина. Как Wi-Fi у бабушки: вроде есть, а толку нет. - Потеря фокуса — Если пользователь кликнул куда-то ещё до того, как выполнился
writeText, браузер решает, что вы пытались украсть данные, и блокирует операцию. Это как если бы вы хотели передать записку, но учитель отвернулся — и вы остались с ней. - Отозванные разрешения в iOS — Safari на iOS может отозвать разрешение на буфер обмена, если пользователь не взаимодействовал с сайтом последние 30 секунд. И вы узнаете об этом только по тихому
rejectedпромиса. - Тайминг React — Если вызвать
writeTextвнутри эффекта или обработчика события, который не является прямым результатом действия пользователя (например, клика), браузер может заблокировать вызов. Реакт батчит обновления, и ваш клик может потеряться в очереди.
Как это исправить (спойлер: не магией)
Для каждого кейса есть обходной путь: проверяйте navigator.clipboard на существование, обрабатывайте ошибки промисов, используйте useRef для хранения последнего действия пользователя, и никогда не вызывайте Clipboard API вне обработчиков пользовательских событий. Код-примеры можно найти в оригинальной статье.
Комментарий студии METABYTE: Мы тоже наступали на эти грабли в одном из проектов для финтех-стартапа. Теперь у нас есть чеклист «Clipboard API: check before deploy», и мы спим спокойнее. Если ваш проект тоже требует надёжного копирования — пишите, поделимся рецептом.