Встраивание Surface

Поверхность запускается локально и открывается по адресу из bootstrap. Эта страница — о том, как встроить её в своё приложение.

Поверхность правит только первый абзац

Встраивать её как полноценный редактор нельзя: она объявляет открытие, правку первого абзаца, сохранение и события. Это проверяемая демонстрация пути, а не редактор для пользователя — см. Запуск Web Surface. Полный редактор в браузере — это веб-хост.

Два разных способа через iframe

Здесь описано встраивание поверхности, которая запущена рядом с вашим приложением — на той же машине, что и пользователь: настольная программа поднимает Surface Host и открывает его адрес в своём окне.

Если ваш продукт живёт в браузере и ядро должно работать на сервере, нужен другой путь — Редактор в браузере. Там пользователю не нужно ничего устанавливать, а каждому открытому документу поднимается отдельный процесс на сервере.

Сначала запустите демо

Если Surface ещё ни разу не запускалась, начните с запуска: там показан полный путь от установки до сохранённого файла.

Как запустить поверхность

# $CLI — путь к процессору, см. «Установка и проверка»
"$CLI" surface --port 0 \
  --doc /data/input.docx --save /data/output.docx

# первая строка stdout: fastdoc.surface-host-bootstrap.v1
# адрес из bootstrap.url открыть в WKWebView, WebView2 или браузере

Вставить поверхность и убрать её

Что поверхность принимает молча, а что молча отбрасывает

В cssVariables попадают только имена, начинающиеся на --fastdoc-, и только строковые значения: "16px" дойдёт, а 16 — нет. Всё остальное поверхность пропускает без ошибки и без предупреждения. Список того, что она понимает, — на странице Настройка под свой бренд.

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

readOnly здесь выключает ввод в самой поверхности — гасит поле правки и кнопку сохранения. Защитой документа это не является: команды, отправленные по сеансу напрямую, ему не подчиняются. За запрет на уровне ядра отвечает режим защиты самого документа — в нём отклоняется любая команда правки.

const handle = window.fastdocSurface.mount(container, {
  theme: "light",
  locale: "ru",
  readOnly: false,
  cssVariables: { "--fastdoc-accent": "#2f5bff" }
});

// при закрытии вкладки или документа
handle.unmount();

Как получать события

window.addEventListener("fastdoc-host-event", (event) => {
  const message = event.detail;
  if (message.schema !== "fastdoc.surface-host-event.v1") return;

  switch (message.type) {
    case "ready": console.log(message.documentPath); break;
    case "dirty": setUnsavedBadge(message.dirty); break;
    case "saved": console.log(message.path, message.byteCount); break;
    case "error": showError(message.operation, message.message); break;
    case "unmounted": releasePartnerResources(); break;
  }
});

Среда	Где встречается	Канал события
WKWebView, WebKitGTK	macOS, iOS, Linux	обработчик сообщений с именем fastdocHost
WebView2	Windows	window.chrome.webview, событие WebMessageReceived
Обычный браузер, без обёртки	везде	событие DOM fastdoc-host-event

Выбирать канал не нужно: каждое событие поверхность отправляет во все три сразу. Хост слушает тот, который есть у него, и не знает про остальные.

Честный статус Surface Host

Сегодня это переносимая поверхность с ограниченным набором: её можно вставить в своё окно и убрать обратно, а наружу она отдаёт события ready, dirty, saved, error и unmounted. Этого хватает, чтобы доказать границу встраивания, но полного внешнего интерфейса ко всем функциям редактора и к расширению контекстного меню здесь ещё нет.

Встраивание

<iframe
  src="http://127.0.0.1:9272/?token=a4-local-demo&locale=ru-RU&theme=light"
  title="A4 document editor"
  style="width:100%;height:720px;border:0"
></iframe>

Поверхность сообщает о своих состояниях — ready, dirty, saved, error и unmounted — событием окна fastdoc-host-event. Этого хватает, чтобы знать, что происходит с документом, но не чтобы им управлять: для полного доступа к модели и всему набору операций работайте параллельно через обмен строками JSON или WebSocket.

Известное поведение текущей сборки

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

Что предусмотреть в рабочей установке

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

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

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

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

После разрыва и после сохранения

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

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

Оператору показывайте состояние сеанса — подключение, готовность, несохранённые правки, сохранение, сохранено, ошибка. Человек должен видеть, можно ли сейчас закрывать окно.

Точные имена

Имена событий, схем, глобального объекта и параметров запуска собраны в справочнике Интерфейс поверхности в браузере. Берите их оттуда: на этой странице они приведены для примера и могут отстать.