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
DocsServer
Das System zur Asset-VerwaltungEdit this page
3 min readeQuantic.UI bietet ein deklaratives System für Asset-Abhängigkeiten, mit dem Komponenten die Skripte und Stylesheets deklarieren, die sie brauchen. Die Assets werden beim SSR automatisch gesammelt, dedupliziert und in den <head> der Seite injiziert.
Überblick
Das System löst ein häufiges Problem: Komponenten, die von externen Bibliotheken abhängen (Prism.js, Chart.js usw.), brauchen ihre Skripte und ihr CSS geladen, sollten aber keine <script>-Tags inline in ihr gerendertes HTML einbetten. Stattdessen deklarieren sie Abhängigkeiten, und das Framework übernimmt die Injektion.
1
Gang durch den Komponentenbaum → IRequireAssets sammeln → IComponentAssetProvider<T> sammeln → Deduplizieren → In <head> injizieren
Kerntypen
Alle Typen liegen in eQuantic.UI.Server.Assets.
IAsset
Die Basisschnittstelle aller Asset-Typen.
1
2
3
4
5
6
public interface IAsset
{
string Key { get; } // Eindeutiger Schlüssel für die Deduplizierung
string? Id { get; } // Optionale HTML-Id, für Manipulation auf dem Client
string Render(); // Rendert als HTML-Tag
}
Asset-Implementierungen
Typ
Ausgabe
Format des Schlüssels
ScriptAsset
<script src="..." defer></script>
script:{Src}
InlineScriptAsset
<script>...</script>
inline-script:{hash}
StylesheetAsset
<link rel="stylesheet" href="...">
stylesheet:{Href}
InlineStyleAsset
<style>...</style>
inline-style:{hash}
Alle Typen nehmen einen optionalen Id-Parameter für die DOM-Manipulation auf dem Client:
1
2
new StylesheetAsset("https://cdn.example.com/theme.css", Id: "theme-css")
// Rendert: <link rel="stylesheet" href="https://cdn.example.com/theme.css" id="theme-css">
AssetBuilder
Der fließende Builder, der Komponenten übergeben wird, um Abhängigkeiten zu deklarieren:
1
2
3
4
5
6
7
public class AssetBuilder
{
AssetBuilder AddScript(string src, bool defer = true, string? id = null);
AssetBuilder AddInlineScript(string content, string? id = null);
AssetBuilder AddStylesheet(string href, string? id = null);
AssetBuilder AddInlineStyle(string content, string? id = null);
}
AssetCollection
Sammelt und dedupliziert die Assets. Die Renderreihenfolge ist optimiert: CSS zuerst, dann JS (die richtige Reihenfolge für das Blockieren des Renderns).
1
StylesheetAsset → InlineStyleAsset → ScriptAsset → InlineScriptAsset
Die Deduplizierung nutzt TryAdd mit dem Key des Assets, die erste Registrierung gewinnt also.
Zwei Muster
Muster 1: IRequireAssets (selbst deklarierend)
Für Komponenten, die ihre Abhängigkeiten besitzen. Die Komponente selbst deklariert, was sie braucht.
1
2
3
4
5
6
7
8
9
10
public class CodeBlock : StatelessComponent, IRequireAssets
{
public void ConfigureAssets(AssetBuilder assets)
{
assets.AddStylesheet(
"https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css",
id: "prism-theme");
assets.AddScript("https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js");
}
}
Wann man es nutzt:
•
Framework-Komponenten (CodeBlock, Diagramme usw.)
•
Komponenten, deren Abhängigkeiten wesensmäßig dazugehören
•
Wenn wer die Komponente nutzt, von den darunterliegenden Bibliotheken nichts wissen muss
Muster 2: IComponentAssetProvider\<T\> (externer Anbieter)
Um Assets einer Komponente von außen zuzuordnen, typischerweise bei Fremdkomponenten, die IRequireAssets nicht implementieren.
1
2
3
4
5
6
7
public class ChartJsAssetProvider : IComponentAssetProvider<ChartCanvas>
{
public void ConfigureAssets(AssetBuilder assets)
{
assets.AddScript("https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js");
}
}
Registrierung (wählen Sie eine):
1
2
3
4
5
6
7
8
// Variante 1: automatischer Scan (werden in den gescannten Assemblys selbst gefunden)
options.ScanAssembly(typeof(Program).Assembly);
// Variante 2: ausdrückliche Registrierung über UIOptions
options.WithAssetProvider<ChartJsAssetProvider>();
// Variante 3: manuelle Registrierung in der DI
services.AddSingleton<IComponentAssetProvider<ChartCanvas>, ChartJsAssetProvider>();
Wann man es nutzt:
•
Fremdkomponenten, die Sie nicht ändern können
•
Überschreibungen auf Anwendungsebene für die Assets einer Framework-Komponente
•
Komponenten aus externen Paketen
Vorrang
Wenn beide Muster für denselben Komponententyp existieren:
1.
IRequireAssets läuft zuerst (die Voreinstellung der Komponente)
2.
IComponentAssetProvider<T> läuft danach (der externe Anbieter)
Die Deduplizierung geschieht nach Key, und der erste gewinnt. Wenn der Anbieter das Standard-Asset einer Komponente überschreiben soll, nutzen Sie einen anderen Key (etwa eine andere URL).
Wie es funktioniert (die SSR-Pipeline)
Beim serverseitigen Rendern geht ServerRenderingService den Komponentenbaum ab:
1
2
3
4
5
6
7
8
9
RenderPageAsync()
├── Erzeugt die AssetCollection
├── CollectAssets(rootComponent, assets, services, visited)
│ ├── Prüft IRequireAssets → ConfigureAssets()
│ ├── Prüft die DI auf IComponentAssetProvider<T> → ConfigureAssets()
│ ├── Rekursion in component.Children
│ └── Für eine StatelessComponent → Build() → Rekursion auf dem Ergebnis
├── Rendert das HTML
└── Gibt ein ServerRenderResult mit den Assets zurück
Die Assets werden dann in HtmlShellOptions.HeadTags verschmolzen, bevor die Seite ausgeliefert wird.
Wichtige Verhaltensweisen:
•
Deduplizierung je Typ: Jeder Komponententyp wird einmal verarbeitet (über HashSet<Type>)
•
Deduplizierung je Asset: Jeder Asset-Schlüssel wird einmal registriert (über Dictionary.TryAdd)
•
Null Mehraufwand: Seiten ohne Komponenten, die Assets verlangen, bekommen keine zusätzlichen Tags
•
Nachsichtiger Rückfall: Scheitert Build() (etwa wegen fehlender DI), wird die Komponente übersprungen
Automatische Registrierung
Implementierungen von IComponentAssetProvider<T> werden während AddUI() selbst gefunden:
1
2
3
4
builder.Services.AddUI(options =>
{
options.ScanAssembly(typeof(Program).Assembly); // Findet die Anbieter hier
});
Der Scan sucht in den gescannten Assemblys alle nicht abstrakten Klassen, die IComponentAssetProvider<T> implementieren, und registriert sie über TryAddSingleton als Singletons.
Ausdrückliche Registrierungen über WithAssetProvider<T>() haben Vorrang vor automatisch gescannten (sie werden zuerst registriert).
Beispiel aus der Praxis: CodeBlock
Die Komponente CodeBlock zeigt das ganze Muster:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
public class CodeBlock : StatelessComponent, IRequireAssets
{
public void ConfigureAssets(AssetBuilder assets)
{
// Stylesheet mit Id, für dynamisches Umschalten des Themes
assets.AddStylesheet(
"https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css",
id: "prism-theme");
// Die Kernskripte von Prism.js
assets.AddScript("https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js");
assets.AddScript("https://cdn.jsdelivr.net/npm/prismjs@1.29.0/plugins/autoloader/prism-autoloader.min.js");
// Hilfsfunktionen + automatisches Umschalten zwischen hell und dunkel
assets.AddInlineScript(
"function copyToClipboard(id){...}" +
"function toggleCodeBlock(id){...}" +
"(function(){" +
"function updateTheme(){...}" + // Schaltet zwischen prism.css und prism-tomorrow.css
"updateTheme();" +
"new MutationObserver(function(){updateTheme()})" +
".observe(document.documentElement,{attributes:true,attributeFilter:['class']});" +
"})();"
);
}
}
Wer entwickelt, nutzt einfach new CodeBlock(code, "csharp"), und die Skripte von Prism.js, das CSS, das Umschalten des Themes und die Hilfsfunktionen werden alle automatisch erledigt.
Seit 0.2.0-preview.1
Das Anwendungs-Icon, in C# gezeichnet (IAppIcon)
Das Launcher-Icon ist eine Komponente wie alles andere, im selben Vokabular, es kann also nicht von der Marke abdriften, mit der die Anwendung schon zeichnet:
1
2
3
4
5
6
public sealed class AppIcon : IAppIcon
{
public VisualNode Build(ComponentContext context) =>
Box(new BoxStyle { Background = Brand, CornerRadius = new CornerRadii(0) },
Text("eQ", TypeRole.Display, Ink).Centered());
}
Zwei Zäune, beide vom Medium und nicht vom Framework:
•
Füllen Sie das ganze Quadrat, deckend. Ein transparentes Icon wird gegen das zusammengesetzt, was der Launcher gerade zeigt, und das ist nie das, wogegen Sie entworfen haben.
•
Kein Zustand, keine Interaktion. Es wird einmal gebaut; ein Druck-Handler auf einem Icon ist ein Handler, den niemand erreichen kann. Bleiben Sie bei Formen, Gradienten und höchstens einem oder zwei Buchstaben, denn in der Größe, in der ein Startbildschirm es wirklich zeigt, ist alles Feinere ein Fleck.
Der Build rastert es in jede Größe, die jede Plattform will, und verlinkt die für das Web im Head, ohne dass die Anwendung es sagt.
ON THIS PAGE
Überblick
Kerntypen
IAsset
Asset-Implementierungen
AssetBuilder
AssetCollection
Zwei Muster
Muster 1: IRequireAssets (selbst deklarierend)
Muster 2: IComponentAssetProvider\<T\> (externer Anbieter)
Vorrang
Wie es funktioniert (die SSR-Pipeline)
Automatische Registrierung
Beispiel aus der Praxis: CodeBlock
Das Anwendungs-Icon, in C# gezeichnet (IAppIcon)