#ctx.element

Uma instância de ElementProxy que aponta para o contêiner DOM do sandbox, servindo como o alvo de renderização padrão para ctx.render(). Está disponível em cenários onde existe um contêiner de renderização, como JSBlock, JSField, JSItem e JSColumn.

#Cenários de Uso

Observação: ctx.element só está disponível em contextos RunJS que possuem um contêiner de renderização. Em contextos sem UI (como lógica puramente de backend), ele pode ser undefined. Recomenda-se realizar uma verificação de valor nulo antes do uso.

#Definição de Tipo

element: ElementProxy | undefined;

// ElementProxy é um proxy para o HTMLElement original, expondo uma API segura
class ElementProxy {
  __el: HTMLElement;  // O elemento DOM nativo interno (acessível apenas em cenários específicos)
  innerHTML: string;  // Sanitizado via DOMPurify durante a leitura/escrita
  outerHTML: string; // Idem ao anterior
  appendChild(child: HTMLElement | string): void;
  // Outros métodos de HTMLElement são repassados (o uso direto não é recomendado)
}

#Requisitos de Segurança

Recomendado: Toda renderização deve ser realizada via ctx.render(). Evite usar as APIs DOM de ctx.element diretamente (ex: innerHTML, appendChild, querySelector, etc.).

#Por que ctx.render() é recomendado

#❌ Não recomendado: Manipulação direta de ctx.element

// ❌ Não recomendado: Usar APIs de ctx.element diretamente
ctx.element.innerHTML = '<div>Conteúdo</div>';
ctx.element.appendChild(node);
ctx.element.querySelector('.class');

ctx.element.innerHTML está depreciado. Por favor, use ctx.render() em seu lugar.

#✅ Recomendado: Usar ctx.render()

// ✅ Renderizando um componente React
const { Button, Card } = ctx.libs.antd;
ctx.render(
  <Card title={ctx.t('Bem-vindo')}>
    <Button type="primary">Clique aqui</Button>
  </Card>
);

// ✅ Renderizando uma string HTML
ctx.render('<div style="padding:16px;">' + ctx.t('Conteúdo') + '</div>');

// ✅ Renderizando um nó DOM
const div = document.createElement('div');
div.textContent = ctx.t('Olá');
ctx.render(div);

#Caso Especial: Como âncora de Popover

Quando você precisar abrir um Popover usando o elemento atual como âncora, você pode acessar ctx.element?.__el para obter o DOM nativo como target:

// ctx.viewer.popover requer um DOM nativo como target
await ctx.viewer.popover({
  target: ctx.element?.__el,
  content: <div>Conteúdo do Popover</div>,
});

Use __el apenas em cenários como "usar o contêiner atual como âncora"; não manipule o DOM diretamente em outros casos.

#Relação com ctx.render

• Se ctx.render(vnode) for chamado sem um argumento container, ele renderiza no contêiner ctx.element por padrão.
• Se tanto ctx.element estiver ausente quanto nenhum container for fornecido, um erro será lançado.
• Você pode especificar explicitamente um contêiner: ctx.render(vnode, customContainer).

#Observações

• ctx.element destina-se ao uso interno pelo ctx.render(). Acessar ou modificar suas propriedades/métodos diretamente não é recomendado.
• Em contextos sem contêiner de renderização, ctx.element será undefined. Certifique-se de que o contêiner está disponível ou passe um container manualmente antes de chamar ctx.render().
• Embora innerHTML/outerHTML no ElementProxy sejam sanitizados via DOMPurify, ainda é recomendado usar ctx.render() para um gerenciamento de renderização unificado.

#Relacionado

• ctx.render: Renderizar conteúdo em um contêiner
• ctx.view: Controlador de visualização atual
• ctx.modal: API de atalho para modais