双方向バインディング

Server SDK で HTML アプリをスプレッドシートのデータ、数式結果、共同編集の更新に接続します。

実験的な機能

双方向バインディングは現在、実験段階です。今後のバージョンには破壊的変更が含まれ、API や導入方法が変更される場合があります。

Univer Server SDKは、通常のHTML、CSS、およびJavaScriptページをシートに接続します。スプレッドシートは、データと式を保持します。一方、ページはフォーム、メトリック、チャート、およびビジネスのやり取りを提供します。 いずれかのサイドの更新に入力する変更。 SDKは、アプリケーションは、スプレッドシートモデルを引用符、ダッシュボード、またはインタラクティブなビジネスアプリケーションに変えます。

例:アプリとスプレッドシートの連動

プロジェクトサミットでは、成長を促進し、価格を提供したり、左側のコントロールとしてキャッシュ・ペイメント・ミックスを、右上のフル・ファイナンシャル・ワークブックで提供しています。関連する式、メトリック・カード、チャートの更新を前提に変更します。ユーザーは、スプレッドシートを開いて、入力と計算を検査することもできます。

スクリーンショットは、ローカルブラウザで実行されているモデルを示しています。 共有編集と永続性は、以下のコラボレーション統合を使用します。 画像をクリックすると、フルサイズで表示できます。

一つの Sheet、複数のインターフェース

HTMLビューは、ページランタイムを介してホストと通信します。 結合エンジンは、独自のheadless Univerインスタンスを介して実際のシートコンテンツを読み込み、書き込みます。 Univer SDKは、式とコラボレーションを処理します。 結合層は、ページに変更された値を提供します。

100%

ユーザーがスプレッドシートを直接編集したり、別のユーザーが共同変更をしたりすると、境界ページも更新されます。単一のHTMLビューは、承認されるユニットに複数のユニットにアクセスすることができます。ホストは1つのエンジンを1つのユニットにロードし、各エンジンは独自の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を保持しています。次のテンプレートフラグメントは2つの入力とそれらのセルの合計を接続します。

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を介してテンプレートをロードします。 式はシートで定義され、ページは結果を読むだけです。 テキスト入力、数字入力、範囲入力、チェックボックス、テクスチャ、およびシングルセレクトコントロールは、その値タイプに応じてバインドします。

JavaScript でグラフと操作を拡張する

このページのランタイムは、任意のテンプレートスクリプトが実行される前に window.univerBinding を初期化します。チャート範囲を data-univer-range-subscribeで宣言し、subscribeRangeById(elementId, callback)を呼び出して、行列を受信し、チャートを更新します。単一の値を表示するコンポーネントは subscribeCellById().

getCellState() / getRangeState()をワンタイム読み取りに使用し、setCellValue()はスカラーを書き、insertRowsWithValues()で行を出し、1つの操作で埋めます。サブスクリプションは、現在の状態を最初に配信し、実際の値が変更されます。ローカル編集、共同編集、および応用式の結果はすべてサブスクリプションを更新できます。

参照は固定座標を読み、したがって、行や列がインサートまたは削除されたときに元のレコードに従わない。スカラーの書き込みは、既にセルに存在する式または豊富なテキストを置き換えるので、ビジネス入力を保持するセルだけを結合します。

ホストと Agent を接続する

アプリケーションは、コンテナ、HTMLテンプレート、loadEngineを提供します。 ローダーは、ユニットへのアクセスを承認し、コラボレーションを設定し、ロードされたエンジンを返します。 Rendererは、隔離されたページ、そのページとホスト間のメッセージ、および配信するエンジンのライフサイクルを所有しています。 このエントリポイントは、これらの3つの入力を受け入れます。

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()を呼び出して、ユニット、シート、参照、ページ要素間の通信を検査します。

ホストはコラボレーション認証情報を保持し、サーバーはアクセスを強制します。シートUIとヘッドレスエンジンを別々のJavaScript環境で保持し、別々のページやiframeなど。現在のバインディングパッケージはシートをカバーします。

ローカル更新と保存確認を分ける

操作意味
ページの書き込み完了ローカル操作は実行されていますが、サーバーはまだそれを認めていない可能性があります。
await view.flush()コントロールから値草案を提出し、以前の書き込みとコラボレーションの承認を待ち、その後、編集が続行できるようにします。
await view.prepareToLeave()編集と保存を繰り返します。 保存が成功したら、ナビゲーションがキャンセルされた場合、またはview.resume()を呼び出します。
view.dispose()接続、エンジン、サブスクリプションを解放します。任意のデータを保存しません。

サブスクリプションは、式の結果が適用されると画面上の値を更新します。 保存が失敗した場合は、ページが開き、保存を再試行してください。 完了したページは、データが保存されているという意味ではありません。

次の接続手順

関連機能:ヘッドレスとサーバー計算 · リアルタイム共同編集 · Agent と自動化。

機能一覧に戻る

このガイドはいかがですか?

© 2026 DreamNum Co., Ltd.