Двусторонняя привязка
Server SDK связывает HTML-приложения с данными таблиц, результатами формул и совместными обновлениями.
Экспериментальная возможность
Двусторонняя привязка пока экспериментальна. Будущие версии будут содержать несовместимые изменения; API и способы интеграции могут измениться.
Univer Server SDK подключает обычные страницы HTML, CSS и JavaScript к Sheet. Таблица хранит данные и формулы, а страница предоставляет формы, показатели, графики и бизнес-интерфейс. Изменения ввода с любой стороны поступают на другую. Так модель таблицы можно превратить в калькулятор сметы, дашборд или интерактивное приложение.
Пример: приложение и связанная таблица
В Project Summit слева находятся элементы управления ростом, ценой предложения и долей оплаты наличными, справа — полная финансовая модель. Изменение предположений обновляет формулы, карточки показателей и графики. В таблице можно проверить исходные данные и расчёты.
На снимке показана локальная модель браузера. Совместное редактирование и сохранение обеспечиваются интеграцией ниже. Нажмите на изображение для увеличения.
Одна Sheet, несколько интерфейсов
HTML-представление общается с хостом через среду страницы. Binding Engine читает и изменяет реальные данные Sheet в собственном экземпляре Headless Univer. Univer SDK выполняет формулы и совместную работу, а слой привязки передаёт изменённые значения странице.
Прямые изменения таблицы и правки других пользователей также обновляют связанные страницы. Одно HTML-представление может обращаться к нескольким разрешённым Units. Хост загружает Engine для каждой Unit; каждый Engine владеет независимым экземпляром Headless Univer.
Объявление привязок в HTML
Объявляйте ссылки на данные в элементах для автоматической синхронизации текста и форм. Формат ячейки: unitId:sheetId:A1. Кодируйте каждый ID отдельно через encodeURIComponent и используйте стабильный ID листа.
| Атрибут | Назначение |
|---|---|
data-univer-cell-text | Показать значение ячейки как текст элемента. |
data-univer-cell-model | Двусторонне синхронизировать ячейку и элемент ввода. |
data-univer-cell-subscribe | Объявить подписку на ячейку для JavaScript-отрисовки. |
data-univer-range-subscribe | Объявить подписку на прямоугольный диапазон для графиков, списков и матриц. |
Например, B2 содержит цену, B3 — количество, а B4 — формулу =B2*B3. Этот фрагмент шаблона связывает ввод и итог:
<label> Цена за единицу <input type="number" min="0" step="0.01" data-univer-cell-model="book:sheet:B2" /></label><label> Количество <input type="number" min="0" step="1" data-univer-cell-model="book:sheet:B3" /></label><p>Итого: <span data-univer-cell-text="book:sheet:B4"></span></p>Замените book и sheet реальными разрешёнными ID и загрузите шаблон через Renderer. Формулы определяются в Sheet, страница читает результаты. Поддерживаются текстовые и числовые поля, ползунки, флажки, textarea и одиночный выбор с подходящими типами значений.
Графики и действия через JavaScript
Среда страницы предоставляет window.univerBinding до запуска скриптов шаблона. Объявите диапазон графика через data-univer-range-subscribe, затем получайте матрицу в subscribeRangeById(elementId, callback) и обновляйте график. Для одиночных значений используйте subscribeCellById().
getCellState() / getRangeState() читают состояние однократно, setCellValue() записывает скаляр, insertRowsWithValues() вставляет строки с данными. Подписки сначала выдают текущее состояние, затем реальные изменения значений. Обновления вызывают локальные и совместные правки и применение результатов формул.
Ссылки используют фиксированные координаты и не следуют за исходной записью после вставки или удаления строк и столбцов. Запись скаляра заменяет формулы или форматированный текст, поэтому привязывайте ячейки бизнес-ввода.
Подключение хоста и Agent
Приложение предоставляет контейнер, HTML и loadEngine. Загрузчик проверяет доступ к Unit, настраивает совместную работу и возвращает загруженный Engine. Renderer управляет изолированной страницей, сообщениями и полученными Engines. Эта функция принимает три входных параметра:
import { renderHtmlView, type RenderHtmlViewOptions,} from '@univerjs-labs/html-view-renderer/render';export function createPreview( container: HTMLElement, html: string, loadEngine: RenderHtmlViewOptions['loadEngine'],) { return renderHtmlView({ container, html, loadEngine });}Генерация шаблонов, редактирование кода, хранение файлов и навигация принадлежат приложению. Agent может создавать HTML с привязками к данным и расчётам Sheet. view.inspect.open() показывает связи Unit → Sheet → ссылка → элемент страницы.
Учётные данные совместной работы остаются у хоста, сервер проверяет доступ. UI Sheet и Headless Engine размещаются в разных JavaScript-средах, например на отдельных страницах или в iframe. Текущие пакеты ориентированы на Sheet.
Локальное обновление и подтверждение сохранения
| Операция | Значение |
|---|---|
| Запись страницы завершена | Локальная операция выполнена; серверное подтверждение может ещё ожидаться. |
await view.flush() | Отправить черновики ввода, дождаться предыдущих записей и подтверждения, затем продолжить редактирование. |
await view.prepareToLeave() | Приостановить редактирование и сохранить. После успеха выйти; при отмене вызвать view.resume(). |
view.dispose() | Освободить соединения, Engines и подписки; автоматического сохранения нет. |
Подписки обновляют отображаемые значения после применения результатов формул. При ошибке сохранения оставьте страницу открытой и повторите сохранение. Завершённая локальная запись сама по себе не означает сохранение данных.
Дальнейшая интеграция
- Репозиторий и описание SDK
- API Binding Engine
- HTML-атрибуты привязки
- Интеграция Renderer
- JavaScript API страницы
Связанные возможности: работа без интерфейса и серверные расчёты · совместная работа · Agent и автоматизация.
Насколько полезно это руководство?