Надстройки для редактора

Надстройки представляют собой изолированный исполняемый код JavaScript в формате ES6, который редактор может запускать внутри себя и предназначенный для расширения функциональности редактора. На текущий момент весь код надстройки должен находиться в одном файле и иметь конкретную точку входа onInit().

Используя EditorApi, надстройка может взаимодействовать с содержимым редактируемого документа, реагировать на события внутри редактора, и таким образом реализовывать различные расширения, полезные для пользователей.

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

Далее нужно использовать глобальную переменную editorApi: EditorApi для взаимодействия с системами Web-редактора.

Среда исполнения надстройки

Надстройки запускаются не в основном потоке браузера, а в изолированных Worker-процессах.
Кроме того, в приложении редактора используется Secure ECMAScript, чтобы гарантировать безопасную среду исполнения надстроек.

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

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

plugin.js

export default {
    onInit() {
        console.log('Поздравляем! Это ваш первая надстройка');
    },
};

А в этом примере надстройка взаимодействует с системой UI редактора, регистрируя в панель инструментов вкладку со своими кнопками:

plugin.js

export default {
    onInit() {
        editorApi.ui.ribbon.addTab({
            id: 'plugin1:my-tab', 
            title: 'Моя вкладка', 
            groups: [{
                id: 'plugin1:custom_group_1',
                type: 'controls',
                controls: [{
                    id: 'plugin1:ribbon:help-button',
                    type: 'button',
                    icon: 'Help',
                    title: 'О надстройке',
                    onClick: editorApi.createCallback(showHelpDialog),
                }, ...]
            }]
        })
    }
};

Пример проекта более сложной надстройки описан в статье Создание надстроек.

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

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

Для этого в интерфейсе EditorPlugin предусмотрен метод onDestroy. Если этот метод определен в надстройке, редактор вызовет его в процессе выгрузки надстройки, что позволит освободить нужные ресурсы.

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

plugin.js

let database;

export default {
    async onInit() {
        database = await openDbConnection();
    },

    async onDestroy() {
        await releaseDbConnection(database);
    }
};

Важно

Редактор передаст управление в метод onDestroy() и будет ожидать его завершения до определенного таймаута.
Если надстройка не вернет управление за отведенное время, то Worker-процесс будет остановлен принудительно.

Отображение пользовательских элементов надстройки в интерфейсе редактора

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

plugin.js

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

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

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

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

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 в планах
Обработка ошибок	Ошибки логируются, надстройка может выгрузиться	✓ По дизайну	Редактор остаётся стабильным