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

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

- Human documentation: [https://docs.univer.ai/ru-RU/overview/features/shared/binding](https://docs.univer.ai/ru-RU/overview/features/shared/binding)

- Agent Markdown: [https://docs.univer.ai/ru-RU/overview/features/shared/binding.md](https://docs.univer.ai/ru-RU/overview/features/shared/binding.md)

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.3.0`

- Source: [features/shared/binding.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/binding.ru-RU.mdx)

---

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

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

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

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

![Project Summit: элементы управления, показатели и графики рядом со связанной финансовой моделью Univer Sheets](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/features/binding/project-summit-app-sheets.png)

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

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

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

```mermaid
flowchart LR
    P["HTML-приложение<br/>Ввод · показатели · графики"]
    E["Хост + Binding Engine<br/>Headless Sheet"]
    S["Сервис совместной работы<br/>Та же Sheet Unit"]
    T["Редактор Sheet"]
    P <-->|"Чтение · запись · подписка"| E
    E <-->|"Совместная работа SDK"| S
    T <-->|"Редактирование · синхронизация"| S
```

Прямые изменения таблицы и правки других пользователей также обновляют связанные страницы. Одно 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`. Этот фрагмент шаблона связывает ввод и итог:

```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` реальными разрешёнными 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. Эта функция принимает три входных параметра:

```ts
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](https://github.com/dream-num/univer-data-binding-sdk)
- [API Binding Engine](https://github.com/dream-num/univer-data-binding-sdk/blob/main/packages/binding-engine/README.md)
- [HTML-атрибуты привязки](https://github.com/dream-num/univer-data-binding-sdk/blob/main/packages/html-view/README.md)
- [Интеграция Renderer](https://github.com/dream-num/univer-data-binding-sdk/blob/main/packages/html-view-renderer/README.md)
- [JavaScript API страницы](https://github.com/dream-num/univer-data-binding-sdk/blob/main/packages/html-view-renderer/docs/javascript-api.md)

Связанные возможности: [работа без интерфейса и серверные расчёты](https://docs.univer.ai/ru-RU/overview/features/shared/server-calculation.md) · [совместная работа](https://docs.univer.ai/ru-RU/overview/features/shared/collaboration.md) · [Agent и автоматизация](https://docs.univer.ai/ru-RU/overview/features/shared/agents.md).

[Ко всем возможностям](https://docs.univer.ai/ru-RU/overview/features.md)
