Копирование

Кнопка копирования кладёт в буфер обмена готовое значение или текст другого элемента: команду, ключ, код заказа. Ставьте её рядом с текстом, который читатель переносит в другое место, и не прячьте этот текст: его должно быть можно выделить и вручную.

Пример

npm install @simai/ui

HTML

<div class="relative p-2 radius-2 border border-outline-variant">
  <code id="clipboard-install">npm install @simai/ui</code>
  <button type="button" class="sf-clipboard sf-clipboard-surface sf-clipboard--overlay" data-clipboard-target="#clipboard-install" data-success="Команда скопирована" data-error="Не удалось скопировать" aria-label="Копировать команду">
    <i class="sf-icon" aria-hidden="true">content_copy</i>
  </button>
</div>

Разметка

Минимальную разметку показывает пример выше: нативный <button type="button"> с классом sf-clipboard, иконкой sf-icon и источником значения.

Источник задаёт один из атрибутов: data-copy — само значение; data-target или data-clipboard-target — #id элемента, чей текст копируется (у <input> и <textarea> берётся value). Если заданы оба вида источника, копирование завершается ошибкой.
Кнопке без видимого текста нужен aria-label, который называет, что копируется.
Сообщения задают data-success и data-error. Скрипт выводит их в область статуса: в элемент из data-status="#id", а без него — в созданный после кнопки <span class="sf-clipboard-status">.
data-duration задаёт, через сколько миллисекунд сообщение и иконка возвращаются к исходным: от 1000 до 10000, по умолчанию 5000.
Класс sf-clipboard — маркер для Loader: по нему подключается скрипт компонента.

Варианты

Оформление

sf-clipboard-surface даёт кнопке собственную спокойную поверхность — для кода и полей. Если кнопка копирования стоит среди других действий, оформите её как кнопку с иконкой или кнопку с подписью и добавьте sf-clipboard: поведение то же.

sf-clipboard-surface

sf-icon-button

sf-button

HTML

<div class="flex flex-wrap gap-4 items-start">
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-clipboard-surface" data-copy="SF-2048" data-success="Скопировано" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">sf-clipboard-surface</code>
  </div>
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-icon-button sf-icon-button--icon sf-icon-button--link sf-icon-button--on-surface sf-icon-button--size-1 flex items-cross-center" data-copy="SF-2048" data-success="Скопировано" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">sf-icon-button</code>
  </div>
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-button sf-button--outline sf-button--on-surface sf-button--size-1" data-copy="SF-2048" data-success="Скопировано">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
      <span class="sf-button-text-container">Копировать код</span>
    </button>
    <code class="text-1/2 color-on-surface-variant">sf-button</code>
  </div>
</div>

Размер

Размер кнопки с sf-clipboard-surface задают sf-clipboard-1 (высота контрола ступени 1/3), sf-clipboard-2 (ступень 1, как без класса) и sf-clipboard-3 (ступень 2). Кнопке, оформленной как sf-icon-button или sf-button, размер задают классы этих компонентов.

sf-clipboard-1

sf-clipboard-2

sf-clipboard-3

HTML

<div class="flex flex-wrap gap-4 items-end">
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-clipboard-surface sf-clipboard-1" data-copy="SF-2048" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">sf-clipboard-1</code>
  </div>
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-clipboard-surface sf-clipboard-2" data-copy="SF-2048" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">sf-clipboard-2</code>
  </div>
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-clipboard-surface sf-clipboard-3" data-copy="SF-2048" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">sf-clipboard-3</code>
  </div>
</div>

Положение

sf-clipboard--overlay прижимает кнопку к верхнему конечному углу блока с текстом; блоку нужен position: relative (утилита relative). Без модификатора кнопка стоит в потоке, например в строке рядом со значением.

HTML

<div class="grid grid-col-1 md:grid-col-2 gap-3">
  <div class="flex flex-col gap-1">
    <div class="relative p-2 radius-2 border border-outline-variant">
      <code id="clipboard-position-overlay">npm install @simai/ui</code>
      <button type="button" class="sf-clipboard sf-clipboard-surface sf-clipboard--overlay" data-clipboard-target="#clipboard-position-overlay" aria-label="Копировать команду">
        <i class="sf-icon" aria-hidden="true">content_copy</i>
      </button>
    </div>
    <code class="text-1/2 color-on-surface-variant">sf-clipboard--overlay</code>
  </div>
  <div class="flex flex-col gap-1">
    <div class="flex items-center gap-1">
      <code id="clipboard-position-inline">npm install @simai/ui</code>
      <button type="button" class="sf-clipboard sf-clipboard-surface" data-clipboard-target="#clipboard-position-inline" aria-label="Копировать команду">
        <i class="sf-icon" aria-hidden="true">content_copy</i>
      </button>
    </div>
    <code class="text-1/2 color-on-surface-variant">без модификатора: в потоке</code>
  </div>
</div>

Состояния

Копирование

Пока идёт запись в буфер, скрипт ставит кнопке aria-disabled="true": кнопка приглушается и повторное нажатие ничего не делает. После записи атрибут снимается.

готова

aria-disabled="true"

HTML

<div class="flex flex-wrap gap-4 items-start">
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-clipboard-surface" data-copy="SF-2048" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">готова</code>
  </div>
  <div class="flex flex-col gap-1 items-start">
    <button type="button" class="sf-clipboard sf-clipboard-surface" data-copy="SF-2048" aria-label="Копировать код заказа" aria-disabled="true">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
    <code class="text-1/2 color-on-surface-variant">aria-disabled="true"</code>
  </div>
</div>

Результат

После успеха иконка меняется на check, после ошибки — на error, а в область статуса выводится текст из data-success или data-error. Через время из data-duration кнопка возвращается к исходному виду. Нажмите кнопки в примере: у второй нет источника, и она показывает ошибку.

data-success

data-error

HTML

<div class="flex flex-wrap gap-4 items-start">
  <div class="flex flex-col gap-1 items-start">
    <code class="text-1/2 color-on-surface-variant">data-success</code>
    <button type="button" class="sf-clipboard sf-clipboard-surface" data-copy="SF-2048" data-success="Код заказа скопирован" aria-label="Копировать код заказа">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
  </div>
  <div class="flex flex-col gap-1 items-start">
    <code class="text-1/2 color-on-surface-variant">data-error</code>
    <button type="button" class="sf-clipboard sf-clipboard-surface" data-target="#clipboard-missing-source" data-error="Не удалось скопировать" aria-label="Копировать значение без источника">
      <i class="sf-icon" aria-hidden="true">content_copy</i>
    </button>
  </div>
</div>

Доступность

Используйте нативный <button>: он получает фокус и срабатывает по Enter и пробелу.
Доступное имя называет объект: «Копировать команду», а не «Копировать».
Область статуса получает role="status", aria-live="polite" и aria-atomic="true": экранный диктор зачитывает результат. Задайте data-success и data-error, иначе результат виден только по иконке.
Скопированный текст остаётся видимым и выделяемым на странице.
В режиме высокой контрастности у кнопки появляется рамка, кольцо фокуса берёт системный цвет.
Кнопка поверх блока стоит в конечном углу и зеркалится при письме справа налево.

JavaScript

Скрипт подключает кнопки .sf-clipboard при загрузке страницы и кнопки, добавленные позже. Объект SF.Clipboard даёт три функции:

SF.Clipboard.bind(button) — подключает кнопку вручную;
SF.Clipboard.copy(button) — копирует значение кнопки, как при нажатии;
SF.Clipboard.unbind(button) — отключает кнопку и удаляет созданную область статуса.

Копирование идёт через navigator.clipboard на защищённой странице, а если оно недоступно или запрещено — через временное скрытое поле (sf-clipboard-fallback).

Кнопка отправляет всплывающие события:

Событие	Когда	`detail`
`sf:copy-success`	значение записано в буфер	`method` — `native` или `legacy`; `text` — скопированный текст
`sf:copy-error`	значение не записано	`code` — `missing_source`, `missing_target`, `ambiguous_source`, `empty_source`, `copy_denied`, `copy_unsupported` или `copy_failed`

JavaScript

document.addEventListener('sf:copy-success', (event) => {
  console.log('Скопировано:', event.detail.text);
});

Компонент регистрирует класс Copy, который собирает кнопку из параметров (text, copy, done, error, label, size, type, scheme). SF.Loader появляется к событию sf-loader-init на window; SF.Loader.ready('Copy', callback) передаёт класс, когда он зарегистрирован.

JavaScript

const whenLoader = (run) => (window.SF?.Loader ? run() : window.addEventListener('sf-loader-init', run, {once: true}));

whenLoader(() => SF.Loader.ready('Copy', (Copy) => {
  const copy = new Copy({param: {copy: 'SF-2048', label: 'Копировать код заказа', done: 'Скопировано'}});
  document.querySelector('#order').append(copy.render());
}));

Классы

Что	Классы
Блок	`sf-clipboard`
Части	`sf-clipboard-1`, `sf-clipboard-2`, `sf-clipboard-3`, `sf-clipboard-fallback`, `sf-clipboard-status`, `sf-clipboard-surface`
Модификаторы	`sf-clipboard--inline`, `sf-clipboard--overlay`

Классы и переменные собраны из CSS выпуска и обновляются вместе с ним.

См. также

Кнопка копирования — Smart-компонент: копирует содержимое другого элемента и сообщает о результате
Кнопки с иконкой
Подсветка кода

Навигация

Главное

Документация

Содержание

Копирование

Пример

Разметка

Варианты

Оформление

Размер

Положение

Состояния

Копирование

Результат

Доступность

JavaScript

Классы

См. также

Настройки

Копирование

Пример

Разметка

Варианты

Оформление

Размер

Положение

Состояния

Копирование

Результат

Доступность

JavaScript

Классы

См. также

Поиск по документации