Imagens e ficheiros

Cada dashboard tem uma área de anexos — o ícone do clipe na barra superior, ou /dashboard/<id>/assets. É onde se guardam logotipos, ícones, imagens de fundo, ficheiros para descarregar e ficheiros de dados que o código dos gráficos consome.

Carregar

Arraste os ficheiros para a área ou escolha-os. Cada anexo fica registado com o nome, o tipo e o tamanho. O limite é de 10 MB por ficheiro.

Aceitam-se imagens (PNG, JPG, SVG, WebP…), PDF e ficheiros de dados — JSON, GeoJSON, CSV, TSV. Os últimos existem porque um gráfico consome ficheiros: o GeoJSON de um mapa, uma tabela de referência em CSV. Ver No código do gráfico.

Os anexos pertencem ao dashboard: acompanham-no quando se duplica ou exporta, e são apagados com ele. Não são partilhados entre dashboards — se precisar do mesmo logotipo em três dashboards, carregue-o nos três.

Escolher um anexo no editor

Não é preciso vir a esta página para usar um anexo. Em qualquer campo do editor que aceite um ficheiro há um selector de media: abre a biblioteca do dashboard com miniaturas e pesquisa, e tem o carregamento lá dentro — um ficheiro novo entra sem sair do editor.

O selector está no widget Imagem, nas colunas Imagem e Ficheiro da tabela, na imagem dos cartões e no selector de ícone dos botões e KPIs.

A referência do anexo

Cada anexo tem uma referência no formato asset:<identificador>. O selector escreve-a sozinho; a página de anexos permite copiá-la, o que só é preciso para a escrever no código de um gráfico ou de um evento.

Usar num widget de imagem

O widget Imagem tem três fontes possíveis:

Fonte	O que se indica	Quando usar
URL	Um endereço na internet	Imagem alojada noutro sítio
Anexo	Escolhido no selector de media	Logotipos e imagens do próprio dashboard
Campo	Um campo do conjunto de dados	Uma imagem diferente por linha

Com a fonte campo, é preciso dizer o que o campo contém:

• url — um endereço;
• path — uma referência a anexo;
• base64 — a própria imagem codificada nos dados.

O ajuste decide como a imagem preenche o espaço: cover corta o que sobra para preencher, contain mostra tudo deixando margens, fill deforma para encher.

Usar numa coluna de tabela

Uma coluna de tabela pode ser do tipo imagem ou ficheiro, com as mesmas três fontes. É como se põe uma miniatura de produto ao lado do nome, ou um link para a factura de cada linha.

Por omissão, a coluna lê o valor do próprio campo. Ver Tabelas.

Usar como ícone

O selector de ícone — dos botões e dos indicadores de KPI — oferece o catálogo de ícones da aplicação e, no rodapé, a biblioteca de anexos. É como se põe o símbolo da marca num botão em vez de um ícone genérico. Um SVG é o formato indicado.

No código do gráfico

Nas opções avançadas de um gráfico, ctx.asset() devolve um anexo já carregado:

const geo = ctx.asset("asset:9f2c…");

Campo	O que traz
url	Endereço utilizável em qualquer sítio — fetch(), image:// do ECharts, <img>, descarregar
json	O conteúdo já interpretado, para GeoJSON ou configurações (null se não for JSON válido)
text	O conteúdo como texto, para CSV
mime, fileName	O tipo e o nome do ficheiro

Serve para o que a interface não exprime: o GeoJSON de um mapa, uma imagem de marcador, uma tabela de referência. Sem depender de um endereço externo, que num dashboard público pode simplesmente não carregar.

O botão Inserir anexo, por cima do editor de código, abre a biblioteca e escreve a referência na posição do cursor — não é preciso decorar identificadores.

Porque é que não se espera pelo ficheiro

As referências que o código menciona são procuradas no texto e carregadas antes de ele correr. Por isso ctx.asset() devolve o anexo directamente, sem await.

Nos handlers de eventos, que já são assíncronos, o equivalente é keplin.assets.get() — ver SDK de eventos.

Quem vê o quê

Os anexos de um dashboard publicado são servidos a quem abre o link, sem sessão — mas apenas os daquele dashboard. Um anexo de outro dashboard não é alcançável a partir de um link público.

Com sessão, vale a mesma regra do dashboard: quem não tem acesso à categoria não alcança os anexos dos dashboards dessa categoria. Carregar e apagar exige permissão de edição.

Boas práticas

Dimensione as imagens antes de carregar. Uma fotografia de 4 MB usada como logotipo de 120 px continua a ser transferida inteira por quem abre o dashboard.

Prefira anexos a endereços externos. Uma imagem alojada noutro sítio desaparece quando esse sítio muda, e num dashboard público pode simplesmente não carregar.

Formatos. PNG para logotipos e imagens com transparência, JPG para fotografias, SVG para ícones que precisem de escalar sem perder nitidez.