Contrato do componente

Tipo

Referência

Para

Desenvolvedor

Um componente paramétrico só tem campos para preencher se o contrato (manifest) os declarar. É um JSON com a lista de campos e a aparência fixa do componente; o código lê os valores em config, indexados pela chave de cada campo.

{
  "fields": [
    { "key": "titulo", "type": "text", "label": "Título", "default": "Meta do mês" },
    { "key": "cor", "type": "color", "label": "Cor principal", "group": "Aparência" },
    { "key": "valor", "type": "column-binding", "label": "Coluna de valor", "filter": "Measure" },
    { "key": "meta", "type": "number", "label": "Meta", "min": 0, "step": 100, "expression": true },
    { "key": "modo", "type": "select", "label": "Modo", "options": [
      { "value": "compacto", "label": "Compacto" },
      { "value": "detalhado", "label": "Detalhado" }
    ] }
  ],
  "display": { "transparentBackground": false, "autoGrow": false }
}

Propriedades de todo campo

Propriedade	Obrigatória	O que é
key	Sim	A chave em config. Única no contrato
type	Sim	Um dos tipos abaixo
label	Sim	O nome que quem configura vê
default	Não	O valor quando ninguém preenche
help	Não	Texto de ajuda abaixo do campo
group	Não	Junta campos do mesmo grupo na tela

Contrato sem fields, com campo sem key, chave repetida, sem label ou com tipo desconhecido é recusado ("Manifest inválido").

Tipos de campo

type	O valor em config	Propriedades próprias	Padrão sem default
column-binding	Texto de coluna, como '[Vendas]."VALOR":SUM'. Lista, com multiple	multiple, filter (Measure, Dimension, Date ou All)	"" ou []
text	Texto		""
textarea	Texto longo		""
number	Número	min, max, step	min ou 0
range	Número, num controle deslizante	min, max, step	min ou 0
color	Cor em hex, como #4F46E5		#000000
boolean	true ou false		false
select	O value da opção escolhida	options ([{ value, label }]), forceKind (segmented ou list)	A primeira opção
date	Data		""
icon	Nome Iconify, como fa:star		""
number-format	Um formato de número do Lumo, para app.formatValue		"default"
svelte_modal	O objeto que a tela do autor devolve	editorComponent (o arquivo da tela), buttonLabel	{}

O componente nunca recebe undefined num campo do contrato: vale o que foi preenchido, senão o default, senão o padrão da tabela.

Sem forceKind, um select escolhe a aparência pelo número de opções.

Fórmula por campo

Os tipos color, number, text, textarea, range e number-format aceitam "expression": true. Quem configura ganha Usar fórmula ("Avalia uma expressão JS; em erro, usa o valor fixo.") e escreve uma expressão em JavaScript no lugar do valor fixo.

A fórmula não é avaliada sozinha. O config recebe duas chaves a mais por campo, <key>Expression (o texto da fórmula) e <key>UsesExpression, e o componente avalia:

const meta = config.metaUsesExpression
  ? (await app.evalExpression(config.metaExpression, { config })) ?? config.meta
  : config.meta;

A fórmula é o corpo de uma função assíncrona, como as regras JS: usa return, e o objeto passado como segundo argumento chega em this. app.evalExpression devolve undefined em erro, e o ?? cai no valor fixo. Veja Objeto app.

Aparência

display vale para todas as instâncias, e quem configura não muda:

Propriedade	Efeito
transparentBackground	Tira o fundo e a borda do cartão
autoGrow	O Widget cresce na altura conforme o conteúdo

Relacionado

• Componentes paramétricos
• Objeto app