API буфера обмена

API буфера обмена предоставляет возможность реагировать на команды буфера обмена (вырезать, копировать и вставить), а также асинхронно читать из и записывать в системный буфер обмена.

Системный буфер обмена — это буфер данных, принадлежащий операционной системе, на которой работает браузер, который используется для кратковременного хранения данных и/или передачи данных между документами или приложениями. Обычно он реализуется как анонимный временный буфер данных, иногда называемый буфером вставки, к которому можно получить доступ из большинства или всех программ в среде через определённые программные интерфейсы.

API буфера обмена позволяет пользователям программно читать и записывать текст и другие типы данных в системный буфер обмена в безопасных контекстах, при условии, что пользователь соответствует критериям, описанным в разделе Обеспечение безопасности.

События генерируются в результате операций cut, copy и paste, которые изменяют буфер обмена. События имеют действие по умолчанию, например, действие по умолчанию для события copy копирует текущий выделенный фрагмент в системный буфер обмена. Действие по умолчанию может быть переопределено обработчиком событий — см. информацию по каждому из событий.

Clipboard Безопасный контекст

Предоставляет интерфейс для чтения и записи текста и данных в или из системного буфера обмена. В спецификации это упоминается как 'Async Clipboard API'.

ClipboardEvent

Представляет события, предоставляющие информацию, связанную с изменением буфера обмена, то есть событиями cut, copy и paste. В спецификации это упоминается как 'Clipboard Event API'.

ClipboardItem Безопасный контекст

Представляет отдельный формат элемента, используемый при чтении или записи данных.

API буфера обмена расширяет следующие API, добавляя перечисленные возможности.

Navigator.clipboard Только чтение Безопасный контекст

Возвращает объект Clipboard, который предоставляет чтение и запись в системный буфер обмена.

Element copy событие

Событие, генерируемое при инициации пользователем действия копирования.

Element cut событие

Событие, генерируемое при инициации пользователем действия вырезания.

Element paste событие

Событие, генерируемое при инициации пользователем действия вставки.

API буфера обмена позволяет пользователям программно читать и записывать текст и другие типы данных в системный буфер обмена в безопасных контекстах.

Спецификация требует, чтобы пользователь недавно взаимодействовал со страницей для чтения из буфера обмена (временная активация пользователя требуется). Если операция чтения вызвана взаимодействием пользователя с элементом вставки браузера или операционной системы (например, контекстным меню), браузер должен запросить подтверждение пользователя. Для записи в буфер обмена спецификация предполагает, что странице предоставлено разрешение API разрешений clipboard-write, и браузер также может потребовать временную активацию пользователя. Браузеры могут ввести дополнительные ограничения на использование методов доступа к буферу обмена.

Реализации браузеров расходятся со спецификацией. Различия отражены в разделе Совместимость с браузерами, и текущее состояние обобщено ниже:

Браузеры Chromium:

• Для чтения требуется, чтобы было предоставлено разрешение API разрешений clipboard-read. Временная активация не требуется.
• Для записи требуется либо разрешение clipboard-read, либо временная активация. Если разрешение предоставлено, оно сохраняется, и дополнительная временная активация не требуется.
• Для элементов <iframe>, которые обращаются к буферу обмена, должны быть разрешены разрешения HTTP Permissions-Policy clipboard-read и clipboard-write.
• Постоянный запрос на вставку не отображается при операции чтения, вызванной элементом вставки браузера или операционной системы.

Firefox & Safari:

• Для чтения и записи требуется временная активация.
• Запрос на вставку подавляется при чтении данных из буфера обмена с одинаковым происхождением, но не с разным происхождением.
• Разрешения clipboard-read и clipboard-write не поддерживаются (и не планируются к поддержке) в Firefox или Safari.

Firefox Расширения WebExtensions:

• Чтение текста доступно только для расширений с разрешением Web Extension clipboardRead. С этим разрешением расширение не требует временной активации или запроса на вставку.
• Запись текста доступна в безопасном контексте и с временной активацией. С разрешением Web Extension clipboardWrite временная активация не требуется.

Системный буфер обмена доступен через глобальную переменную Navigator.clipboard.

Этот фрагмент кода извлекает текст из буфера обмена и добавляет его к первому элементу, найденному с классом editor. Так как readText() возвращает пустую строку, если в буфере обмена нет текста, этот код безопасен.

navigator.clipboard
  .readText()
  .then(
    (clipText) => (document.querySelector(".editor").innerText += clipText),
  );

• Статья о поддержке изображений для Async Clipboard