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

ウィジェットセットを開発してプレビューする

開発中に開発モードを使用すると、未公開のウィジェットコードを Foundry でプレビューできます。開発モードは、お使いのユーザーアカウントに対してのみ公開済みのアセットを置き換えるため、ほかのユーザーには引き続き公開済みのバージョンが表示されます。

このページでは、開発サーバーを起動してウィジェットセットに接続し、Foundry に変更が表示されていることを確認する方法を説明します。

始める前に

ウィジェットセットとそのソースコードが必要です。まだ作成していない場合は、まずウィジェットセットを作成するに沿って進めてください。

開発サーバーを実行する場所を選択します。

開発環境	セットアップ	コマンド
ローカルマシン	ウィジェットセットのコードリポジトリをクローンし、ユーザー生成トークンを作成します。	`npm run dev`
VS Code Workspaces	ウィジェットセットのコードリポジトリをワークスペースで開きます。認証は Foundry が管理します。	`npm run dev:remote`

Workshop で新しいウィジェットをプレビューする

未公開のウィジェットは、カスタムウィジェットのプレイグラウンドと Code Workspaces でプレビューできます。ただし、Workshop では、ウィジェットを選択できるようにするために、まず1回公開する必要があります。初回の公開後は、カスタムウィジェットのプレイグラウンドや Code Workspaces と同様に、Workshop でも開発モードを使用できます。

開発セッションを開始する

ローカルマシンで開発する

ウィジェットセットのコードリポジトリをクローンします。Foundry のコードリポジトリの場合は、VS Code Workspaces または Code Repositories アプリケーションのローカルで作業の手順に沿って進めます。
ユーザー生成トークンを作成します。
ターミナルで FOUNDRY_TOKEN 環境変数を設定します。<token> をご自身のトークンに置き換えます。
```
Copied!1
export FOUNDRY_TOKEN=<token>
```
プロジェクトディレクトリから、プロジェクトの依存関係をインストールします。
```
Copied!1
npm install
```
ローカル開発サーバーを起動します。
```
Copied!1
npm run dev
```
開発サーバーを実行したまま、ターミナルに出力されたセットアップリンクを開きます。このリンクによってサーバーがウィジェットセットに接続され、ウィジェットセットの概要ページが開きます。
ウィジェットを選択して、カスタムウィジェットのプレイグラウンドで開きます。
ソースファイルを編集して保存します。プレイグラウンドが開発バージョンに更新されます。

ターミナルに表示された npm run dev コマンドと開発モードのセットアップリンク。

ウィジェットが更新されない場合は、まずターミナルで開発サーバーが引き続き実行中であることと、最新のセットアップリンクを開いたことを確認します。

VS Code ワークスペースで開発する

ウィジェットセットのコードリポジトリを VS Code ワークスペースで開きます。
ワークスペースが起動するまで待ちます。ウィジェットセットのテンプレートでは、開発サーバーが自動的に起動します。
サーバーが実行されていない場合は、プロジェクトディレクトリから起動します。
```
Copied!1
npm run dev:remote
```
VS Code のプレビューパネルで、プレビューするウィジェットを選択します。
ソースファイルを編集して保存します。プレビューパネルが開発バージョンに更新されます。

VS Code Workspaces の開発サーバーで実行されているウィジェット。

同じワークスペースの開発サーバーから、カスタムウィジェットのプレイグラウンドと Workshop にオーバーライドを提供できます。2台目のサーバーを実行する必要はありません。

開発モードがアクティブであることを確認する

開発モードのコントロールには、表示中のウィジェットのバージョンが示されます。

状態	表示されるバージョン	操作
無効	公開済みのバージョン	開発セッションを開始し、開発モードを有効にして変更をプレビューします。
有効	開発バージョン	編集を続けます。コントロールには、ソースが localhost または VS Code ワークスペースとして表示されます。
有効（非アクティブ）	公開済みのバージョン	表示中のウィジェットを開発していない場合は、何もする必要はありません。それ以外の場合は、開発サーバーが実行中であり、ウィジェットが含まれていることを確認してから、開発モードを再適用します。
一時停止中	公開済みのバージョン	開発バージョンに戻す場合は、開発モードを再開します。

開発モードを開始する

開発モードが無効な場合は、開発モードを開始するコントロールが表示されます。開発モードがウィジェットのオーバーライドを検出できるように、コントロールを選択する前に開発サーバーを起動してください。

非アクティブなセッションを理解する

非アクティブなセッションとは、表示中のウィジェットに対するオーバーライドが開発サーバーにないことを意味します。この状態は、必ずしも解消する必要はありません。たとえば、比較のために別のウィジェットセットのウィジェットを開いた場合や、一部のカスタムウィジェットのみを開発している Workshop アプリケーションを表示した場合、開発モードはセッションが非アクティブであることを示します。このような場合は、公開済みのバージョンが表示されるのが想定どおりの動作です。

表示中のウィジェットを開発する場合は、開発サーバーを起動し、そのウィジェットが含まれていることを確認してから、開発モードを再適用します。

開発モードのメニューに、非アクティブなセッションではウィジェットのオーバーライドが設定されていないことが示されています。

一時停止中のセッションを再開または停止する

再開するを選択すると、開発バージョンが再び表示されます。中止を選択すると、開発モードのセッションが終了し、公開済みのバージョンを引き続き使用できます。

開発ソースを特定する

アクティブなローカルセッションでは、ソースとして localhost が表示されます。

アクティブな VS Code Workspaces セッションでは、ソースとしてワークスペースが表示されます。

開発モードが有効で、VS Code Workspaces 内の開発サーバーを使用しています。

開発モードは個人用の一時的なものです。ほかのユーザーに表示される内容は変わらず、24時間後に期限切れになります。

プレビュー環境を選択する

開発モードがアクティブになったら、テストする内容に適した環境を使用します。

プレビュー環境	用途
カスタムウィジェットのプレイグラウンド	1個のウィジェットをさまざまなサイズでテストし、パラメーター値を変更し、発行されたイベントとパラメーターの更新を確認します。
Workshop	Workshop のパラメーターバインディング、イベント、周囲のコンポーネント、アプリケーションのレイアウトとともにウィジェットをテストします。
VS Code のプレビューパネル	開発ワークスペースを離れずにウィジェットをプレビューします。

プレイグラウンドには、パラメーターのコントロールとイベントのメッセージログが表示されます。

カスタムウィジェットのプレイグラウンドで開発モードになっているウィジェット。

Workshop では、ウィジェットを使用するアプリケーションに開発バージョンが表示されます。

Workshop で開発モードになっているウィジェット。

さまざまな種類の変更をプレビューする

開発モードでは、ソースコードの変更とウィジェットの設定変更を異なる方法で処理します。

変更	プレビュー方法
コンポーネントのコードまたはスタイル	ファイルを保存します。開発サーバーの実行中は、ウィジェットが自動的に更新されます。
ウィジェット設定ファイル内のパラメーターまたはイベント	ファイルを保存してから、開発モードを再適用します。ローカルサーバーの場合は、ターミナルのセットアップリンクを再度開きます。VS Code Workspaces では、プレビューパネルを更新します。

パラメーターとイベントを追加または変更する

ウィジェットのテンプレートでは、main.config.ts などの設定ファイルでパラメーターとイベントを定義します。次の例では、3個のパラメーターと2個のイベントを定義しています。

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
import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "<Widget ID>", // プロジェクト内のウィジェットの一意の識別子
  name: "<Widget Name>", // ウィジェットのわかりやすい名前
  description: "<Widget Description>", // ウィジェットのわかりやすい説明
  type: "workshop",
  parameters: {
    headerText: {
      displayName: "Widget title",
      type: "string",
    },
    showWarning: {
      displayName: "Show warning callout",
      type: "boolean",
    },
    todoItems: {
      displayName: "Todo items",
      type: "array",
      subType: "string",
    },
  },
  events: {
    updateHeader: {
      displayName: "Update header",
      parameterUpdateIds: ["headerText"],
    },
    updateTodoItems: {
      displayName: "Update todo items",
      parameterUpdateIds: ["todoItems"],
    },
  },
});

@osdk/widget.vite-plugin のバージョン 3.34.0 以降では、開発モードでパラメーターとイベントの変更をプレビューできます。サポートされているデータ型や、ウィジェットからパラメーターを読み取ってイベントを発行する例については、パラメーターとイベントを参照してください。

ランタイムの制限を理解する

ブラウザーストレージ

カスタムウィジェットのランタイムは、データを永続化するブラウザー API に対応していません。これには次の API が含まれます。

Web Storage API ↗（localStorage と sessionStorage）
IndexedDB API ↗

ウィジェット間で状態を共有するには、Workshop 変数など、ホストアプリケーションで設定したパラメーターを使用します。状態を保存するには、Workshop 変数の保存済み状態を使用するか、オントロジーにデータを書き込みます。

Web Workers API

カスタムウィジェットのランタイムは、Web Workers API ↗ を通じて専用 Web ワーカーに対応しています。専用ワーカーを使用すると、ブラウザーのメインスレッドをブロックせずに JavaScript タスクを実行できます。

このランタイムは、共有ワーカー ↗やサービスワーカー ↗に対応していません。

Workshop のウィジェットの状態

デフォルトでは、Workshop はカスタムウィジェットを含むレイアウトが非表示になると、そのウィジェットをアンマウントします。これにより、ウィジェットの iframe に保持されている状態が破棄されます。画面遷移後もローカルの状態を保持するには、ウィジェットがマウントされたままになるようにウィジェット表示の最適化を設定します。

ネットワークリクエスト

カスタムウィジェットのランタイムでは、ユーザーが設定できない制限の厳しいコンテンツセキュリティポリシーが使用されます。このランタイムは外部へのリクエストをブロックし、オントロジー以外の API に対応していません。外部サービスにアクセスするには、関数や Webhook など、リクエストをラップする Foundry リソースを使用します。

テーマ設定

CSS メディアクエリと JavaScript を使用して、親アプリケーションの配色を検出できます。実装の詳細と例については、ダークテーマへの対応を参照してください。

トラブルシューティング

カスタムウィジェットの開発中に発生するブラウザーのクラッシュ、パフォーマンスの問題、予期しない動作への対処については、トラブルシューティングを参照してください。

←

PREVIOUSWorkshop にウィジェットを埋め込む

NEXTウィジェットセットを公開する

→