Interface: ClipboardApi

API для управления операциями буфера обмена (копирование, вырезание, вставка).

Предоставляет методы для взаимодействия с системным буфером обмена: копирование выделенного текста, вырезание и вставка содержимого.

Remarks

Требования и ограничения:

• Требует разрешения clipboard-read и clipboard-write в iframe (смотрите IframeSandboxConfig)
• Может требовать явного разрешения пользователя в браузере (во всплывающем окне)
• Некоторые браузеры могут блокировать доступ к буферу обмена по соображениям безопасности
• Работает только если документ находится в фокусе

Типичные сценарии использования:

• Создание кастомных кнопок копирования/вставки
• Реализация горячих клавиш для операций буфера обмена
• Синхронизация содержимого между редактором и другими приложениями
• Создание надстроек для работы с внешними системами

Обработка ошибок:

• Если разрешения не установлены, методы могут вызвать ошибку
• Если буфер обмена недоступен, операция может молча завершиться
• Используйте try-catch для обработки исключений

Example

Копирование выделения

// Выделить текст в документе
// Скопировать в буфер обмена
editorApi.document.clipboard.copy();
console.log('Текст скопирован');

Вырезание и вставка с проверкой ошибок

try {
  // Вырезать выделение
  editorApi.document.clipboard.cut();
  console.log('Содержимое вырезано');

  // Поместить фокус на другой документ/поле
  // ...

  // Вставить содержимое
  editorApi.document.clipboard.paste();
  console.log('Содержимое вставлено');
} catch (error) {
  console.error('Ошибка при работе с буфером обмена:', error);
}

Создание кастомной кнопки копирования в UI

editorApi.ui.ribbon.addTab({
  id: 'clipboardTab',
  title: 'Буфер обмена',
  groups: [{
    id: 'clipboardGroup',
    controls: [
      {
        type: 'button',
        id: 'copyBtn',
        title: 'Копировать',
        icon: 'copy',
        onClick: () => editorApi.document.clipboard.copy()
      },
      {
        type: 'button',
        id: 'cutBtn',
        title: 'Вырезать',
        icon: 'cut',
        onClick: () => editorApi.document.clipboard.cut()
      },
      {
        type: 'button',
        id: 'pasteBtn',
        title: 'Вставить',
        icon: 'paste',
        onClick: () => editorApi.document.clipboard.paste()
      }
    ]
  }]
});

See

• IframeSandboxConfig — как настроить разрешения для буфера обмена
• DocumentApi.clipboard — доступ к ClipboardApi
• SelectionApi — для работы с выделением перед операциями буфера обмена

Methods

copy()

copy(): void

Копирует текущее выделение в буфер обмена.

Содержимое становится доступным для вставки в другие приложения или обратно в редактор.

Returns

void

Remarks

Поведение:

• Копирует текущее выделение (если оно есть)
• Если ничего не выделено, операция игнорируется
• Форматирование и стили сохраняются в буфере обмена

Требования:

• Требует разрешение clipboard-write в конфигурации iframe
• Документ должен быть в фокусе
• Должно быть активное выделение

Браузерная совместимость:

• Chrome/Edge: ✅ Полная поддержка
• Firefox: ✅ Полная поддержка
• Safari: ⚠️ Требует разрешения пользователя

Example

Копирование после выделения

// Пользователь выделяет текст в документе
// Срабатывает обработчик копирования
const copyCallback = editorApi.createCallback(() => {
  editorApi.document.clipboard.copy();
  editorApi.ui.toasts.showToast({ id, content: 'Текст скопирован' });
});

// Регистрируем кнопку копирования
editorApi.ui.ribbon.registerButton({
  id: 'copyBtn',
  title: 'Копировать',
  onClick: copyCallback
});

Копирование с проверкой выделения

async function copyIfSelected() {
  const selection = await editorApi.document.selection.getSelectionAsText();

  if (selection && selection.length > 0) {
    editorApi.document.clipboard.copy();
    console.log('Скопировано:', selection);
  } else {
    console.warn('Ничего не выделено');
  }
}

See

• SelectionApi.getSelection — проверить текущее выделение
• ClipboardApi.cut — вырезание с удалением из документа

---

cut()

cut(): void

Вырезает текущее выделение в буфер обмена (копирует и удаляет из документа).

Содержимое удаляется из документа и помещается в буфер обмена.

Returns

void

Remarks

Поведение:

• Копирует выделение в буфер обмена
• Удаляет выделение из документа
• Курсор остаётся на месте удалённого содержимого
• Форматирование сохраняется в буфере обмена

Требования:

• Требует разрешение clipboard-write в конфигурации iframe
• Документ должен быть в режиме редактирования (OpenMode.edit)
• Документ должен быть в фокусе
• Должно быть активное выделение

Различие от copy():

• copy() оставляет содержимое в документе
• cut() удаляет содержимое из документа

Example

Вырезание с уведомлением

const cutCallback = editorApi.createCallback(() => {
  try {
    editorApi.document.clipboard.cut();
    editorApi.ui.toasts.showToast({ id, content: 'Содержимое вырезано' });
  } catch (error) {
    editorApi.ui.toasts.showToast({ id, type: 'error', content: 'Ошибка при вырезании' });
  }
});

Вырезание с отменой

const cutWithUndo = editorApi.createCallback(() => {
  editorApi.document.clipboard.cut();
  // Пользователь может отменить (Ctrl+Z) если передумает
});

See

• ClipboardApi.copy — копирование без удаления
• ClipboardApi.paste — вставка из буфера обмена

---

paste()

paste(): void

Вставляет содержимое из буфера обмена в позицию текущего выделения.

Если есть выделение, оно заменяется содержимым из буфера обмена. Если выделения нет, содержимое вставляется в позицию курсора.

Returns

void

Remarks

Поведение:

• Вставляет содержимое из системного буфера обмена
• Если есть выделение, оно заменяется
• Форматирование сохраняется (при поддержке формата)
• HTML содержимое автоматически преобразуется в внутренний формат
• Встроенные изображения также вставляются

Требования:

• Требует разрешение clipboard-read в конфигурации iframe
• Документ должен быть в режиме редактирования (OpenMode.edit)
• Документ должен быть в фокусе
• Буфер обмена должен содержать поддерживаемое содержимое

Поддерживаемые форматы:

• Обычный текст (text/plain)
• HTML (text/html)
• Встроенные изображения (image/*)

Ограничения:

• Если режим документа view | review | comment, операция будет заблокирована
• Размер содержимого может быть ограничен

Example

Вставка с обработкой ошибок

async function pasteContent() {
  try {
    editorApi.document.clipboard.paste();
    editorApi.ui.toasts.showToast({ id, content: 'Содержимое вставлено' });
  } catch (error) {
    if (error.message.includes('Rejected')) {
      editorApi.ui.toasts.showToast({ id, type: 'error', content: 'Документ защищен от редактирования' });
    } else {
      editorApi.ui.toasts.showToast({ id, type: 'error', content: 'Ошибка при вставке' });
    }
  }
}

Вставка с заменой выделения

const pasteCallback = editorApi.createCallback(async () => {
  // Если что-то выделено, оно будет заменено
  editorApi.document.clipboard.paste();
});

editorApi.ui.ribbon.registerButton({
  id: 'pasteBtn',
  title: 'Вставить (Ctrl+V)',
  onClick: pasteCallback
});

Вставка и продолжение редактирования

const pasteAndContinue = editorApi.createCallback(() => {
  editorApi.document.clipboard.paste();
  // Фокус остаётся в документе, можно продолжать печатать
  editorApi.document.insertContent(' '); // Добавить пробел
});

See

• ClipboardApi.copy — копирование для подготовки буфера обмена
• DocumentApi.insertContent — вставка произвольного содержимого
• SelectionApi — для работы с выделением перед вставкой