Skip to content

Boas práticas do Widget Svelte ​

Tipo
Referência
Para
Desenvolvedor
Liberação
Em beta

Um Widget Svelte roda também em outro Tenant depois de instalado por template, no tema escuro, no aplicativo móvel com a cor da marca e no PDF de um alerta. Estas regras fazem o mesmo código funcionar em todos esses lugares.

Checklist ​

RegraPor quê
Coluna pelo nome, com sufixo: '[Vendas]."VALOR":SUM'ID numérico só lê no Tenant onde foi escrito. Veja Referência de coluna
Nomes de coluna em constantes no topo do scriptAdaptar a outra Aplicação vira trocar uma linha
Dado por app.query, no topo do <script>Ela já traz carregando, erro e linhas, e aplica os filtros do Dashboard
data-source em cada bloco com dado, data-field no valorLiga a tela à Origem dos dados
Todo valor por consulta.format(apelido, valor) ou app.formatValueSegue a máscara, o idioma e a moeda da coluna
Os quatro estados: erro, carregando, vazio e dadoSem eles, o Widget em branco não diz se é falha ou falta de dado
filters só com o que é do WidgetO filtro do Dashboard já está na consulta
Várias colunas numa consulta, limit no que vai para a telaCada app.query é uma consulta ao banco a cada montagem. O padrão é 500 linhas
Sintaxe do Svelte 4O compilador é Svelte 4. Veja abaixo
Raiz sem h-full junto com overflow-autoVeja Tamanho
Classes de tema da tabela, navy no dark:Veja Tema
Seleção lida de app.getFilter ao montarTodo addFilter remonta o Widget e zera as variáveis
Nada que muda algo fora do Lumo ao montarVeja Exportação e alerta
Nenhum segredo no códigoO código vai inteiro para o navegador. Para uma API sua, use JWT
Paramétrico: o que muda entre usos vem de configSenão cada uso exige editar o componente, e a edição publicada chega a todos

Os quatro estados ​

svelte
<script>
  export let app;
  const lojas = app.query('lojas', {
    title: 'Vendas por loja',
    columns: { loja: '[Vendas]."LOJA":AGP', valor: '[Vendas]."VALOR":SUM' },
  });
</script>

<div class="w-full p-4" data-source="lojas">
  {#if $lojas.error}
    <p class="text-sm text-error">{$lojas.error} <button on:click={() => lojas.refresh()}>Tentar de novo</button></p>
  {:else if !$lojas.ready}
    <p class="text-slate-500 dark:text-navy-300">Carregando…</p>
  {:else if !$lojas.rows.length}
    <p class="text-slate-500 dark:text-navy-300">Sem dados no período</p>
  {:else}
    {#each $lojas.rows as l}<p>{l.loja} <b data-field="valor">{lojas.format('valor', l.valor)}</b></p>{/each}
  {/if}
</div>

O erro vem antes do carregando: uma consulta que falha na primeira vez fica com ready: false.

Não reaplique o filtro do Dashboard ​

javascript
// errado: troca o período do Dashboard pelo de janeiro, só neste Widget
filters: [{ column: '[Vendas]."DATA":DATE', operator: 'between', value: '2026-01-01,2026-01-31' }]

Na mesma coluna, o filtro do código vence o do Dashboard. Para o total do ano ao lado do mês, ignore o filtro do Dashboard com value: false (app.query).

Escreva Svelte 4 ​

As runes do Svelte 5 dão erro ou não reagem, e onclick={fn} compila, mas o clique não faz nada.

Svelte 4 (use)Svelte 5 (não funciona)
export let app;let { app } = $props();
let total = 0;let total = $state(0);
$: dobro = total * 2;let dobro = $derived(total * 2);
on:click={filtrar}onclick={filtrar}
<slot />{@render children()}

Tamanho ​

O cartão já define largura, altura e rolagem. Na raiz do componente, h-full com overflow-auto cria uma segunda rolagem e corta o conteúdo no PDF. Use w-full e padding; h-full só para centralizar carregando e erro.

Com Crescer com o conteúdo ligado, o cartão não tem altura fixa e um gráfico com height: 100% some. Dê altura ao gráfico (chart: { height: 320 }).

Tema ​

O aplicativo móvel do Lumo repinta a página com a cor da marca, e só repinta as classes da web. Use estas, com a paleta navy no dark: (nunca gray, slate ou zinc):

PapelClaroEscuro
Fundo da páginabg-slate-50dark:bg-navy-900
Cartãobg-whitedark:bg-navy-800
Bloco internobg-slate-100dark:bg-navy-700
Bordaborder-slate-200dark:border-navy-600
Textotext-slate-800, text-slate-700dark:text-navy-100, dark:text-white
Texto secundáriotext-slate-500dark:text-navy-300

A cor do dado (série, vermelho e verde de status) é livre.

No <style>, use a variável do aplicativo com a cor da web de reserva: var(--mt-cartao, #FFFFFF). As variáveis são --mt-fundo, --mt-cartao, --mt-rebaixado, --mt-linha, --mt-texto, --mt-texto-secundario e --mt-acao.

O Highcharts não lê classe nem variável CSS. Monte as cores em JavaScript, num $:, para o gráfico repintar quando o tema muda:

javascript
$: escuro = $app.theme === 'dark';
$: marca = $app.moldura?.ativa ? $app.moldura.cores : null;
$: cores = {
  texto: marca?.texto ?? (escuro ? '#C2C9D6' : '#1E293B'),
  linha: marca?.linha ?? (escuro ? '#313E59' : '#E2E8F0'),
};

Datas no fuso local ​

new Date('2026-02-23') é meia-noite em UTC, que no Brasil ainda é dia 22. Use parseISO('2026-02-23') do date-fns, ou new Date(2026, 1, 23). Para mostrar, format da consulta resolve.

Pense na exportação e no alerta ​

O Widget roda sem ninguém olhando na exportação de PDF e imagem e no envio de alerta, uma vez por renderização, como quem disparou. Por isso:

  • Chamada a uma API sua no corpo do script ou no onMount dispara em cada abertura, cada troca de filtro e cada PDF. O que muda algo fora do Lumo vai num clique.
  • Saudação por app.user num Widget de alerta mostra a todos os destinatários o nome do dono do alerta.