Двусторонняя привязка
Server SDK связывает HTML-приложения с данными таблиц, результатами формул и совместными обновлениями.
Экспериментальная возможность
Двусторонняя привязка пока экспериментальна. Будущие версии будут содержать несовместимые изменения; API и способы интеграции могут измениться.
Univer Server SDK соединяет обычные страницы HTML, CSS и JavaScript с листом. Электронная таблица сохраняет данные и формулы, в то время как страница предоставляет формы, метрики, диаграммы и деловые взаимодействия. Изменение на вход с обеих сторон обновляет другую сторону. SDK позволяет приложению превратить модель электронной таблицы в калькулятор цитат, панель инструментов или интерактивное бизнес-приложение.
Пример: приложение и связанная таблица
Пример Project Summit показывает рост, цену предложения и сочетание оплаты наличными в качестве элементов управления слева, с полным финансовым учебником справа. Изменение предположения обновляет соответствующие формулы, метрические карты и диаграммы. Пользователи также могут открыть электронную таблицу для проверки входов и расчетов, стоящих за ними.
На скриншоте показана модель, работающая в локальном браузере. Совместное редактирование и персистентность используют интеграцию совместной работы, описанную ниже. Нажмите на изображение, чтобы просмотреть его в полном размере.
Одна Sheet, несколько интерфейсов
HTML-вид взаимодействует со своим хостом через время выполнения страницы. Binding Engine читает и записывает фактический контент Sheet через собственный экземпляр headless Univer. Univer SDK обрабатывает формулы и совместную работу, а уровень связывания доставляет измененные значения на страницу.
Связанные страницы также обновляются, когда пользователь редактирует электронную таблицу напрямую или другой пользователь вносит совместные изменения. Один 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. Следующий фрагмент шаблона соединяет два входа и общее количество с этими ячейками:
<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. Загрузчик разрешает доступ к блоку, настраивает совместную работу и возвращает загруженный движок. Рендеру принадлежит изолированная страница, обмен сообщениями между этой страницей и хостом и жизненный цикл движков, которые он предоставляет. Эта точка входа принимает эти три входа:
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() | Выпускает соединения, движки и подписки. Не сохраняет никаких данных. |
Подписки обновляют значения на экране после того, как результаты формулы применены. Если сохранение не удается, держать страницу открытой и перепроверить сохранение. Завершенное написание страницы само по себе не означает, что данные были сохранены.
Дальнейшая интеграция
- Репозиторий и описание SDK
- API Binding Engine
- HTML-атрибуты привязки
- Интеграция Renderer
- JavaScript API страницы
Связанные возможности: работа без интерфейса и серверные расчёты · совместная работа · Agent и автоматизация.
Насколько полезно это руководство?