#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의 클린업(cleanup) 함수에서 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를 트리거함)