Class: EditorBuilder

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

Использует паттерн Builder для гибкой настройки редактора перед инициализацией.

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

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

Example

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

const container = document.getElementById('editor-container');
const api = await new EditorBuilder().mount(container, 'http://localhost:9002/?WeApi=1');
await api.openDocument({ filename, content });

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

const openDocumentApi = await new EditorBuilder()
  .withMode(OpenMode.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

• HostEditorApi для работы с инициализированным редактором
• OpenMode для доступных режимов работы
• DocumentAccessPolicy для настройки ограничений

Constructors

Constructor

new EditorBuilder(): EditorBuilder

Returns

EditorBuilder

Methods

mount()

mount(container, url): Promise<DocumentOpenApi>

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

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

Parameters

container

HTMLElement

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

url

string

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

Returns

Promise<DocumentOpenApi>

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

Remarks

Формат URL:

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

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

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

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

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

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

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

Example

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

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

const { openDocument } = await new EditorBuilder()
  // Запуск редактора в заданном контейнере
  .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()
  .withMode('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()
    .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;
}

---

withDocumentAccessPolicy()

withDocumentAccessPolicy(accessPolicy): EditorBuilder

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

Parameters

accessPolicy

DocumentAccessPolicy

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

Returns

EditorBuilder

Текущий экземпляр 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
  .withMode(OpenMode.view)
  .withDocumentAccessPolicy({
    restrict: ['copy']  // Дополнительная защита от копирования
  })

---

withExperimentalFeaturesEnabled()

withExperimentalFeaturesEnabled(value): EditorBuilder

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

Parameters

value

boolean

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

Returns

EditorBuilder

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

Remarks

⚠️ Внимание:

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

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

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

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

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

Default

false

Example

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

builder.withExperimentalFeaturesEnabled(true)

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

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

---

withHostOrigin()

withHostOrigin(origin): EditorBuilder

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

Parameters

origin

string

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

Returns

EditorBuilder

Текущий экземпляр 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')   // Редактор

---

withIframeOrigin()

withIframeOrigin(origin): EditorBuilder

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

Parameters

origin

string

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

Returns

EditorBuilder

Текущий экземпляр 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')  // Редактор

---

withIframeSandboxConfig()

withIframeSandboxConfig(iframeSandboxConfig): EditorBuilder

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

Parameters

iframeSandboxConfig

IframeSandboxConfig

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

Returns

EditorBuilder

Текущий экземпляр 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
})

---

withLocale()

withLocale(locale): EditorBuilder

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

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

Parameters

locale

SupportedLocale

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

Returns

EditorBuilder

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

Default

'ru-RU'

Examples

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

editorBuilder.withLocale('en-US')

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

editorBuilder.withLocale('fr-FR')

---

withMode()

withMode(mode): EditorBuilder

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

Parameters

mode

OpenMode

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

Returns

EditorBuilder

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

Remarks

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

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

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

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

Default

OpenMode.edit

Example

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

builder.withMode(OpenMode.edit)

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

builder.withMode(OpenMode.view)

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

builder.withMode(OpenMode.review)

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

builder.withMode(OpenMode.comment)

---

withUserName()

withUserName(userName): EditorBuilder

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

Parameters

userName

string

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

Returns

EditorBuilder

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

Default

'Local User'

Remarks

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

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

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

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

Example

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

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

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

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