#ctx.on()

Inscreva-se em eventos de contexto (como mudanças de valor de campo, mudanças de propriedade, atualização de recursos, etc.) no RunJS. Os eventos são mapeados para eventos DOM personalizados em ctx.element ou eventos do barramento interno de ctx.resource com base em seu tipo.

#Cenários de uso

#Definição de Tipo

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

#Eventos Comuns

Regra de mapeamento de eventos: Eventos com o prefixo resource: passam por ctx.resource.on, enquanto outros geralmente passam por eventos DOM em ctx.element (se existir).

#Exemplos

#Vínculo bidirecional de campo (React useEffect + Limpeza)

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

#Escuta de DOM nativo (Alternativa quando ctx.on não está disponível)

// Quando ctx.on não for fornecido, você pode usar ctx.element diretamente
const handler = (ev) => {
  if (selectEl) selectEl.value = String(ev?.detail ?? '');
};
ctx.element?.addEventListener('js-field:value-change', handler);
// Durante a limpeza: ctx.element?.removeEventListener('js-field:value-change', handler);

#Atualizando a UI após a atualização do recurso

ctx.resource?.on('refresh', () => {
  const data = ctx.resource?.getData?.();
  // Atualiza a renderização com base nos dados
});

#Coordenação com ctx.off

• Os ouvintes (listeners) registrados usando ctx.on devem ser removidos no momento apropriado via ctx.off para evitar vazamentos de memória ou disparos duplicados.
• No React, o ctx.off é geralmente chamado dentro da função de limpeza (cleanup) do useEffect.
• O ctx.off pode não existir; recomenda-se usar o encadeamento opcional (optional chaining): ctx.off?.('eventName', handler).

#Observações

1. Cancelamento em par: Cada ctx.on(eventName, handler) deve ter um ctx.off(eventName, handler) correspondente, e a referência do handler passada deve ser idêntica.
2. Ciclo de vida: Remova os ouvintes antes que o componente seja desmontado ou o contexto seja destruído para evitar vazamentos de memória.
3. Disponibilidade de eventos: Diferentes tipos de contexto suportam eventos diferentes. Consulte a documentação específica do componente para mais detalhes.

#Documentação Relacionada

• ctx.off - Remover ouvintes de eventos
• ctx.element - Contêiner de renderização e eventos DOM
• ctx.resource - Instância de recurso e seus métodos on/off
• ctx.setValue - Define o valor do campo (dispara js-field:value-change)