Кнопка копирования

<sf-copy-button> копирует значение и сообщает о результате: значок на миг становится галочкой, а «Скопировано» вежливо объявляется для чтения с экрана.

Пример

<div class="flex flex-col gap-3">
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-1/2 color-on-surface-variant">Идентификатор</span>
    <code id="copy-button-id">fhmm3nb668n747qpocad</code>
    <sf-copy-button target="#copy-button-id" label="Скопировать идентификатор"></sf-copy-button>
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <code>npm install @simai/ui</code>
    <sf-copy-button value="npm install @simai/ui" text="Копировать" label="Копировать команду" appearance="outline"></sf-copy-button>
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-1/2 color-on-surface-variant">Ссылка на запись</span>
    <sf-copy-button value="https://larena.test/admin/cms/42" icon="link" label="Скопировать ссылку" success-text="Ссылка скопирована" appearance="tonal"></sf-copy-button>
  </div>
  <output class="text-1/2 color-on-surface-variant" id="copy-button-log" aria-live="off"></output>
</div>

const log = document.querySelector('#copy-button-log');
document.addEventListener('sf-copy', (event) => { log.textContent = `Событие sf-copy: «${event.detail.text}»`; });
document.addEventListener('sf-copy-error', (event) => { log.textContent = `Событие sf-copy-error: ${event.detail.code}`; });

Применение

Что копируется

• value — сам текст;
• target="#id" — значение поля или текст элемента; пронумерованный блок кода копируется без номеров строк.

Задать сразу и value, и target — ошибка (ambiguous_source). Оба атрибута читаются при каждом копировании, поэтому другое значение достаточно присвоить свойству: button.value = … или button.target = '#id'.

Классы sf-clipboard подходят для готовой разметки без Smart-компонентов. <sf-copy-button> нужен, когда копируется содержимое другого элемента (target), нужно сообщение о результате и запасной путь там, где буфер обмена недоступен.

<code id="token">sk_test_51H…</code>
<sf-copy-button target="#token" label="Скопировать ключ"></sf-copy-button>
<sf-copy-button value="npm i @simai/ui" text="Копировать" label="Копировать команду"></sf-copy-button>

Вид

• text — видимая подпись; без неё кнопка — только значок.
• size — 1/3, 1/2 (по умолчанию), 1 или 2, по общей лестнице размеров: рядом с полем sf-input--size-1 берите 1; appearance — link (по умолчанию), ghost, outline или tonal. root-style ложится на саму кнопку.
• icon — значок в покое, по умолчанию content_copy: например, link для ссылки или key для ключа. success-icon — значок после копирования, по умолчанию check.
• success-text и error-text — свои сообщения, duration — сколько миллисекунд держится результат, по умолчанию 2000.

Когда копировать нельзя

Если браузер не дал доступ к буферу обмена — страница во фрейме или так настроена политика, — кнопка выделяет текст и сообщает «Выделено — нажмите Ctrl+C» (⌘C на macOS), чтобы человек скопировал сам. Пока идёт копирование, повторное нажатие не срабатывает.

События и код

sf-copy приходит с {text, method}, sf-copy-error — с {code}: empty_source, missing_target, ambiguous_source или denied. Метод copy() копирует из кода.

Доступность

• label — доступное имя: что именно копируется («Скопировать команду»). По умолчанию «Копировать». Если на странице несколько кнопок, называйте каждую, иначе экранный диктор не различит их.
• У кнопки с text доступное имя начинается с видимой подписи: при text="Копировать" — label="Копировать команду", а не «Скопировать команду». Так человек, который управляет голосом, называет кнопку тем словом, которое видит.
• У кнопки только со значком видимого имени нет, а всплывающую подсказку к Smart-кнопке не подключить (см. Подсказка). Где зрячему человеку нужно имя, задайте text.
• Результат объявляется вежливо, не перебивая.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• value — string, по умолчанию пусто. Текст для копирования.
• target — string, по умолчанию пусто. #id поля (копируется его значение) или элемента (его текст; пронумерованный блок кода — без номеров строк). value и target вместе — ошибка.
• text — string, по умолчанию пусто. Видимая подпись; без неё кнопка — только значок.
• label — string, по умолчанию пусто. Доступное имя, говорящее, что копируется («Скопировать команду»); по умолчанию «Копировать».
• size — string, по умолчанию 1/2, значения: 1/3, 1/2, 1, 2.
• appearance — string, по умолчанию link, значения: link, ghost, outline, tonal.
• icon — string, по умолчанию content_copy. Значок в покое: link, key и другие.
• success-icon — string, по умолчанию check.
• success-text — string, по умолчанию пусто.
• error-text — string, по умолчанию пусто.
• duration — string, по умолчанию 2000. Сколько миллисекунд держится результат.
• root-class — string, по умолчанию пусто.
• template — string, по умолчанию default.

Методы

• copy() — возвращает object. Копирует так же, как нажатие; нажатие во время копирования игнорируется.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• sf-copy — detail: { text: string, method: any }. Значение скопировано.
• sf-copy-error — detail: { code: any }. Значение не скопировано; при denied текст выделен для Ctrl+C.

Доступность

• Роль: кнопка (button).
• Доступное имя: рекомендуется.
• Клавиши: Enter, Space.
• Фокус: Обычная кнопка с именем из label (что копируется); результат объявляется вежливо; если буфер обмена недоступен, текст выделяется и звучит подсказка нажать Ctrl+C (⌘C на macOS).

Минимальная разметка

<sf-copy-button value="npm i @simai/ui" label="Скопировать команду"></sf-copy-button>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/copy-button
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-copy-button

См. также

• Копирование — классы копирования без Smart-компонента
• Кнопки
• Кнопки-иконки