HIER STARTEN
Erste Schritte
ARCHITEKTUR
Architekturüberblick
Write-once-Komponenten
Deklarative Oberfläche
Paketarchitektur
Komponenten
Styling
Lokalisierung
Analytics und GTM
WRITE-ONCE
Speicher
Formulare
Markdown
Mermaid
E-Mail-Rendering
KOMPILIERUNG
Externe Typauflösung
RUNTIME
Runtime (TypeScript)
Performance
SERVER
Assets
BunPackage
Sicherheit
ÖKOSYSTEM
Image
Diagramme
Lottie
ENTWICKLUNG
Roadmap
DocsÖkosystem
DiagrammeEdit this page
5 min readEin Diagramm in eQuantic.UI ist EINE in C# geschriebene Komponente. Dasselbe BarChart rendert im Web (serverseitig und im Browser) und auf Photon (Desktop und Mobil), aus demselben Code, in den Farben, die das Theme für Daten reserviert. Die Bibliothek ist eQuantic.UI.Charts, und das SDK bringt sie in jedem Projekt so in Reichweite, wie es eQuantic.UI.Components tut: Es gibt nichts zu installieren und kein using zu schreiben.
Seit 0.2.0-preview.50
Das Balkendiagramm
1
2
3
4
5
6
7
8
9
10
11
BarChart(
title: "Revenue by quarter",
subtitle: "Three regions, side by side",
series:
[
ChartSeries("Europe", [120_000, 138_500, 149_200, 171_000]),
ChartSeries("Americas", [98_400, 104_900, 99_700, 132_300]),
ChartSeries("Asia", [61_200, 72_800, 88_100, 95_500]),
],
categories: CategoryAxis(["Q1", "Q2", "Q3", "Q4"]),
values: ValueAxis(format: "C0", title: "Revenue"))
Die Factories sind die deklarative Oberfläche: Jede trägt den Namen ihres Typs und spiegelt ihren Konstruktor Parameter für Parameter (BarChart, ChartSeries, CategoryAxis, ValueAxis), sodass ein Dashboard sich ohne ein einziges new liest.
Drei Anordnungen, eine Komponente:
Sie wollen
Sie schreiben
Gruppen nebeneinander (die Voreinstellung)
layout: BarLayout.Grouped
eine Serie über einer anderen
layout: BarLayout.Stacked
Balken, die von links nach rechts laufen, für lange Kategorienamen
orientation: ChartOrientation.Horizontal
plotHeight setzt die Höhe allein der Zeichenfläche; die Breite ist die, die das Diagramm bekommt, und die Balken füllen sie.
Was jedes Diagramm ungefragt mitbringt:
•
Eine Legende, wenn es mehr als eine Serie gibt. Einen Eintrag zu drücken isoliert diese Serie; ihn erneut zu drücken bringt die anderen zurück. Eine einzelne Serie zeigt keine Legende, weil der Titel sie schon benennt.
•
Einen Tooltip, der dem Zeiger folgt und Kategorie, Serie und Wert benennt.
•
Eine Tabellenansicht. Das Als Tabelle zeigen in der Fußzeile tauscht die Zeichenfläche gegen eine DataTable derselben Zahlen, und Als Diagramm zeigen tauscht zurück: dieselben Daten für einen Screenreader, eine Tastatur oder jemanden, der die Zahlen will.
•
Achsenlabels aus Ihren Daten: die Kategorien unter (oder neben) der Zeichenfläche, die Werte auf saubere Schritte. ValueAxis(format: "C0") formatiert jedes Wertlabel und jede Tabellenzelle mit einem .NET-Formatstring in der aktuellen Kultur: Dasselbe "C0" druckt bei einer Anfrage €120,000 und bei der nächsten R$ 120.000. min, max und ticks fixieren die Achse, wenn Sie lieber hätten, dass sie den Daten nicht folgt.
•
Einen zugänglichen Namen: Das Canvas trägt den Titel des Diagramms, die Zeichenfläche wird also als das angekündigt, was sie ist.
Die Farbe kommt aus dem Theme
Ein Diagramm nennt nie eine Farbe. IAppTheme.Data ist eine DataPalette mit acht Serienplätzen, sequenzieller und divergierender Rampe und vier Statusstufen, geprüft auf Kontrast und auf Farbsehschwächen: Die Standardpalette wird geprüft ausgeliefert, und Ihre lässt sich auf dieselbe Weise mit PaletteAudit prüfen. Die Regeln halten von Bauart und nicht durch Ratschlag:
•
Die erste Serie trägt Platz 0, die zweite Platz 1 und so weiter; ChartSeries("Forecast", values, slot: 3) nagelt eine Serie auf einen Platz, damit sie ihre Farbe über Diagramme hinweg behält.
•
Eine neunte Serie wirft beim Build. Acht unterscheidbare Farben sind, wo das Audit aufhört; ein Diagramm mit mehr Serien ist eine Tabelle.
•
Statusfarben sind dem Zustand reserviert. Eine Serie, die gut oder schlecht BEDEUTET, trägt Status; "Serie 4" nie.
•
Text trägt nie eine Datenfarbe: Labels, Legendeneinträge und Tooltips lesen sich in den Text-Tokens des Themes, und die Farbfläche daneben trägt die Farbe.
Die Datenfarben umzubranden heißt, Ihr eigenes Data auf Ihrem Theme bereitzustellen, genau so, wie Sie Primary bereitstellen.
Wie es rendert
Das Chrome des Diagramms (Titel, Untertitel, Legende, Achsenlabels, die Tabelle, die Fußzeile) besteht aus gewöhnlichen Knoten (Text, Row, Column, DataTable), es wird also gelayoutet, umgebrochen, gethemt und spricht mit assistiver Technik wie der Rest Ihres Bildschirms. Die Marken sind ein Canvas, mit den eigenen Formen der Engine gemalt: gerundete Rechtecke auf dem SVG des Webs, dieselben Rechtecke auf Photons GPU.
Im Web wird das Chrome serverseitig gerendert wie der Rest Ihrer Seite, und die Marken werden in dem Moment gezeichnet, in dem die Zeichenfläche gemessen wurde: Ein Canvas, das seine Box füllt, hat keine Größe, bis CSS es gelayoutet hat, der Server gibt also den Rahmen aus, und der Browser malt hinein.
Die Geometrie wird einmal gelöst, in BarChartLayout: C# auf dem Server und auf Photon, der transpilierte Zwilling im Browser. Eine gepinnte Fixture, von beiden Kompilierungen gelöst, wird in den Testsuiten Zeile für Zeile verglichen, also lässt ein Balken, den die beiden um ein Zehntel dp auseinander platzieren würden, den Build scheitern. Die Schrittwerte rasten aus demselben Grund durch Multiplikation statt durch Logarithmen auf 1, 2, 5 und 10 ein: Die beiden Runtimes müssen sich über jeden Schritt einigen.
Was kommt
Das Balkendiagramm ist die erste Scheibe eines Plans, der die Diagrammtypen erreicht, die die Wrapper unten abdeckten: Linie, Fläche und Sparklines mit einer Zeitachse; Torte, Ring, Tacho, Heatmap und Streudiagramm; Radar und Kerzen, Annotationen, Animation und Export über eine Fähigkeit. Der Plan lebt im Repository als docs/CHARTS-PLAN.md, mit dem, was jede Scheibe liefert, und dem, was mit Absicht eingezäunt ist (Doppelachsen, 3D und Trichter unter anderem).
Wrapper, für den Übergang
Zwei nur im Web nutzbare Wrapper um JavaScript-Bibliotheken gehen der nativen Bibliothek voraus und bleiben verfügbar, bis sie ihre Diagrammtypen abdeckt, woraufhin sie entfernt werden:
•
eQuantic.UI.Charts.ChartJs, Chart.js auf einem HTML5-Canvas: bar, line, pie, doughnut, radar.
•
eQuantic.UI.Charts.ApexCharts, ApexCharts auf SVG: area, bar, line, heatmap, candlestick.
Es sind Opt-in-Pakete, nur fürs Web (auf Photon rendern sie nichts), und sie nehmen die eigene Konfiguration der Bibliothek als C#-Klassen, die ihre JavaScript-API spiegeln:
1
dotnet add package eQuantic.UI.Charts.ApexCharts
1
2
3
4
5
builder.Services.AddUI(options =>
{
options.UseApexCharts() // oder UseChartJs(); jedes liefert die Skripte seiner Bibliothek
.ScanAssembly(typeof(Program).Assembly);
});
1
2
3
4
5
new ApexChart<MyData>
{
Options = new ApexOptions { Chart = new ChartConfig { Type = "bar" } },
Series = [new ApexSeries<MyData> { Name = "Sales", Data = dataList }],
}
Ihre Skripte werden über das Asset-System deklariert und dort injiziert, wo eine Seite sie nutzt; nichts wird von Hand hinzugefügt. Eine Seite, die nur ein Balkendiagramm braucht, sollte das BarChart von oben nutzen: Es rendert auf jedem Ziel, und es ist das, was bleibt.