Создание надстроек с помощью API

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

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

Для добавления новой надстройки необходимо создать JavaScript файл включающий команду инициации надстройки EditorPlugin.onInit. При включении надстройки эта команда будет выполнена автоматически.

Пример простой надстройки:

export default {
  onInit: startPlugin,
};

Освобождение ресурсов при отключении надстройки

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

Полноценный пример надстройки с освобождением ресурсов:

export default {
    // Завершение работы надстройки
    async onDestroy() {
        // Удаляем ранее зарегистрированные вкладки и элементы
        try {
            await editorApi.ui.ribbon.removeTabs(['plugin:ribbon:tab']);           // Убираем вкладку с ленты инструментов
            await editorApi.ui.sidebar.removeTabs(['plugin:sidebar:tab']);         // Убираем вкладку настроек сбоку
            await editorApi.ui.contextMenu.removeItems(['plugin1:context-menu:button']);   // Убираем пункт контекстного меню
            
            console.log("Все ресурсные элементы успешно очищены.");
        } catch (err) {
            console.error("Ошибка при очистке ресурсов:", err.message);
        }
    },
};

Отображение надстроек в интерфейсе редактора

Вы можете создавать элементы интерфейса и подключать их к командам созданных надстроек. Возможность расширения доступна для следующих контейнеров:

• Контекстное меню

  • Это меню отображается при клике правой кнопкой мыши на рабочей области редактора.
  • Удобно, если вам нужен быстрый доступ к определённым действиям надстройки именно там, где вы работаете.
  • Поддерживает только добавление кнопок.

• Панель инструментов

  • Эта панель располагается в верхней части редактора и содержит основные инструменты для работы с приложением.
  • Здесь удобно размещать кнопки быстрого запуска команд надстройки.
  • Позволяет размещать кнопки и поля ввода.

• Боковая панель

  • Находится в правой части редактора и используется чаще всего для расширенных настроек и сложных операций.
  • Подходит для создания полноценных структур элементов с большим количеством опций, списками элементов, визуализациями результатов работы надстройки.

Доступ к структуре и содержимому документа

Через API редактора ваша надстройка получает прямой доступ к данным документа, позволяя извлекать и изменять текстовые фрагменты, структуру документа и даже визуализировать элементы на экране.

Более подробную информацию о доступе к содержимому документа можно найти в статье: Работа с содержимым документа.

Подписка на события в редакторе

API редактора позволяет отслеживать изменения, происходящие в документе, и реагировать на них соответствующим образом. Для этого необходимо подписаться на события редактора и обрабатывать их.

Например, данный код позволяет отображать изменение выделения текста в консоли:

// Подключение к редактору
export default {
    // Начальная инициализация надстройки
    onInit() {
        // Реакция на смену выделения
        editorApi.events.subscribe('selectionChange', (state) => {
            console.log('Пользователь поменял выделение');
        });
    },
};

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

Работа с буфером обмена

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

Пример реализации стандартных функций для работы с буфером обмена:

// Подключение к редактору
export default {
    // Начальная инициализация надстройки
    onInit() {
        const callbacks = {
            clipboard: {
                cut: editorApi.createCallback(() => editorApi.document.clipboard.cut()), // Вырезание
                copy: editorApi.createCallback(() => editorApi.document.clipboard.copy()), // Копирование
                paste: editorApi.createCallback(() => editorApi.document.clipboard.paste()), // Вставка
            },
        };
    },
};

Методы editorApi.document.clipboard.* обеспечивают базовую поддержку операций с буфером обмена:

• cut(): вырезать выделенный текст и поместить его в буфер обмена.
• copy(): скопировать выделенный текст в буфер обмена.
• paste(): вставить содержимое буфера обмена в документ.

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

Показ модальных окон и предупреждений

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

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

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

Ограничения

Web Editor API использует SES (Secure EcmaScript) для изоляции кода надстроек в защищённой песочнице. Это обеспечивает безопасность редактора от потенциально вредоносного или неправильного кода надстроек.

Таблица ограничений

Область	Ограничение	Статус	Примечание
SES Security	Нет доступа к window, document, fetch	✓ По дизайну	Защита редактора
EditorApi	Минимальный набор (ribbon, events, document basics)	⚠️ MVP	Остальное заглушено
UI	Только текст и статический HTML в боковой панеле	⚠️ v1	Реактивные компоненты в roadmap
Документ	Только чтение выделения и вставка текста	⚠️ v1	Полный API в планах
События	Все события слушаются всегда, нет отписки	⚠️ v1	Оптимизация в планах
Типы документов	Разная функциональность для Text/Spreadsheet/Presentation	✓ Ожидается	Проверяйте тип в надстройке
Количество надстроек	~50-100 активных одновременно	⚠️ Браузер	Лимит памяти, не SES
Внешние библиотеки	Нельзя импортировать	❌ SES ограничение	Встраивайте код в надстройку
Сетевые запросы	Нет встроенного fetch	❌ Запрещено	Полный API в планах
Обработка ошибок	Ошибки логируются, надстройка может выгрузиться	✓ По дизайну	Редактор остаётся стабильным