Extension型オブジェクトを使って変更を伝達する

Extensionは、そのビジュアルパーツ独自の情報を、ビジュアルパーツとData Visualizerの間で伝達しあうために使用するオブジェクト型です。 以下のような場合に使用します。

  • Panel Optionに設定項目を設け、その設定の変更をData Visualizerからビジュアルパーツに伝達する

  • ビジュアルパーツ上でのユーザーの操作をData Visualizerに伝達する

また、Extensionの内容は、Data Visualizerによりウェブブラウザー内のストレージ(IndexedDB)に永続化されます。 そのため、Screenを切り替えたり、ウェブブラウザーを閉じたあとData Visualizerを再表示したりしても状態を再現することができます。

Panel Optionの設定項目変更をData Visualizerからビジュアルパーツに伝達する

Data Visualizer上でのPanel Optionが変更されると、その情報はExtensionオブジェクトを使って以下のようにビジュアルパーツに伝達されます。

これにより、例えば、Panel Optionでビジュアルパーツの背景色を変更することが可能になります。

../_images/panel-option-change.png

図 16 Panel Optionでの設定変更(添付サンプルSensor Valueの例)

  1. Data Visualizerにビジュアルパーツが読み込まれると、ビジュアルパーツの持つmetadata.panelOptionConfig.extensionConfigsにより、Panel Optionに表示される項目(テキスト入力ボックス、プルダウン選択など)が決定します。

    panelOptionConfigには、Panel Optionの各項目をExtensionのどの項目に関連付けるかが定義されています。

  2. Panel Optionでユーザーが設定を変更すると、上記の関連付けに従って、Extensionオブジェクトの内容が書き換えられます。

  3. Data Visualizer上でExtensionオブジェクトの内容が書き換えられると、Extensionオブジェクトの変更イベント(event.extension)が発生します。

  4. ビジュアルパーツ側に実装されたイベントハンドラがExtensionオブジェクトを受け取ります。ビジュアルパーツは、受け取ったExtensionオブジェクトをバリデーションしたうえで、Extensionの情報に従って表示を更新します。

  5. Data Visualizerは、Panel Optionの変更をウェブブラウザー内のストレージ(IndexedDB)に永続化します。

../_images/data-visualizer-to-visual-part.drawio.png

図 17 Panel Optionの設定項目変更をData Visualizerからビジュアルパーツに伝達する

ビジュアルパーツ上でのユーザー操作をData Visualizerに伝達する

ビジュアルパーツ上でのユーザー操作をData Visualizerに伝達する際には、以下のようにExtensionオブジェクトが使用されます。

これにより、例えば、凡例をクリックすることによる表示/非表示の切り替えを、Data Visualizer側で永続化することがきます。

../_images/click-legend.png

図 18 凡例をクリックすることによる表示/非表示切り替え(添付サンプルHorizontal Barsの例)

  1. ユーザーがビジュアルパーツ上で操作可能な部分(ボタンなど)を操作すると、ビジュアルパーツ内の実装によりExtensionの差分情報が作成されます。

  2. Extensionの差分情報は、Extensionオブジェクトの変更イベント(event.extensionPatch)により、Data Visualizer に送信されます。

  3. Data VisualizerがextensionPatchを受け取ります。Data Visualizerは、この内容をウェブブラウザー内のストレージ(IndexedDB)に永続化します。

../_images/visual-part-to-data-visualizer.drawio.png

図 19 ビジュアルパーツ上でのユーザー操作をData Visualizerに伝達する

Extensionのバリデーションを実装する

Data Visualizerとビジュアルパーツがデータをやり取りするExtension型は、ビジュアルパーツごとにそのプロパティが異なります。 そのため、 data-viz-visual-parts-sdk の定義では、Extensionには任意のオブジェクトが使用できるように定義されています。

ビジュアルパーツを実装する際には、Extension型のオブジェクトを受け取ったビジュアルパーツの側がオブジェクトのバリデーションを行うようにしてください。

data-viz-create-visual-parts-react により作成されたワークスペースには、Extensionのバリデーションに使用できるよう、スキーマバリデーターのZodがインストールされます。

Zodの代わりにAjvなど他のバリデーターを使用することもできます。 お好みのものを使用してください。

ワークスペースに付属のサンプルでは、Zodを使用しています。

Zodの使用例

以下は、あるビジュアルパーツのExtensionの型定義と、バリデーションを行う parse 関数の例です。

このビジュアルパーツでは、 descriptionbgColorfactor の3つの情報を、ビジュアルパーツ固有の情報として保持しています。

また、ワークスペースに含まれる src/utils/zodestimate 関数により、以下の処理を行っています。

  • 値がスキーマ定義に合致する場合は、現在の値を使用する。

  • 値がスキーマ定義に合致しない場合は、デフォルト値に置き換える。

import { estimate, estimatePartialObject } from 'src/utils/zod'

// カラー設定
const BG_COLOR_TRANSPARENT = 'transparent'
const BG_COLOR_RED = 'red'
const BG_COLOR_GREEN = 'green'
const BG_COLOR_BLUE = 'blue'

// Extension の型を定義
type Extension = {
  description: string
  bgColor: string
  factor: number
}

// Extensionの Default値を設定
export const defaultExtension: Extension = {
  description: 'no settings',
  bgColor: BG_COLOR_TRANSPARENT,
  factor: 1,
}

// Extension のスキーマ定義
export const schema = {
  description: Z.string(),
  bgColor: Z.union([
    Z.literal(BG_COLOR_TRANSPARENT),
    Z.literal(BG_COLOR_RED),
    Z.literal(BG_COLOR_GREEN),
    Z.literal(BG_COLOR_BLUE),
  ]),
  factor: Z.number(),
}

// Extension 各フィールドをチェック
export const parse = (anyExtension: any): Extension => {
  const def = defaultExtension
  const ext = estimatePartialObject<Extension>(anyExtension)

  // eslint-disable-next-line prettier/prettier
  const description = estimate(schema.description, ext.description, def.description)
  const bgColor = estimate(schema.bgColor, ext.bgColor, def.bgColor)
  const factor = estimate(schema.factor, ext.factor, def.factor)

  return {
    description,
    bgColor,
    factor,
  }
}