#イベントフロー

#紹介

フォームの変更時にカスタムアクションをトリガーしたい場合は、イベントフローを使用できます。フォーム以外にも、ページ、ブロック、ボタン、フィールドでイベントフローを使用してカスタム操作を設定できます。

#使い方

以下の簡単な例で、イベントフローの設定方法を説明します。2 つのテーブル間の連動を実現しましょう。左側のテーブルの行をクリックしたときに、右側のテーブルのデータを自動的にフィルタリングします。

設定手順は以下の通りです：

1. 左側のテーブルブロック右上にある「稲妻」アイコンをクリックして、イベントフロー設定画面を開きます。
2. 「イベントフローを追加（Add event flow）」をクリックし、「トリガーイベント」で「行クリック」を選択します。これは、テーブルの行がクリックされたときにトリガーされることを意味します。
3. 「実行タイミング」を設定します。これは、このイベントフローをシステムの組み込みフローに対してどの順序で実行するかを制御します。通常はデフォルトのままで問題ありません。組み込みロジックの実行後に通知やページ遷移を行いたい場合は、「すべてのフローの後」を選択します。詳細は後述の 実行タイミング を参照してください。
4. 「トリガー条件（Trigger condition）」は条件を設定するためのものです。条件が満たされた場合にのみイベントフローがトリガーされます。ここでは設定不要で、行をクリックすれば常にイベントフローがトリガーされます。
5. 「ステップを追加（Add step）」にマウスを合わせると、操作ステップを追加できます。「データ範囲を設定（Set data scope）」を選択して、右側のテーブルのデータ範囲を設定します。
6. 右側のテーブルの UID をコピーし、「ターゲットブロック UID（Target block UID）」入力欄に貼り付けます。すると、その下に条件設定画面が表示され、右側のテーブルのデータ範囲を設定できます。
7. 以下のように条件を設定しましょう：
8. データ範囲を設定した後、フィルタリング結果を表示するにはブロックを更新する必要があります。次に、右側のテーブルブロックの更新を設定しましょう。「ターゲットブロックを更新（Refresh target blocks）」ステップを追加し、右側のテーブルの UID を入力します。
9. 最後に右下の保存ボタンをクリックすれば、設定は完了です。

#イベント詳解

#描画前

ページ、ブロック、ボタン、またはフィールドで使用できる汎用イベントです。このイベントでは、初期化作業を行うことができます。例えば、異なる条件に基づいて異なるデータ範囲を設定する、といった使い方ができます。

#行クリック（Row click）

テーブルブロック専用のイベントです。テーブルの行がクリックされたときにトリガーされます。トリガー時にコンテキストに Clicked row record が追加され、条件やステップで変数として使用できます。

#フォーム値変更（Form values change）

フォームブロック専用のイベントです。フォームフィールドの値が変更されたときにトリガーされます。条件やステップでは、「Current form」変数を通じてフォームの値を取得できます。

#クリック（Click）

ボタン専用のイベントです。ボタンがクリックされたときにトリガーされます。

#実行タイミング

イベントフローの設定には、混同しやすい 2 つの概念があります：

• トリガーイベント： いつ実行を開始するか（例：描画前、行クリック、クリック、フォーム値変更など）。
• 実行タイミング： 同じトリガーイベントが発生した際、このカスタムイベントフローを組み込みフローのどの位置に挿入して実行するか。

#「組み込みフロー / 組み込みステップ」とは？

多くのページ、ブロック、または操作には、システム標準の処理フロー（例：送信、ポップアップを開く、データリクエストなど）が備わっています。同じイベント（例：「クリック」）に対してカスタムイベントフローを追加する場合、「実行タイミング」によって以下を決定します：

• カスタムイベントフローを先に実行するか、組み込みロジックを先に実行するか。
• または、カスタムイベントフローを組み込みフローの特定のステップの前後に挿入するか。

#UI の実行タイミングの選択肢

• すべてのフローの前（デフォルト）： 最初に実行されます。「インターセプト / 準備」（例：バリデーション、二次確認、変数の初期化など）に適しています。
• すべてのフローの後： 組み込みロジックの完了後に実行されます。「仕上げ / フィードバック」（例：通知メッセージ、他ブロックの更新、ページ遷移など）に適しています。
• 指定フローの前 / 指定フローの後： より詳細な挿入ポイントです。選択後、具体的な「組み込みフロー」を選択する必要があります。
• 指定フローステップの前 / 指定フローステップの後： 最も詳細な挿入ポイントです。選択後、「組み込みフロー」と「組み込みフローステップ」の両方を選択する必要があります。

ヒント：どの組み込みフロー / ステップを選べばよいか不明な場合は、まず最初の 2 つ（「前 / 後」）を優先的に使用してください。

#ステップ詳解

#カスタム変数（Custom variable）

カスタム変数を定義し、コンテキスト内で使用します。

#スコープ

カスタム変数にはスコープがあります。例えば、ブロックのイベントフローで定義された変数は、そのブロック内でのみ使用できます。現在のページ内のすべてのブロックで利用したい場合は、ページのイベントフローで設定する必要があります。

#フォーム変数（Form variable）

特定のフォームブロックの値を変数として使用します。具体的な設定は以下の通りです：

• Variable title：変数タイトル
• Variable identifier：変数識別子
• Form UID：フォーム UID

#その他の変数

今後、他の変数タイプも順次サポートされる予定です。ご期待ください。

#データ範囲を設定（Set data scope）

ターゲットブロックのデータ範囲を設定します。具体的な設定は以下の通りです：

• Target block UID：ターゲットブロック UID
• Condition：フィルタリング条件

#ターゲットブロックを更新（Refresh target blocks）

ターゲットブロックを更新します。複数のブロックを設定できます。具体的な設定は以下の通りです：

• Target block UID：ターゲットブロック UID

#URL へ移動（Navigate to URL）

指定した URL へ移動します。具体的な設定は以下の通りです：

• URL：ターゲット URL、変数使用可能
• Search parameters：URL 内のクエリパラメータ
• Open in new window：チェックした場合、移動時に新しいブラウザページが開きます

#メッセージを表示（Show message）

操作フィードバック情報をグローバルに表示します。

#いつ使用するか

• 成功、警告、エラーなどのフィードバック情報を提供できます。
• 画面上部中央に表示され自動的に消えるため、ユーザーの操作を妨げない軽量な通知方法です。

#具体的な設定

• Message type：メッセージタイプ
• Message content：メッセージ内容
• Duration：表示時間（秒単位）

#通知を表示（Show notification）

通知アラート情報をグローバルに表示します。

#いつ使用するか

システムの四隅に通知アラートを表示します。以下の状況でよく使用されます：

• 比較的複雑な通知内容の場合。
• インタラクションを伴い、ユーザーに次のアクションを促す場合。
• システムからのプッシュ通知。

#具体的な設定

• Notification type：通知タイプ
• Notification title：通知タイトル
• Notification description：通知説明
• Placement：表示位置（選択肢：左上、右上、左下、右下）

#JavaScript を実行（Execute JavaScript）

JavaScript コードを実行します。

#カスタムリクエスト（Custom request）

#いつ使用するか

フロー内で外部インターフェースやサードパーティサービスを呼び出す必要がある場合、Custom request を使用してカスタム HTTP リクエストをトリガーできます。一般的な使用シーンには以下が含まれます：

• 外部システム API の呼び出し（CRM、AI サービスなど）
• リモートデータの取得と後続フローステップでの処理
• サードパーティシステムへのデータ送信（Webhook、メッセージ通知など）
• 内部または外部サービスの自動化フローのトリガー

リクエスト実行完了後、その返却データを後続のステップで引き続き使用できます（データ処理、条件判断、保存など）。

#具体的な設定

• HTTP method：HTTP リクエストメソッド（GET、POST、PUT、DELETE など）。
• URL：リクエスト先のアドレス。完全なインターフェース URL を入力するか、変数を使用して動的に組み立てることができます。
• Headers：リクエストヘッダー情報。認証情報やインターフェース設定の伝達に使用します（Authorization、Content-Type など）。
• Parameters：URL クエリパラメータ（Query Parameters）。通常 GET リクエストで使用します。
• Body：リクエストボディの内容。通常 POST、PUT などのリクエストで使用し、JSON やフォームデータなどを記述できます。
• Timeout config：リクエストタイムアウト時間の設定。リクエストの最大待機時間を制限し、フローが長時間ブロックされるのを防ぎます。
• Response type：リクエストレスポンスのデータ型。
  • JSON：インターフェースが JSON データを返します。返却結果はフローのコンテキストに注入され、後続ステップで ctx.steps を通じて取得できます。
  • Stream：インターフェースがデータストリーム（Stream）を返します。リクエスト成功後、自動的にファイルダウンロードがトリガーされます。
• Access control：アクセス制御。どのロールがこのリクエストステップをトリガーできるかを制限し、インターフェース呼び出しのセキュリティを確保します。

#使用例

#フォーム：サードパーティ API を呼び出してフィールドに値を戻す

シナリオ：フォーム内でイベントフローをトリガーし、サードパーティ API をリクエストして、取得したデータをフォームフィールドに自動入力します。

設定手順：

1. フォームブロックでイベントフロー設定を開き、新しいイベントフローを追加します。
2. トリガーイベントで「描画前」を選択します。
3. 実行タイミングで「すべてのフローの後」を選択します。
4. 「JavaScript を実行（Execute JavaScript）」ステップを追加し、以下のコードを貼り付けて必要に応じて修正します：

const res = await ctx.api.request({
  method: 'get',
  url: 'https://jsonplaceholder.typicode.com/users/2',
  skipNotify: true,
  // 注意: ctx.api はデフォルトで現在の NocoBase 認証/カスタムヘッダーを含みます
  // ここではサードパーティにトークンを送信しないよう、空の Authorization で上書きします
  headers: {
    Authorization: 'Bearer ',
  },
});

const username = res?.data?.username;

// 実際のフィールド名に置き換えてください
ctx.form.setFieldsValue({ username });