カスタムウィジェット

Prev Next

HTML、CSS、JavaScriptを使用して、Tulipで独自のウィジェットを作成しましょう

Who can use this feature

Users on Professional plans and above.

Requirement to use Custom Widget

Please allow Outgoing access to Custom Widgets. See Networking requirements for a Tulip Cloud Deployment to learn more.* *.tulip-custom-widgets.com

アプリにドラッグ&ドロップする項目は「ウィジェット」と呼ばれます。これには、ボタン、画像、入力ボックス、およびツールバーから利用可能なその他の要素が含まれます。

カスタムウィジェットを使用すると、独自のコードを記述して独自のウィジェットを作成でき、それをアプリケーション上にドラッグ&ドロップして操作することができます。この機能により、TulipユーザーはTulipで可能なことの限界を広げることができます。

この機能の概要については、以下の動画をご覧ください:

Tulipライブラリで利用可能なカスタムウィジェットをご覧ください。

カスタムウィジェットの基本

カスタムウィジェットの管理画面は、アカウント設定ページ内にあります。ここでは、ウィジェットの作成や削除を行うことができます。カスタムウィジェットエディタでは、ウィジェットのコードを記述したり、プロパティやイベントを作成したり、ウィジェットをプレビューしたりすることができます。以下は、プロパティとイベントの概要を示す図です:

**プロップ:**プロップとは、カスタムウィジェットとTulipアプリケーション間で共有されるデータのことです。プロップはアプリケーションエディタで公開され、アプリ編集者はそのプロップに関連付ける変数、テーブルレコード、その他の情報を選択できるようになります。

**イベント:**イベントとは、ウィジェットがアプリケーションに送信できるシグナルです。イベントにより、アプリケーションはトリガーで応答することができ、イベントには情報を付随させることができます。

カスタムウィジェットには、アプリエディタ内の「カスタム」ダウンセレクタからアクセスできます。

ウィジェットの作成

Permission Required

Only users with access to account settings (i.e. Account Owners) or users with specific permission to access the custom widget page can use the custom widget editor.

ウィジェットエディタ画面は4つのセクションに分かれています。左下のセクションに記述したコードは、プレビューセクションをクリックすると、そのセクションに表示されます。テスト目的で、プレビューセクション内でプロパティの値を直接変更することができます。

Propsやイベントを操作するための特別な関数が用意されています。

プロパティの値を取得する

Warning

It is not guaranteed that the prop being used by a widget will load before that widget loads, so all props associated with Table record fields, Aggregations, or any other dynamic value should include logic to support cases where they are null at the point the widget is loaded. See this section for details on triggering logic when a prop changes.

//プロパティの値を取得 getValue('My Prop');``//プロパティを変数に格納 let myVariable = getValue('My Prop');

プロパティが変更されたときに処理を実行する

//プロパティの値が変更されるたびに処理を実行getValue('My Prop', (internalVariable) => { doSomething(internalVariable);});

Propsの値を設定する


//テキストプロパティの値を 'hello!' に設定setValue('My Text Prop', 'hello!');

// オブジェクト内の項目の値を設定setValue('My Object Prop', { 'Key inside object': 'new value' });```

### イベントの発生

```**イベントを発生させる**fireEvent('event',*payload*);

//ペイロードなしでイベントを発火fireEvent('My Event');

//ペイロード付きでイベントを発火fireEvent('My Event', myVariable);```

次の図は、アプリ内のカスタムウィジェットを通る情報の流れを示しています。入力変数のデータはプロパティに格納されます。値が変更されるとイベントが発生し、トリガーによってデータが出力変数に格納されます。

![Custom Widget App Setup Diagram](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widget%20App%20Setup%20Diagram.jpg){height="" width=""}

## ウィジェット構築デモ

![Video](https://www.youtube.com/embed/H08-W2M2Ypo?rel=0){height="576" width="1024"}

## アプリのインポート/エクスポート

この機能の詳細については、「[インポートとエクスポート](/r230/docs/import-export)」をご覧ください。

### エクスポート

1. カスタムウィジェットの概要画面で、エクスポートしたいウィジェットの横にある**三点メニュー**を選択します。

![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477703991.png){height="" width=""}

1. 「**エクスポート**」を選択します。

![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477704053.png){height="" width="800"}

### インポート

1. カスタムウィジェットの概要画面で、上部の**3点メニュー**を選択します。

![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477704175.png){height="" width="800"}

1. 「**インポート**」を選択します。

![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477704228.png){height="" width="350"}

1. .json形式のカスタムウィジェットファイルを探します。

## 外部ライブラリを有効にする

外部ライブラリを使用すると、カスタムウィジェットの機能範囲をさらに広げることができます。外部ライブラリは、JavaScript 内で HTML を直接記述するという手作業を代行します。外部ライブラリを使用するには、そのライブラリを使用したい各ウィジェットで有効にする必要があります。

1. ウィジェット内で、ページの右上にある**3つのドットのメニュー**をクリックします。

![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477684182.png){height="" width=""}

1. 「**外部ライブラリを有効にする**」を選択します。

![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477684247.png){height="" width="250"}

1. 有効にしたい**拡張機能**を選択します。

![Screenshot 2025-02-06 at 9.13.14 AM](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-02-06%20at%209.13.14%20AM.png){height="" width=""}

各拡張機能の基本的な機能の説明は以下の通りです:

* **jQuery**- HTML要素の選択や操作をより効率的に行えるようになります。
* **D3 -**データ可視化のゴールドスタンダード。習得には時間がかかりますが、非常に高い柔軟性を備えています。
* **Google Visualization -**その名の通り、可視化を行うための優れたツールです。
* **Lodash -**JavaScriptのデータ型を扱う作業を容易にする、数多くのツールを提供します。
* **ChartJS -**オンラインリソースが豊富で、おそらく最もシンプルなグラフ作成ライブラリです。
* **Moment -**Momentは、日付や時刻を扱うための豊富なツールを提供します。

## ランタイムのバージョン

新しいランタイムにおけるカスタムウィジェットの読み込み方法が更新されました([「カスタムウィジェットの改善点」](/r230/docs/custom-widget-improvements)を参照)。この変更により、`getValue()` などで取得されるウィジェットのプロパティに確実にアクセスできるタイミングが影響を受けます。

ウィジェットが使用しているランタイムのバージョンを確認するには:

* **カスタムウィジェット一覧ページ**またはエディタで、ウィジェットの名前の横に「**Legacy**」バッジが表示されている場合、そのウィジェットは旧ランタイムを使用しています。バッジが表示されていない場合は、新しいランタイムを使用しています。
* 「カスタムウィジェット」情報サイドパネルの「**ランタイム**」セクションを確認してください。
* カスタムウィジェットの「**権限設定」**で、「**カスタムウィジェットランタイム」**のトグルがオンになっている場合、そのウィジェットは新しいランタイムを使用しています。

:::(Info) (NOTE)
By default, newly created Custom Widgets use the old runtime.
:::

カスタムウィジェットのランタイムバージョンを切り替えるには、**権限設定にある**「**カスタムウィジェットランタイム**」トグルを使用してください。![Custom widget runtime toggle](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20widget%20runtime%20toggle.png){height="" width=""}

## 例

以下に、上記で説明した機能の例となる、[Tulip ライブラリ](https://tulip.co/library/)のカスタムウィジェットをいくつか紹介します。

### シンプルなタイマーウィジェット

[シンプルなタイマーウィジェット](https://library.tulip.co/apps/simple-timer-widget)

アプリのワークフロー中に経過時間を追跡するための、使いやすいタイマーウィジェットです。オペレーターはアプリのインターフェースから直接タイマーの開始、停止、リセットを行うことができ、タスクやプロセスの時間計測に役立ちます。

![Screenshot 2025-07-02 at 15.33.20.png](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-07-02%20at%2015.33.20.png){height="" width=""}

### ラジアルゲージウィジェット

[ラジアルゲージウィジェット](https://library.tulip.co/apps/radial-gauge-widget)

このウィジェットは、カスタマイズ可能なラジアルゲージを用いて数値を視覚的に表現します。機械の速度、温度、進捗状況などの指標を、一目で理解しやすい形式で表示するのに最適です。

![Screenshot 2025-07-02 at 15.34.22.png](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-07-02%20at%2015.34.22.png){height="" width=""}

### タイムラインウィジェット

[タイムラインウィジェット](https://library.tulip.co/apps/timeline-widget)

水平方向のタイムライン上にイベントやステップを表示し、ユーザーがプロセスの段階、完了したタスク、または時間軸に基づくデータを一目で把握できるようにします。

![Screenshot 2025-07-02 at 15.34.59.png](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-07-02%20at%2015.34.59.png){height="" width=""}

## ベストプラクティス

### 1. 読み込み時に実行されるウィジェットコードによる予期せぬ副作用を防ぐ

Tulipは、ウィジェットがレンダリングされるたびに、その実際のコードを実行します。これはPlayerだけでなく、カスタムウィジェットエディタ、アプリエディタ、およびステーションのライブプレビューでも同様です。これにより、ウィジェットの正確なライブプレビューが可能になります。 スクリプトの最上位にある副作用を伴うコード(例:API呼び出し、テーブルへの書き込み、通知)は、ウィジェットがレンダリングされるたびに実行されます。これには、エディタでウィジェットが再表示された場合や、プレビューが再読み込みされた場合も含まれます。

現実世界に影響を与える処理は、読み込み時に自動的に実行するのではなく、明示的なトリガー(例:ボタンの押下、ユーザー操作に応じた ``` fireEvent` ``、またはプロパティの変更)の背後で実行するようにしてください。

```// 推奨:アプリが明示的に要求した場合にのみ実行される getValue('TriggerIncrement', (shouldIncrement) => { if (shouldIncrement) { fetch("https://api.example.com/increment-counter", { method: "POST" }); }});

// 悪い例:エディタやプレビュー時を含め、ウィジェットが読み込まれるたびに実行されるfetch("https://api.example.com/increment-counter", { method: "POST" });```ウィジェットがデータを自動的に読み込む必要がある場合は、読み取り専用または冪等なエンドポイントを使用し、繰り返し読み込みによって望ましくない影響が生じないようにしてください。

### 2. 実際の副作用を引き起こさずに反復的にテストする

実際の副作用を伴う本番環境の API を呼び出すウィジェットを開発する際は、反復開発が完了するまでテスト用またはステージング用のエンドポイントを指定し、公開前に本番環境のエンドポイントに切り替えてください。これにより、ウィジェットの編集やプレビューに伴うレコードの重複、通知、その他の副作用を防ぐことができます。

公開後も本番環境で実行する必要があるアクションについては、読み込みのタイミングに依存するのではなく、ウィジェット自身のUIに確認手順を組み込んでください。目に見えるアクション(例:ボタンのクリック)を必須とすることで、ウィジェットを閲覧するユーザーが、その効果がいつ発生するかを制御できるようになります。

```// ウィジェット自体が何度レンダリングされても、// 実際のアクションが実行される前に明示的なクリックが必要ですdocument.getElementById('submitBtn')?.addEventListener('click', () => { fetch("https://api.example.com/submit-order", { method: "POST" });});

3. プロパティの管理 - プロパティ値の検証

カスタムウィジェットがデータを確実に処理できるようにしてください。プロップはウィジェットに情報を渡す手段ですが、その値は変更されたり、初期状態で未定義であったりする場合があります。プロップには特定の型が設定されていても、初期状態では未定義である可能性があり、それがカスタムウィジェットのコードでエラーを引き起こす原因となる可能性があります。適切なパターンに従うことでエラーを防ぎ、ウィジェットの堅牢性を高めることができます。

以下の例では、getValue の 2 番目のパラメータとしてコールバック関数を使用しています。このコールバックは、カスタムウィジェットが更新されたプロップ値を受け取るたびに実行されます。

プロパティの初期値は未定義である可能性があり、後で更新された値を受け取る可能性があるため、更新された値を受け取った時点で確実に設定を適用するようにする必要があります。コールバック関数を使用せずに getValue を使用すると、コードの実行時点でのプロパティの値が返されます。

getValue('config', function(config) { if (config) { applyConfiguration(config); }});

以下の例は、プロパティの初期値が undefined である可能性があるため、推奨されません:const config = getValue('config');applyConfiguration(config);

4. イベント処理 - データの検証

イベントデータには型があります。データ型が正しくないイベントを発火させても、カスタムウィジェットのコードの実行がクラッシュしたり停止したりすることはありませんが、fireEventで送信されるデータが検証され、正しい型であることを確認するための独自のガードを設けることが推奨されます。

この手法により、予期しない動作を防ぎ、コードの予測可能性を高めることができます。

if (data != null && typeof data === 'string') { fireEvent(eventName, data);} else { // 必要に応じて、無効なデータの場合の処理を行う。}

5. 非同期のプロパティアクセスにはコールバック関数を使用する

setValue() を呼び出すと、プロパティの更新は非同期で行われます。これは、カスタムウィジェットが iframe からメインアプリケーションと通信しているため、更新が即座には行われないことを意味します。setValue()のリクエストは送信されますが、コードは変更が反映されるのを待たずに実行を続けます。 その直後にgetValue()を使用しようとすると、古い値が返される可能性が高いです。

**最新のデータを取得するには、常にコールバック関数とともにgetValue()を使用してください。**コールバックは、プロパティの更新が正常に完了したときにのみ実行されるため、最新の情報で処理を行っていることが保証されます。

以下の例は、このベストプラクティスを示しています:```// 推奨:プロパティの値を非同期で取得するconst newConfig = { setting: 'value' };setValue('config', newConfig);

// プロパティの更新が完了すると、コールバック関数が実行されます。getValue('config', function(updatedConfig) { console.log('プロパティが更新されました。新しい設定は次のとおりです:', updatedConfig); // 確実に新しい値を使用して処理を行います applyConfiguration(updatedConfig);});```

次の例は、避けるべき方法を示しています:```// 悪い例:期待通りに動作しない可能性がありますconst newConfig = { setting: 'value' };setValue('config', newConfig);

// これでは、新しい値ではなく、古い値がログに出力される可能性が高い。const currentConfig = getValue('config'); ```

6. API呼び出しにはサポートされているヘッダーを使用する

カスタムウィジェットから外部APIを呼び出す際は、CORS(Cross-Origin Resource Sharing)の問題を回避するために、HTTPヘッダーの扱いに注意してください。カスタムウィジェットは、特定のセキュリティ制限があるiframe環境内で実行されます。

**明示的にサポートされているヘッダーのみを使用してください。**Content-Type やその他のカスタムヘッダーなど、サポートされていないヘッダーを設定すると、CORS エラーが発生し、API 呼び出しが機能しなくなる可能性があります。

以下の例は、このベストプラクティスを示しています:// 推奨:カスタムヘッダーを使用しないシンプルなAPI呼び出しfetch("https://akhatri.bulb.cloud/api/v3/w/1/tables", { headers: { Authorization: "<APIキー>", },}) .then((response) => response.json()) .then((data) => console.log(data)) .catch((error) => console.error("エラー:", error));

以下の例は、避けるべきことを示しています:// 悪い例: Content-Typeヘッダーを設定するとCORSの問題が発生しますfetch("https://api.example.com/data", { headers: { Authorization: "<APIキー>", "Content-Type": "application/json", // これによりCORSエラーが発生します },})

Troubleshoot CORS error

If you encounter CORS errors, first remove any custom headers you've set (especially Content-Type) and test with minimal headers. The iframe security model restricts which headers can be set from custom widgets.

7. 実行環境に応じてウィジェットを初期化する

詳細については、「ランタイムのバージョン」を参照してください。

新しいランタイム

新しいランタイムでは、src属性は空のシェル HTML ファイルを返します。読み込まれると、このシェルファイルは親アプリにメッセージを送信します。親アプリは、カスタムウィジェットのコード、ユーティリティ関数(getValue() など)、および iframe に注入する初期プロパティ値を送信します。

このため、空のシェルが読み込まれた際、ウィジェットコードが注入される前に`DOMContentLoaded`および`window.onload`が発生します。これらのイベントに添付されたハンドラは登録が遅すぎます。イベントはすでに発生しているため、コールバックは決して実行されません。以下の例に示すように、これらのハンドラ内のコードは黙ってスキップされます:

document.addEventListener('DOMContentLoaded', function() { // SHELLの読み込み時、ユーザーコードの注入前に発生 // ユーザーコードはまだ注入さえされていない! const myProp = getValue('myProp'); // エラー: getValue は定義されていません});

custom widgets では、DOMContentLoadedやwindow.onloadを使用する必要はありません。Tulipは、サードパーティ製ライブラリ、ユーザーHTML、そしてJavaScriptの順でリソースを読み込みます。JavaScriptが実行される時点では、DOMはすでに利用可能です。以下の例に示すように、ロードイベントを待たずにDOM要素に直接アクセスできます:

// 直接呼び出しても安全です — これが実行される時点ですでにDOMは読み込まれています。const btn = document.getElementById('my-btn');

旧ランタイム

旧ランタイムでは、srcDoc属性によって、getValue()などのユーティリティ関数や初期プロパティ値とともに、カスタムウィジェットのコードがiframeに挿入されます。ウィジェットのコードは最初からドキュメントの一部であるため、iframeのコンテンツが読み込まれるとすぐに、getValue()やプロパティを利用できるようになります。その結果、古いランタイムではDOMContentLoadedやwindow.onload が期待通りに動作します。以下の例を参照してください:

document.addEventListener('DOMContentLoaded', function() { // ユーザーのHTMLの準備が整ったときに発火 // プロパティはすでに利用可能 const myProp = getValue('myProp'); // すぐに動作する});