Docs

Playground

GitHub

DocsEcossistema

Gráficos

Editar esta página

5 min de leitura

Um gráfico no eQuantic.UI é UM componente escrito em C#. O mesmo BarChart renderiza na web (no servidor e no browser) e no Photon (desktop e mobile), a partir do mesmo código, nas cores que o tema reserva para dados. A biblioteca é a eQuantic.UI.Charts, e o SDK a coloca em escopo em todo projeto como faz com a eQuantic.UI.Components: não há nada para instalar nem using para escrever.

Desde 0.2.0-preview.50

O gráfico de barras

BarChart(

title: "Receita por trimestre",

subtitle: "Três regiões, lado a lado",

series:

[

ChartSeries("Europa", [120_000, 138_500, 149_200, 171_000]),

ChartSeries("Américas", [98_400, 104_900, 99_700, 132_300]),

ChartSeries("Ásia", [61_200, 72_800, 88_100, 95_500]),

categories: CategoryAxis(["T1", "T2", "T3", "T4"]),

values: ValueAxis(format: "C0", title: "Receita"))

As factories são a superfície declarativa: cada uma tem o nome do seu tipo e espelha o construtor parâmetro a parâmetro (BarChart, ChartSeries, CategoryAxis, ValueAxis), e um dashboard se lê sem um único new.

Três arranjos, um componente:

você quer

você escreve

grupos lado a lado (o padrão)

layout: BarLayout.Grouped

uma série sobre a outra

layout: BarLayout.Stacked

barras da esquerda para a direita, para nomes de categoria longos

orientation: ChartOrientation.Horizontal

plotHeight define a altura só da área do gráfico; a largura é a que o gráfico receber, e as barras a preenchem.

O que todo gráfico traz sem que se peça:

•

Uma legenda quando há mais de uma série. Pressionar uma entrada isola aquela série; pressionar de novo traz as outras de volta. Uma série só não mostra legenda, porque o título já a nomeia.

•

Um tooltip que segue o ponteiro, nomeando a categoria, a série e o valor.

•

Uma vista em tabela. O Ver como tabela do rodapé troca o gráfico por um DataTable com os mesmos números, e Ver como gráfico troca de volta: os mesmos dados para um leitor de tela, um teclado, ou quem prefere os números.

•

Rótulos de eixo a partir dos seus dados: as categorias sob (ou ao lado d)o gráfico, os valores em ticks limpos. ValueAxis(format: "C0") formata cada rótulo de valor e cada célula da tabela com uma format string do .NET na cultura atual: o mesmo "C0" imprime €120,000 num pedido e R$ 120.000 no seguinte. min, max e ticks fixam o eixo quando você prefere que ele não siga os dados.

•

Um nome acessível: o canvas carrega o título do gráfico, e a área é anunciada como o que é.

A cor vem do tema

Um gráfico nunca declara uma cor. IAppTheme.Data é uma DataPalette com oito slots de série, rampas sequencial e divergente e quatro degraus de status, auditada para contraste e para deficiências de visão de cor: a paleta padrão sai auditada, e a sua pode ser verificada da mesma forma com PaletteAudit. As regras valem por construção, não por recomendação:

•

A primeira série veste o slot 0, a segunda o slot 1, e assim por diante; ChartSeries("Previsão", values, slot: 3) fixa uma série a um slot para que mantenha a cor entre gráficos.

•

Uma nona série lança exceção no build. Oito cores distinguíveis é onde a auditoria para; um gráfico com mais séries é uma tabela.

•

As cores de status são reservadas para estado. Uma série que SIGNIFICA bom ou mau veste status; a "série 4" nunca.

•

Texto nunca veste cor de dado: rótulos, entradas da legenda e tooltips leem-se nos tokens de texto do tema, e a amostra ao lado carrega a cor.

Rebrandear as cores de dados é fornecer o seu próprio Data no seu tema, exatamente como fornece Primary.

Como renderiza

O chrome do gráfico (título, subtítulo, legenda, rótulos de eixo, a tabela, o rodapé) são nós comuns (Text, Row, Column, DataTable), e por isso dispõe-se, quebra linha, tematiza e fala com tecnologia assistiva como o resto da sua tela. As marcas são um Canvas pintado com as formas do próprio engine: retângulos arredondados no SVG da web, os mesmos retângulos na GPU do Photon.

Na web o chrome é renderizado no servidor como o resto da sua página, e as marcas são desenhadas assim que o gráfico é medido: um canvas que preenche a sua caixa não tem tamanho antes de o CSS o dispor, então o servidor emite a moldura e o browser pinta dentro dela.

A geometria é resolvida uma vez, em BarChartLayout: C# no servidor e no Photon, o twin transpilado no browser. Uma fixture fixada, resolvida pelas duas compilações, é comparada linha a linha nas suites de teste, e uma barra que as duas colocassem a um décimo de dp de distância falha o build. Os valores dos ticks encaixam em 1, 2, 5 e 10 por multiplicação, e não por logaritmo, pela mesma razão: os dois runtimes têm de concordar em cada tick.

O que vem a seguir

O gráfico de barras é a primeira fatia de um plano que alcança os tipos de gráfico que os wrappers abaixo cobriam: linha, área e sparklines com eixo de tempo; pizza, donut, gauge, heatmap e dispersão; radar e candlestick, anotações, animação e exportação via capability. O plano vive no repositório como docs/CHARTS-PLAN.md, com o que cada fatia entrega e o que fica cercado de propósito (eixos duplos, 3D e funis entre eles).

Wrappers, para a transição

Dois wrappers só-web em torno de bibliotecas JavaScript antecedem a biblioteca nativa e continuam disponíveis até que ela cubra os seus tipos de gráfico, momento em que são removidos:

•

eQuantic.UI.Charts.ChartJs, Chart.js em canvas HTML5: bar, line, pie, doughnut, radar.

•

eQuantic.UI.Charts.ApexCharts, ApexCharts em SVG: area, bar, line, heatmap, candlestick.

São pacotes opt-in, só-web (não renderizam nada no Photon), e recebem a configuração da própria biblioteca como classes C# que espelham a sua API JavaScript:

dotnet add package eQuantic.UI.Charts.ApexCharts

builder.Services.AddUI(options =>

{

options.UseApexCharts() // ou UseChartJs(); cada um serve os scripts da sua biblioteca

.ScanAssembly(typeof(Program).Assembly);

});

new ApexChart<MyData>

{

Options = new ApexOptions { Chart = new ChartConfig { Type = "bar" } },

Series = [new ApexSeries<MyData> { Name = "Vendas", Data = dataList }],

}

Os seus scripts são declarados pelo sistema de assets e injetados onde uma página os usa; nada é adicionado à mão. Uma página que só precisa de um gráfico de barras deve usar o BarChart acima: renderiza em todos os alvos, e é o que fica.

NESTA PÁGINA

Wrappers, para a transição