Skip to content

Widget-Typ: Chart

chart ist ein bewusst schlanker, performanter Widget-Typ für Liniencharts mit mehreren Serien. Die App rendert ihn nativ per Compose-Canvas und ist auf kleine bis mittlere Dashboard-Kacheln optimiert.

V1-Prinzipien

  • mehrere Kurven pro Diagramm
  • jede Serie darf ein eigenes datasetPath haben
  • keine generische Transform-Sprache im JSON
  • keine Tooltips, keine Interpolation, keine zweite Y-Achse in V1
  • Fokus auf stabile Konfiguration und hohe Render-Performance

Struktur

Ein Chart-Widget kombiniert:

  • normales Widget-Rendering mit Icon, Titel und optionalem Value
  • content.chart für Achsen, Stil und Serien
  • status als JSON-Quelle

Pflichtfelder

{
  "content": {
    "mode": "chart",
    "chart": {
      "xAxis": {
        "kind": "time"
      },
      "series": [
        {
          "id": "pv",
          "datasetPath": "pv.history",
          "x": { "valuePath": "timestamp" },
          "y": { "valuePath": "watts" },
          "color": "#E8B400"
        }
      ]
    }
  },
  "status": {
    "request": {
      "url": "https://example.org/api/energy/history"
    }
  }
}

Mehrere Serien mit getrennten Datensaetzen

Die Kernidee ist serienzentriert:

  • datasetPath verweist pro Serie auf ein eigenes Array
  • x.valuePath und y.valuePath werden innerhalb dieses Arrays gelesen
  • die App fuehrt danach alle Serien auf eine gemeinsame Domain zusammen

Beispiel:

"chart": {
  "xAxis": {
    "kind": "time"
  },
  "yAxis": {
    "unit": "W",
    "zeroLine": true
  },
  "series": [
    {
      "id": "pv",
      "label": "PV",
      "datasetPath": "pv.history",
      "x": { "valuePath": "timestamp" },
      "y": { "valuePath": "watts" },
      "color": "#E8B400"
    },
    {
      "id": "house",
      "label": "Haus",
      "datasetPath": "house.history",
      "x": { "valuePath": "time" },
      "y": { "valuePath": "watts" },
      "color": "#2563EB"
    },
    {
      "id": "battery",
      "label": "Batterie",
      "datasetPath": "battery.points",
      "x": { "valuePath": "ts" },
      "y": { "valuePath": "value" },
      "color": "#059669",
      "lineStyle": "dashed"
    }
  ]
}

X-Werte

xAxis.kind steuert die Interpretation:

  • time: numerische Werte oder ISO-Zeitstrings
  • number: numerische X-Werte

Wichtig:

  • die App sortiert Punkte pro Serie nach X, falls noetig
  • fehlende Punkte zwischen Serien werden nicht kuenstlich aufgefuellt

Y-Achse

Wenn yAxis.min und yAxis.max nicht gesetzt sind:

  • berechnet die App den Bereich automatisch aus allen Serien

Wenn beide gesetzt sind:

  • verwendet die App genau diesen Bereich

Mit zeroLine: true wird eine zusaetzliche Null-Linie gezeichnet, falls 0 innerhalb des Y-Bereichs liegt.

Darstellung im Widget

Im Dashboard zeigt ein Chart-Widget:

  • Icon oder Emoji
  • Titel
  • optional content.value
  • Canvas-Chart
  • optional eine kompakte Legende mit aktuellem Serienwert

Bei sehr vielen Punkten verdichtet die App den Renderpfad pixelbasiert, damit die Kachel flüssig bleibt.

Tipps

  • für Zeitreihen size eher 2/2, 3/2 oder full/2 verwenden
  • showDots nur für wenige Punkte aktivieren
  • yAxis.min und yAxis.max nur setzen, wenn der Zielbereich stabil bekannt ist
  • Serien farblich klar unterscheiden; gestrichelte Linien sind für Ableitungen oder Sollwerte sinnvoll

Siehe auch