Версия: Next

Interface: EditorBuilderAutonomous

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

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

Метод mount() завершает конфигурацию и возвращает Promise<OpenDocumentApi>.

Example

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

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

Полная конфигурация с цепочкой методов

const openDocumentApi = await new EditorBuilder()
    .withAutonomousMode()
    .withLicenseToken('xxx.xxx.xxx')
  .withOpeningMode('edit')
    .withLocale('ru-RU')
    .withUserName('Ivan Petrov')
    .withDocumentAccessPolicy({ restrict: ['copy'] })
    .mount(container, url);

const hostApi = await openDocumentApi.openDocument({ filename, content });

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

// Работа с 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 Класс-конструктор выступающий в роли точки входа
HostEditorApi для работы с инициализированным редактором
AutonomousOpenMode для доступных режимов работы
DocumentAccessPolicy для настройки ограничений

Methods

mount()

mount(container, url): Promise<DocumentOpenApi>

Монтирует редактор в HTML-контейнер и инициализирует его.

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

Parameters

container

HTML-контейнер, в который будет встроен iframe с редактором

HTMLElement | HTMLIFrameElement

url

string

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

Returns

Promise<DocumentOpenApi>

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

Remarks

Формат URL:

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

Требования к контейнеру:

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

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

Создание iframe с редактором
Установка разрешений (permissions)
Настройка postMessage коммуникации
Ожидание готовности редактора
Возврат API для открытия документа в редакторе
После открытия документа: возврат API для взаимодействия с редактором

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

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

Example

Простая инициализация

const container = document.getElementById('editor-container');

const { openDocument } = await new EditorBuilder()
    .withAutonomousMode()
    .withLicenseToken('xxx.xxx.xxx') // укажите свой лицензионный ключ
  // Запуск редактора в заданном контейнере
  .mount(container, `http://localhost:9002/?documentId=ades8asduZ8`);

// Сперва надо открыть документ в редакторе
const { editorApi } = await openDocument({ content: fileBuffer, filename: 'doc.docx' });

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

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

const container = document.getElementById('editor-container');

const { openDocument } = await new EditorBuilder()
    .withAutonomousMode()
    .withLicenseToken('xxx.xxx.xxx')
  .withOpeningMode('edit')
    .withLocale('ru-RU')
    .withUserName('Ivan Petrov')
    .withDocumentAccessPolicy({ restrict: ['copy'] })
    .withIframeSandboxConfig({ allowClipboardRead: true })
    .mount(container, 'http://localhost:9002/?fileId=123');

const { editorApi } = await openDocument({ content: fileBuffer, filename: 'doc.docx' });

editorApi.ui.toasts.showToast({ id: 'toast', content: 'Документ загружен' });

С обработкой ошибок

try {
    const container = document.getElementById('editor-container');

    if (!container) {
        throw new Error('CONTAINER_NOT_FOUND: Элемент #editor-container не найден');
    }

    if (container.offsetWidth === 0 || container.offsetHeight === 0) {
        console.warn('⚠️ Контейнер имеет нулевой размер');
    }

    const { openDocument } = await new EditorBuilder()
        .withAutonomousMode()
        .withLicenseToken('xxx.xxx.xxx')
    .mount(container, 'http://localhost:9002/');

    const hostApi = await openDocument({ content: fileBuffer, filename: 'doc.docx' });

    console.log('✓ Редактор успешно инициализирован');

    return hostApi;
} catch (error) {
    if (error.message.includes('CONTAINER_NOT_FOUND')) {
        console.error('Контейнер не найден');
    } else if (error.message.includes('INITIALIZATION_TIMEOUT')) {
        console.error('Редактор не отвечает, проверьте соединение');
    } else {
        console.error('Неизвестная ошибка:', error);
    }
    throw error;
}

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

AutonomousOpenMode

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

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')

withUserName()

withUserName(userName): this

Задаёт имя пользователя для отображения в редакторе.

Parameters

userName

string

Имя пользователя.

Returns

this

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

Default

'Local User'

Remarks

Где отображается имя пользователя:

В комментариях к документу
В отметках об изменениях (tracked changes)
В истории правок
В списке активных пользователей (при совместной работе)

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

поле не должно быть пустым (будет заменено на local)

Example

Установка имени пользователя

builder.withUserName('Иван Петров')

Установка имени с email

builder.withUserName('Ivan Petrov (ivan@example.com)')

Example​

See​

Methods​

mount()​

Parameters​

container​

url​

Returns​

Remarks​

Example​

Overrides​

withDocumentAccessPolicy()​

Parameters​

accessPolicy​

Returns​

Remarks​

Default​

Example​

Inherited from​

withExperimentalFeaturesEnabled()​

Parameters​

value​

Returns​

Remarks​

Default​

Example​

Inherited from​

withHostOrigin()​

Parameters​

origin​

Returns​

Remarks​

Default​

Example​

Inherited from​

withHostRequests()​

Parameters​

hostRequests​

Returns​

Example​

Inherited from​

withIframeOrigin()​

Parameters​

origin​

Returns​

Remarks​

Default​

Example​

Inherited from​

withIframeSandboxConfig()​

Parameters​

iframeSandboxConfig​

Returns​

Remarks​

Default​

Example​

Inherited from​

withLicenseToken()​

Parameters​

licenseToken​

Returns​

Example​

Inherited from​

withLocale()​

Parameters​

locale​

Returns​

Default​

Examples​

Inherited from​

withOpeningMode()​

Parameters​

mode​

Returns​

Remarks​

Default​

Example​

withUserName()​

Parameters​

userName​

Example

See

Methods

mount()

Parameters

container

url

Returns

Remarks

Example

Overrides

withDocumentAccessPolicy()

Parameters

accessPolicy

Returns

Remarks

Default

Example

Inherited from

withExperimentalFeaturesEnabled()

Parameters

value

Returns

Remarks

Default

Example

Inherited from

withHostOrigin()

Parameters

origin

Returns

Remarks

Default

Example

Inherited from

withHostRequests()

Parameters

hostRequests

Returns

Example

Inherited from

withIframeOrigin()

Parameters

origin

Returns

Remarks

Default

Example

Inherited from

withIframeSandboxConfig()

Parameters

iframeSandboxConfig

Returns

Remarks

Default

Example

Inherited from

withLicenseToken()

Parameters

licenseToken

Returns

Example

Inherited from

withLocale()

Parameters

locale

Returns

Default

Examples

Inherited from

withOpeningMode()

Parameters

mode

Returns

Remarks

Default

Example

withUserName()

Parameters

userName