注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

パラメーターとイベント

パラメーターとイベントは、ウィジェットが Workshop などのホストアプリケーションとやり取りするための主要な仕組みです。パラメーターを使うと、ホストアプリケーションからウィジェットにデータを渡せます。イベントを使うと、ウィジェットからホストアプリケーションに情報を伝えられます。

カスタムウィジェットを開発する際は、ユーザーがウィジェットの動作を設定してホストアプリケーションとやり取りできるようにパラメーターを定義し、双方向の通信を可能にするためにイベントを定義します。このページでは、利用可能なパラメーターのデータ型、書式の要件、およびイベントの使用方法について説明します。

制約

ウィジェット設定ファイルには、パラメーターとイベントをそれぞれ最大50個まで定義できます。パラメーターとイベントの ID は、camelCase 形式である必要があります。

パラメーター

パラメーターを使うと、ウィジェットとホストアプリケーションで状態を共有できます。パラメーターは、プリミティブ型、プリミティブ型の配列、およびオブジェクトセット型として定義できます。

パラメーターのデータ型

データ型	説明	形式	例
`boolean`	ブール値 (true/false)	ブール値	`true` または `false`
`date`	暦日	ISO 8601 形式: `YYYY-MM-DD`	`"2023-12-31"`
`number`	数値	数値	`42` または `3.14159`
`string`	テキスト値	文字列	`"Hello World"`
`timestamp`	タイムゾーンを含む日時	ISO 8601 形式: `YYYY-MM-DDThh:mm:ss.sssZ`	`"2023-12-31T23:59:59.999Z"`
`objectSet`	オブジェクトセット	オブジェクトセット RID	`ri.object-set.main.temporary-object-set.2af08bf0-3feb-416e-9e34-ad604940581b`
`scenario`	オントロジーシナリオへの参照	シナリオ RID	`ri.actions..scenario.2af08bf0-3feb-416e-9e34-ad604940581b`

オブジェクトセットパラメーターを使うと、カスタムウィジェットとホストアプリケーションの間でオブジェクトセットを渡せます。オブジェクトセットには、固定リストとして、またはオブジェクトタイプやインターフェースに適用するフィルターとして、0個以上のオブジェクトを含められます。オブジェクトセットパラメーターは、オントロジー SDK（OSDK）のオブジェクトタイプまたはインターフェースを使用して、ウィジェット設定ファイル内で定義する必要があります。

シナリオパラメーターを使うと、カスタムウィジェットとホストアプリケーションの間でオントロジーシナリオを渡せます。シナリオパラメーターの値は、シナリオへの参照（RID）です。ウィジェットでは、この RID を OSDK とともに使用して、シナリオの隔離されたサンドボックス内でオブジェクトを読み取り、アクションを適用できます。シナリオパラメーターは、オントロジーシナリオでのみ利用可能です。

利用できないパラメーターのデータ型

オブジェクトセットフィルターや構造体などのデータ型は、現在、カスタムウィジェットのファーストクラスのパラメーター型としてサポートされていません。

パラメーター定義での使用方法

ウィジェット設定ファイルでパラメーターを定義する際は、適切なデータ型を指定します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  parameters: {
    // プリミティブパラメーターの例
    startDate: {
      type: "date",
      displayName: "Start Date"
    },
    // 配列パラメーターの例
    tags: {
      type: "array",
      subType: "string",
      displayName: "Tags"
    },
    // オブジェクトセットパラメーターの例
    flights: {
      type: "objectSet",
      allowedType: Flight,
      displayName: "Flights"
    }
  }
}

イベント

イベントを使うと、ウィジェットからホストアプリケーション（Workshop など）に情報を伝え、副次的効果をトリガーしたり、パラメーターを更新したりできます。イベントは、ウィジェット設定ファイルでパラメーターとともに定義できます。

イベントを定義する

イベントは、ウィジェット設定ファイルで次の構造を使用して定義します。

Copied!1
2
3
4
5
6
7
8
{
  events: {
    myEventId: {
      displayName: "Human-readable event name",
      parameterUpdateIds: ["parameter1", "parameter2"],
    },
  },
}

parameterUpdateIds フィールドでは、このイベントがトリガーされたときに更新できるパラメーターを指定します。

Workshop でのパラメーターとイベントのバインド

Workshop では、ウィジェットの設定パネルで、ウィジェットのパラメーターを Workshop 変数に、ウィジェットのイベントを Workshop イベントにバインドできます。これにより、双方向の通信が可能になります。

Workshop は、パラメーターのバインドを通じてウィジェットにデータを渡せます。ウィジェットは、イベントを発行してこれらのパラメーターを更新できます。
Workshop イベントをウィジェットのイベントにバインドして、Workshop で副次的効果をトリガーすることもできます。

例

以下に、ウィジェットの設定と React での使用方法の両方を示す完全な例を示します。

プリミティブパラメーターとイベント

まず、設定ファイルでパラメーターとイベントを定義します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "simpleCounter",
  name: "Simple Counter",
  description: "A minimal counter example",
  type: "workshop",
  parameters: {
    name: {
      displayName: "Name",
      type: "string",
    },
    count: {
      displayName: "Count",
      type: "number",
    },
  },
  events: {
    updateCount: {
      displayName: "Update Count",
      parameterUpdateIds: ["count"],
    },
  },
});

次に、ウィジェットコンポーネントでこれらのパラメーターとイベントを使用します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { useFoundryWidgetContext } from "@osdk/widget.client-react";
import React, { useCallback } from "react";
import type SimpleCounterConfig from "./simpleCounter.config.js";

const useWidgetContext = useFoundryWidgetContext.withTypes<typeof SimpleCounterConfig>();

export const Widget = () => {
  const { parameters, emitEvent } = useWidgetContext();

  const name = parameters.values.name ?? "World";
  const count = parameters.values.count ?? 0;

  const increment = useCallback(() => {
    emitEvent("updateCount", {
      parameterUpdates: { count: count + 1 },
    });
  }, [emitEvent, count]);

  return (
    <div>
      <h1>Hello, {name}!</h1>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
};

オブジェクトセットパラメーター

まず、設定ファイルでパラメーターとイベントを定義します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { Flight } from "@custom-widget/sdk";
import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "flights",
  name: "Flights Example",
  description: "An example with flights",
  type: "workshop",
  parameters: {
    flights: {
      displayName: "Flights",
      allowedType: Flight,
      type: "objectSet",
    },
  },
  events: {},
});

オブジェクトセットパラメーターを使用する場合は、OSDK クライアントを FoundryWidget コンポーネントに渡す必要があります。データの取得に @osdk/react の useObjectSet フックを使用するには、ウィジェットを OsdkProvider2 でラップすることも必要です。このプロバイダーにより、自動キャッシュ、読み込み状態、およびリアルタイム更新を提供する試験的な React フックが有効になります。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { FoundryWidget } from "@osdk/widget.client-react";
import { OsdkProvider2 } from "@osdk/react/experimental";
import { createRoot } from "react-dom/client";
import FlightsConfig from "./flights.config.js";
import { client } from "./client.js";
import { Widget } from "./Widget.js";

const root = document.getElementById("root")!;

createRoot(root).render(
  <FoundryWidget config={FlightsConfig} client={client}>
    <OsdkProvider2 client={client}>
      <Widget />
    </OsdkProvider2>
  </FoundryWidget>
);

次に、ウィジェットコンポーネントでこれらのパラメーターとイベントを使用します。useObjectSet は、null または undefined のオブジェクトセットを指定して呼び出すことができないため、以下のパターンでは、オブジェクトセットが利用可能になってから表示される別のコンポーネントを使用しています。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import { Flight } from "@custom-widget/sdk";
import type { ObjectSet } from "@osdk/api";
import { useObjectSet } from "@osdk/react/experimental";
import { useFoundryWidgetContext } from "@osdk/widget.client-react";
import React from "react";
import type FlightsConfig from "./flights.config.js";

const useWidgetContext = useFoundryWidgetContext.withTypes<typeof FlightsConfig>();

export const Widget = () => {
  const { parameters } = useWidgetContext();

  const flightsParam = parameters.values.flights;

  if (flightsParam == null) {
    return <div>Select an object set</div>;
  }

  return <FlightsView objectSet={flightsParam.objectSet} />;
};

const FlightsView = ({ objectSet }: { objectSet: ObjectSet<Flight> }) => {
  const { data: flights, isLoading, error } = useObjectSet(objectSet);

  if (isLoading) {
    return <div>Loading flights...</div>;
  }

  if (error) {
    return <div>Error loading flights</div>;
  }

  return (
    <div>
      <p>Flights: {flights?.map(f => ...)}</p>
    </div>
  );
};

オブジェクトセットパラメーターの値には、オブジェクトセット RID に加えて、利便性のためにインスタンス化された OSDK オブジェクトセットも含まれます。オブジェクトセットの定義が変更された場合、またはホストアプリケーションでデータが無効化された場合、パラメーター値に含まれるオブジェクトセット RID とインスタンス化された OSDK オブジェクトセットが更新されます。useObjectSet およびクエリ、アクション、キャッシュ用のその他の React フックについては、@osdk/react のドキュメント ↗を参照してください。

オブジェクトセットパラメーターを更新する

OSDK の ObjectSet を使用してパラメーターを更新するイベントを発行することで、オブジェクトセットパラメーターを更新できます。

まず、設定ファイルで、parameterUpdateIds にオブジェクトセットパラメーターを指定してイベントを定義します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Flight } from "@custom-widget/sdk";
import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "flights",
  name: "Flights Example",
  description: "An example with flights",
  type: "workshop",
  parameters: {
    flights: {
      displayName: "Flights",
      allowedType: Flight,
      type: "objectSet",
    },
  },
  events: {
    updateFlights: {
      displayName: "Update Flights",
      parameterUpdateIds: ["flights"],
    },
  },
});

次に、emitEvent を使用して、オブジェクトセットパラメーターを新しい ObjectSet で更新します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { Flight } from "@custom-widget/sdk";
import { useFoundryWidgetContext } from "@osdk/widget.client-react";
import React, { useCallback } from "react";
import { client } from "./client.js";
import type FlightsConfig from "./flights.config.js";

const useWidgetContext = useFoundryWidgetContext.withTypes<typeof FlightsConfig>();

export const Widget = () => {
  const { parameters, emitEvent } = useWidgetContext();

  const filterToLongFlights = useCallback(() => {
    const longFlights = client(Flight).where({
      duration: { $gt: 500 },
    });

    emitEvent("updateFlights", {
      parameterUpdates: { flights: longFlights },
    });
  }, [emitEvent]);

  return (
    <div>
      <button onClick={filterToLongFlights}>Show Long Flights</button>
    </div>
  );
};

イベントを発行すると、SDK は ObjectSet の定義から一時的なオブジェクトセットを作成し、生成された RID をホストアプリケーションに送信します。同じイベントが短時間に連続して複数回発行された場合は、最後の呼び出しのみが送信され、競合状態を防ぐためにそれ以前の呼び出しは破棄されます。

SDK が一時的なオブジェクトセットを作成する際に発生するネットワーク障害などのエラーは、呼び出し元には通知されません。

ウィジェットで OSDK を使用して、オブジェクトセットパラメーター内のデータを変更するオントロジーアクションを適用する場合は、アクション時にホストデータを更新するの説明に従って、データの自動更新を有効にできます。

←

PREVIOUSウィジェットセットで Ontology SDK (OSDK) を使用する

NEXTウィジェットセットに追加のウィジェットを追加する

→