Двусторонняя привязка

Server SDK связывает HTML-приложения с данными таблиц, результатами формул и совместными обновлениями.

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

Двусторонняя привязка пока экспериментальна. Будущие версии будут содержать несовместимые изменения; API и способы интеграции могут измениться.

Univer Server SDK соединяет обычные страницы HTML, CSS и JavaScript с листом. Электронная таблица сохраняет данные и формулы, в то время как страница предоставляет формы, метрики, диаграммы и деловые взаимодействия. Изменение на вход с обеих сторон обновляет другую сторону. SDK позволяет приложению превратить модель электронной таблицы в калькулятор цитат, панель инструментов или интерактивное бизнес-приложение.

Пример: приложение и связанная таблица

Пример Project Summit показывает рост, цену предложения и сочетание оплаты наличными в качестве элементов управления слева, с полным финансовым учебником справа. Изменение предположения обновляет соответствующие формулы, метрические карты и диаграммы. Пользователи также могут открыть электронную таблицу для проверки входов и расчетов, стоящих за ними.

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

Одна Sheet, несколько интерфейсов

HTML-вид взаимодействует со своим хостом через время выполнения страницы. Binding Engine читает и записывает фактический контент Sheet через собственный экземпляр headless Univer. Univer SDK обрабатывает формулы и совместную работу, а уровень связывания доставляет измененные значения на страницу.

100%

Связанные страницы также обновляются, когда пользователь редактирует электронную таблицу напрямую или другой пользователь вносит совместные изменения. Один HTML-вид может получить доступ к нескольким блокам, для которых он авторизован. Хост загружает один движок на единицу, и каждый движок поддерживает свой собственный экземпляр headless Univer.

Объявление привязок в HTML

Ссылка на данные на элемент сохраняет свой текст или управление синхронизированным автоматически. Ссылки на ячейки используют форму unitId:sheetId:A1. Каждый идентификатор кодируется отдельно с encodeURIComponent, и идентификатор рабочего листа должен оставаться стабильным.

АтрибутНазначение
data-univer-cell-textОтображает значение ячейки как текст элемента.
data-univer-cell-modelСинхронизирует клетку и контролирует форму в обоих направлениях.
data-univer-cell-subscribeОбъявляет подписку на ячейку для пользовательского рендеринга JavaScript.
data-univer-range-subscribeОбъявляет подписку прямоугольного диапазона для диаграмм, списков и других потребителей матрицы.

Например, цена единицы находится в B2, количество в B3 и B4 удерживает =B2*B3. Следующий фрагмент шаблона соединяет два входа и общее количество с этими ячейками:

HTML
<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 реальными, авторизованными идентификаторами, а затем загрузите шаблон через Renderer. Формулы определены в Специфике, а страница только читает результаты. Текстовые вводы, вводы чисел, ввод диапазона, флажки, текстовые зоны и одновыборные элементы управления связываются в соответствии с их типами значений.

Графики и действия через JavaScript

Среда выполнения страницы инициализирует window.univerBinding перед запуском любого скрипта шаблона. Объявляют диапазон диаграмм с data-univer-range-subscribe, а затем звонят subscribeRangeById(elementId, callback) для получения матрицы и обновления диаграммы. Компоненты, которые отображают одно значение, используют subscribeCellById().

Используйте getCellState() / getRangeState() для одноразового чтения, setCellValue(), чтобы написать скаляр, и insertRowsWithValues() чтобы вставить строки и заполнить их в одной операции. Подписка сначала обеспечивает текущее состояние, а затем каждое фактическое изменение значения. Локальные правки, совместные правки и результаты прикладной формулы могут все обновить подписку.

Ссылки читают фиксированные координаты и поэтому не следуют исходной записи, когда строки или столбцы вставлены или удалены. Скалярная запись заменяет любую формулу или богатый текст, уже присутствующий в ячейке, поэтому связывают только ячейки, которые удерживают бизнес-вход.

Подключение хоста и Agent

Приложение предоставляет контейнер, HTML-шаблон и loadEngine. Загрузчик разрешает доступ к блоку, настраивает совместную работу и возвращает загруженный движок. Рендеру принадлежит изолированная страница, обмен сообщениями между этой страницей и хостом и жизненный цикл движков, которые он предоставляет. Эта точка входа принимает эти три входа:

TypeScript
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 });}

Генерация шаблонов, редактирование источников, хранение файлов и деловая навигация остаются в компетенции приложения. Агент может генерировать HTML с обязательными декларациями, которые повторно используют данные Спецификация и правила расчета. Позвоните view.inspect.open(), чтобы проверить соответствие между Единицей, Спецификация, ссылка и элемент страницы.

Хост имеет учетные данные совместной работы, а сервер обеспечивает доступ. Сохранить пользовательский интерфейс Sheet и движок без головы в отдельных средах JavaScript, таких как отдельные страницы или ифрамы. Текущие пакеты связывания охватывают лист.

Локальное обновление и подтверждение сохранения

ОперацияЗначение
Запись страницы завершенаМестная операция выполнена, но сервер, возможно, еще не признал ее.
await view.flush()Представляет черновые значения из элементов управления, ждет более ранних записей и подтверждения совместной работы, а затем позволяет редактировать.
await view.prepareToLeave()Оставьте после того, как сохранение увенчается успехом, или позвоните в view.resume(), если навигация отменена.
view.dispose()Выпускает соединения, движки и подписки. Не сохраняет никаких данных.

Подписки обновляют значения на экране после того, как результаты формулы применены. Если сохранение не удается, держать страницу открытой и перепроверить сохранение. Завершенное написание страницы само по себе не означает, что данные были сохранены.

Дальнейшая интеграция

Связанные возможности: работа без интерфейса и серверные расчёты · совместная работа · Agent и автоматизация.

Ко всем возможностям

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.