#ctx.on()

RunJS において、コンテキストイベント（フィールド値の変更、プロパティの変更、リソースの更新など）を購読します。イベントはそのタイプに応じて、ctx.element 上のカスタム DOM イベント、または ctx.resource の内部イベントバスにマッピングされます。

#適用シーン

#型定義

on(eventName: string, handler: (event?: any) => void): void;

#よく使われるイベント

イベントのマッピングルール：resource: プレフィックスが付いているものは ctx.resource.on を経由し、それ以外は通常 ctx.element 上の DOM イベント（存在する場合）を経由します。

#例

#フィールドの双方向バインディング（React useEffect + クリーンアップ）

React.useEffect(() => {
  const handler = (ev) => setValue(ev?.detail ?? '');
  ctx.on?.('js-field:value-change', handler);
  return () => {
    ctx.off?.('js-field:value-change', handler);
  };
}, []);

#ネイティブ DOM の監視（ctx.on が利用できない場合の代替案）

// ctx.on が提供されていない場合は、ctx.element を直接使用できます
const handler = (ev) => {
  if (selectEl) selectEl.value = String(ev?.detail ?? '');
};
ctx.element?.addEventListener('js-field:value-change', handler);
// クリーンアップ時：ctx.element?.removeEventListener('js-field:value-change', handler);

#リソース更新後の UI 更新

ctx.resource?.on('refresh', () => {
  const data = ctx.resource?.getData?.();
  // データの更新に基づいてレンダリングを更新
});

#ctx.off との組み合わせ

• ctx.on で登録したリスナーは、メモリリークや重複実行を避けるため、適切なタイミングで ctx.off を使用して削除する必要があります。
• React では、通常 useEffect のクリーンアップ関数内で ctx.off を呼び出します。
• ctx.off が存在しない場合があるため、使用時はオプショナルチェイニング（ctx.off?.('eventName', handler)）の使用を推奨します。

#注意事項

1. ペアでの解除: ctx.on(eventName, handler) を呼び出すたびに、対応する ctx.off(eventName, handler) が必要です。また、渡される handler の参照は同一である必要があります。
2. ライフサイクル: コンポーネントのアンマウントやコンテキストの破棄の前にリスナーを削除してください。そうしないとメモリリークの原因になります。
3. イベントの可用性: コンテキストのタイプによってサポートされるイベントが異なります。詳細は各コンポーネントのドキュメントを参照してください。

#関連ドキュメント

• ctx.off - イベントリスナーの削除
• ctx.element - レンダリングコンテナと DOM イベント
• ctx.resource - リソースインスタンスとその on/off
• ctx.setValue - フィールド値の設定（js-field:value-change をトリガーします）