Widget Svelte

Tipo

Conceito

Para

Desenvolvedor

Na tela

DataViz › Aplicação › Editar › Dashboards › Editando Widget › Svelte

O Widget Svelte é um Widget que você escreve em código: um componente Svelte 4 que recebe o objeto app e, com ele, consulta os dados da Aplicação, põe filtros no Dashboard e formata valores. O que o componente desenha fica por sua conta, de um gráfico com uma biblioteca de mercado a uma tela inteira com abas, tabelas e botões.

Use quando nenhum Widget pronto faz a visualização ou a interação de que você precisa. Ele custa mais para manter que um Widget pronto: quem mexe nele precisa ler código, e uma mudança de tabela que o configurador de um Widget pronto acompanharia sozinha pode quebrar o código.

Qual escolher

Você precisa	Use
Uma visualização que um Widget pronto já faz, mesmo com ajuste de cor e formato	O Widget pronto. Veja Escolher um widget
Uma visualização ou interação que nenhum Widget pronto faz, num Dashboard	Widget Svelte
O mesmo código em vários Dashboards, com quem monta só preenchendo campos	Componente paramétrico, feito a partir de um Widget Svelte

Quem escreve um componente paramétrico começa por um Widget Svelte que funciona. Tudo o que esta seção diz sobre o código vale para os dois.

Como funciona

O código é guardado no próprio Widget, como uma lista de arquivos .svelte. O primeiro, Main.svelte, é o componente que o Dashboard monta; os outros entram como componentes importados por ele. Quando o Dashboard abre, o navegador manda os arquivos para o serviço de compilação da Horus, que devolve um JavaScript pronto, e monta o componente dentro da célula do Widget. O resultado da compilação fica em cache pelo texto do código: mudar uma letra gera uma compilação nova, e o mesmo código em dez Widgets compila uma vez.

O compilador é Svelte 4, e a sintaxe de Svelte 5 não funciona; a tabela de equivalências está em Boas práticas. O Tailwind 3 funciona direto no markup, inclusive as classes dark:. Os pacotes que dá para importar estão em Bibliotecas.

O componente recebe uma propriedade só, app (export let app;). Os filtros do Dashboard e os filtros pré-aplicados do Widget já vêm embutidos em app.fetchMatrix e app.fetchData, e você não os reaplica. A lista completa do que app oferece está em Objeto app.

Quando um filtro muda ou o Dashboard recarrega, o Widget é montado de novo, com um app novo: o estado que o componente guardava em variáveis se perde. Por isso a consulta vai no onMount (ou no corpo do script), e o que precisa sobreviver a um filtro vai para o próprio filtro, via app.addFilter.

Erro de compilação aparece no lugar do Widget, com o título Erro de compilação e as primeiras linhas da mensagem. No editor do Dashboard, o mesmo quadro traz Editar Código e Corrigir com IA. Um erro que acontece depois da montagem, como uma consulta que falha dentro do onMount, não chega a esse quadro: o componente precisa mostrar o próprio estado de erro, como em Seu primeiro Widget Svelte.

O configurador

Aba	Opção	O que faz
Geral	Código › Editar Código	Abre o editor, com os arquivos em abas, Testar (compila sem salvar) e Gerar com IA
Geral	Filtros Pré Aplicados	Filtros que valem só para este Widget. Entram em toda consulta do código e ganham de um filtro que o próprio código passe na mesma coluna
Visual	Gráfico com fundo transparente	Tira o fundo e a borda do cartão
Visual	Cortar conteúdo que passa da borda	Esconde o que passa do tamanho do Widget, em vez de rolar
Visual	Crescer com o conteúdo	O Widget cresce na altura conforme o conteúdo, só na visualização e na exportação. Exige largura total. Na tela, só cresce se todos os Widgets do Dashboard forem Svelte, de largura total e com a opção ligada; senão, cresce só no PDF e na imagem
Comportamento	Colocar link no Indicador e Campos para Relatório	Põem no menu do Widget o atalho para um relatório do Explorer, com os campos escolhidos
Comportamento	Filtros do Relatório	Filtros aplicados ao abrir esse relatório. Os Filtros Pré Aplicados não vão junto: repita aqui os que o relatório também deve respeitar

Sem a função de usar o gerador de relatórios, o atalho para o Explorer não aparece.

O que o código não pode fazer

O código roda no navegador de quem abre o Dashboard, com a sessão dessa pessoa. Ele lê só o que ela pode ler: a consulta passa pelas mesmas regras de acesso de qualquer Widget, e o código não tem caminho para dado que a pessoa não veria.

Pelo mesmo motivo, o código é público para quem abre o Dashboard: qualquer pessoa vê o fonte nas ferramentas do navegador. Nunca ponha chave de API, senha ou token fixo nele. Para o Widget falar com um sistema seu, use app.generateJWTToken(), que devolve um token assinado no servidor com a chave do Tenant; veja o exemplo em Exemplos.

Quem o código enxerga como usuário muda conforme o contexto (link público, exportação, alerta); veja Usuário.

A seção

Página	Para
Seu primeiro Widget Svelte	Sair do zero com um Widget que consulta, formata, filtra e trata erro
Objeto app	Consultar cada função e parâmetro de app
Bibliotecas	Saber o que dá para importar
Boas práticas	Escrever um Widget que não quebra em outro Tenant, no escuro ou no PDF
Exemplos	Copiar um padrão pronto: gráfico, drilldown, comparação de período, Excel, API
Gravar em Cadastro	Ler e gravar registros de um Cadastro a partir do Widget, com permissão e erros tratados
Componentes paramétricos	Transformar o Widget num tipo reutilizável
Contrato do componente	Declarar os campos que quem usa o componente preenche

Pelo Lumo CLI

O Widget Svelte também pode ser escrito e versionado em YAML: lumo scaffold widget svelte gera um modelo com a referência do app comentada. Veja a referência de app.