Interface: EditorBuilderCloud

Класс-конструктор для настройки и монтирования редактора в хост-приложение в режиме облачного редактирования.

Все методы конфигурации (с префиксом with*) возвращают EditorBuilderCloud для цепочки вызовов.

Example

Минимальная инициализация

const iframe = document.getElementById('editor-iframe');
await new EditorBuilder()
  .withCloudMode()
  .withLicenseToken('xxx.xxx.xxx') // укажите свой лицензионный ключ
  .mount(iframe, 'http://localhost:9002/');

Полная конфигурация с использованием API

const iframe = document.getElementById('editor-iframe');
const hostApi = await new EditorBuilder()
    .withCloudMode()
    .withLicenseToken('xxx.xxx.xxx') // укажите свой лицензионный ключ
  .mount(iframe, url);

Взаимодействие через HostCloudEditorApi

// Работа с UI
hostApi.editorApi.ui.ribbon.addTab({ id: 'custom', title: 'Мои инструменты' });
hostApi.editorApi.ui.contextMenu.addItems([{ id: 'action', title: 'Действие' }]);

// Подписка на события
hostApi.editorApi.ui.events.subscribe('documentChange', () => console.log('Документ изменён'));

// Операции с файлами
const saveResult = await hostApi.saveDocument();

// Управление надстройками
await hostApi.plugins.startPlugin(myPlugin);

See

• EditorBuilder Класс-конструктор выступающий в роли точки входа
• HostCloudEditorApi для работы с инициализированным редактором
• CloudOpenMode для доступных режимов работы

Methods

mount()

mount(element, url): Promise<HostCloudEditorApi>

Устанавливает соединение с облачным редактором в iframe для дальнейшего управления им через API.

Это терминальный метод — после него нельзя вызывать методы конфигурации. Устанавливает коммуникацию с iframe с редактором и возвращает API для взаимодействия.

Parameters

element

HTMLElement

iframe с облачным редактором

url

string

URL редактора с параметрами

Returns

Promise<HostCloudEditorApi>

Promise с интерфейсом HostCloudEditorApi для работы с редактором

Remarks

Формат URL:

• Базовый URL редактора + query параметры
• Опциональные: &fileId=123, &userId=456
• Пример: http://localhost:9002/?fileId=abc123

Требования к iframe:

• Должен существовать в DOM на момент вызова
• Должен быть видимым (не display: none)
• Должен иметь ненулевые размеры (width > 0, height > 0)
• Рекомендуется: минимум 800x600px

Процесс инициализации:

1. Настройка postMessage коммуникации редактором в iframe
2. Ожидание готовности редактора
3. Возврат API для открытия документа в редакторе
4. После открытия документа: возврат API для взаимодействия с редактором

Возвращаемый HostCloudEditorApi содержит:

• editorApi — основной API для работы с документом и UI
• plugins — API для регистрации и управления надстройками
• saveRequest — метод для сохранения содержимого документа

Example

Инициализация

const editorIframe = document.getElementById('editor-iframe');

const { editorApi } = await new EditorBuilder()
    // Установление режима облачного редактора
    .withCloudMode()
    .withLicenseToken('xxx.xxx.xxx') // укажите свой лицензионный ключ
  // Установление соединения с редактором в iframe
  .mount(editorIframe, `http://localhost:9002/?documentId=ades8asduZ8`);

// Далее можно начинать взаимодействие с редактором по интерфейсу `EditorApi`
editorApi.events.subscribe('documentChange', () => console.log('Document changed'));

Overrides

EditorBuilderBase.mount

---

withDocumentAccessPolicy()

withDocumentAccessPolicy(accessPolicy): this

Задаёт политику доступов к функциональности редактора.

Parameters

accessPolicy

DocumentAccessPolicy

Список ограниченного функционала

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Remarks

Доступные ограничения:

Ограничение	Описание	Влияние
'copy'	Запретить копирование	Отключает Ctrl+C/Cmd+C, контекстное меню "Копировать"
'externalClipboard'	Запретить использование буфера обмена только внутри документа	Данные из документа можно копировать и вставлять в пределах самого документа, но вне документа данные из него вставить не получится
'print'	Запретить печать	Скрывает кнопку печати, блокирует Ctrl+P/Cmd+P

Default

{} (без ограничений)

Example

Запрет копирования и печати

builder.withDocumentAccessPolicy({
    restrict: ['copy', 'print']
})

Полная защита документа

builder.withDocumentAccessPolicy({
    restrict: ['copy', 'print', 'externalClipboard']
})

Только просмотр без возможности копирования

builder
    .withOpeningMode('view')
    .withDocumentAccessPolicy({
        restrict: ['copy']  // Дополнительная защита от копирования
    })

Inherited from

EditorBuilderBase.withDocumentAccessPolicy

---

withExperimentalFeaturesEnabled()

withExperimentalFeaturesEnabled(value): this

Активирует экспериментальные функции редактора.

Parameters

value

boolean

true для включения, false для отключения

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Remarks

⚠️ Внимание:

• Экспериментальные функции находятся в процессе тестирования
• Могут работать нестабильно или содержать ошибки
• API экспериментальных функций может измениться без предупреждения
• Не рекомендуется использовать в production без тщательного тестирования

Когда использовать:

• Для раннего тестирования новых возможностей
• В development/staging окружении
• Для обратной связи команде разработки

Не использовать:

• В production без согласования
• Для критичных бизнес-процессов
• Без возможности быстрого отката

Default

false

Example

Включение экспериментальных функций

builder.withExperimentalFeaturesEnabled(true)

Использование в development

const isDevelopment = process.env.NODE_ENV === 'development';
builder.withExperimentalFeaturesEnabled(isDevelopment)

Inherited from

EditorBuilderBase.withExperimentalFeaturesEnabled

---

withHostOrigin()

withHostOrigin(origin): this

Устанавливает origin хост-приложения для безопасной коммуникации через postMessage.

Parameters

origin

string

Origin адрес хост-приложения (протокол + домен + порт)

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Remarks

Что такое origin хоста:

• Это адрес приложения, в которое встроен редактор
• Используется для валидации postMessage от хоста к редактору
• Должен точно совпадать с реальным origin вашего приложения

Формат origin:

• protocol://domain:port
• Примеры: http://localhost:3000, https://app.example.com
• Не включает путь. Неправильно: https://app.example.com/documents Правильно: https://app.example.com

Когда указывать:

• Всегда в production для безопасности
• При разработке на нестандартных портах
• Если window.location.origin недоступен или неверен

⚠️ Безопасность:

• В production обязательно указывайте явный origin
• Неверный origin заблокирует коммуникацию
• Использование window.location.origin по умолчанию может быть небезопасно

Default

window.location.origin

Example

Локальная разработка

builder.withHostOrigin('http://localhost:3000')

Production

builder.withHostOrigin('https://app.example.com')

Полная конфигурация origins

builder
    .withHostOrigin('https://app.example.com')        // Ваше приложение
    .withIframeOrigin('https://editor.example.com')   // Редактор

Inherited from

EditorBuilderBase.withHostOrigin

---

withHostRequests()

withHostRequests(hostRequests): this

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

Parameters

hostRequests

Partial<HostRequests>

Внешние обработчики.

Returns

this

Example

• Переадресация всей страницы при запросе переадресации от редактора

builder.withHostRequests({
    redirect: (url: string) => {
        window.location.replace(url);
    };
})

• Перезапуск редактора по запросу.

function startWebEditorInContainer(container: HTMLDivElement) {
    const builder = new EditorBuilder().withAutonomousMode().withLicenseToken('xxx.xxx.xxx');
    builder.withHostRequests({
        reload: () => {
            container.innerHTML = '';
            startWebEditorInContainer(container);
        };
    }).mount(container, webEditorUrl);
}

Inherited from

EditorBuilderBase.withHostRequests

---

withIframeOrigin()

withIframeOrigin(origin): this

Устанавливает origin iframe для безопасной коммуникации через postMessage.

Parameters

origin

string

Origin адрес iframe (протокол + домен + порт)

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Remarks

Что такое origin iframe:

• Это адрес, с которого загружен редактор в iframe
• Используется для валидации postMessage от редактора к хосту
• Должен точно совпадать с реальным origin редактора

Формат origin:

• protocol://domain:port
• Примеры: http://localhost:9002, https://editor.example.com
• Не включает путь. Неправильно: http://localhost:9002/editor Правильно: http://localhost:9002

Когда указывать:

• Редактор на отдельном домене/поддомене
• Редактор на другом порту (локальная разработка)
• Для явного контроля безопасности postMessage

⚠️ Безопасность:

• Неверный origin заблокирует всю коммуникацию
• Браузер проверяет совпадение origin при каждом postMessage
• Не используйте * в production

Default

Определяется автоматически из URL переданного в mount()

Example

Локальная разработка

builder.withIframeOrigin('http://localhost:9002')

Production с поддоменом

builder.withIframeOrigin('https://editor.myoffice.ru')

Разные порты для хоста и редактора

builder
    .withHostOrigin('http://localhost:3000')    // Хост-приложение
    .withIframeOrigin('http://localhost:9002')  // Редактор

Inherited from

EditorBuilderBase.withIframeOrigin

---

withIframeSandboxConfig()

withIframeSandboxConfig(iframeSandboxConfig): this

Настраивает разрешения для iframe с редактором.

Parameters

iframeSandboxConfig

IframeSandboxConfig

Конфигурация разрешений (соответствует атрибуту allow iframe)

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Remarks

Доступные разрешения:

Параметр	Описание	Зачем нужно
allowClipboardRead	Доступ к чтению	Для операций копирования/вставки
allowClipboardWrite	Доступ к записи	Для операций копирования/вставки
allowMicrophone	Доступ к микрофону	Для голосового ввода
allowFullscreen	Полноэкранный режим	Для презентаций

⚠️ Безопасность:

• Предоставляйте только необходимые разрешения
• Пользователь увидит запрос браузера на разрешение
• Некоторые браузеры могут блокировать определённые разрешения

Default

{} (без дополнительных разрешений)

Example

Разрешение чтения и записи операций вставки

builder.withIframeSandboxConfig({
    allowClipboardRead: true,
    allowClipboardWrite: true,
})

Разрешение микрофона

builder.withIframeSandboxConfig({
    allowMicrophone: true
})

Все разрешения для полного функционала

builder.withIframeSandboxConfig({
    allowClipboardRead: true,
    allowClipboardWrite: true,
    allowMicrophone: true,
    allowFullscreen: true
})

Inherited from

EditorBuilderBase.withIframeSandboxConfig

---

withLicenseToken()

withLicenseToken(licenseToken): this

Устанавливает лицензионный ключ редактора.

Без действующего лицензионного ключа редактор не будет работать корректно.

Parameters

licenseToken

string

Лицензионный ключ

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Example

Установка лицензионного ключа

editorBuilder.withLicenseToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsaWNlbnNlIjoiZGV2ZWxvcG1lbnQiLCJleHAiOjk5OTk5OTk5OTl9.XYZ123')

Inherited from

EditorBuilderBase.withLicenseToken

---

withLocale()

withLocale(locale): this

Устанавливает локализацию интерфейса редактора.

Влияет на язык меню, кнопок, диалогов, форматирование чисел и дат.

Parameters

locale

SupportedLocale

Код локализации в формате BCP 47 (язык-РЕГИОН)

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Default

'ru-RU'

Examples

Установка английского языка

editorBuilder.withLocale('en-US')

Установка французского языка

editorBuilder.withLocale('fr-FR')

Inherited from

EditorBuilderBase.withLocale

---

withOpeningMode()

withOpeningMode(mode): this

Устанавливает режим работы редактора с документом.

Parameters

mode

CloudOpenMode

Режим работы редактора

Returns

this

Текущий экземпляр EditorBuilder для цепочки вызовов

Remarks

Доступные режимы:

Режим	Описание	Доступные операции
edit	Полное редактирование (по умолчанию)	Все операции: редактирование, комментирование, форматирование
view	Только просмотр	Только чтение, прокрутка, масштабирование
review	Рецензирование	Отслеживание изменений, комментарии, без прямого редактирования
comment	Только комментирование	Только добавление комментариев без изменения содержимого

Взаимодействие с другими настройками:

• В режиме view ограничения withDocumentAccessPolicy() избыточны
• В режиме review автоматически включается отслеживание изменений
• В режиме comment редактор позволяет только комментирование содержимого документа

Default

'edit'

Example

Режим редактирования

builder.withOpeningMode('edit')

Режим просмотра

builder.withOpeningMode('view')

Режим рецензирования

builder.withOpeningMode('review')

Режим комментирования

builder.withOpeningMode('comment')