Skip to content

Widget-Typ: Bild

Bild-Widgets stellen PNG- und JPG-Antworten direkt im Dashboard dar. Sie eignen sich vor allem für Kameras, Visualisierungen oder Snapshots.

Zwei Wege zum Bild-Widget

Explizit

"content": {
  "mode": "image"
}

Automatisch

"content": {
  "mode": "auto"
}

auto ist praktisch, wenn ein Endpoint sicher ein PNG liefert und dasselbe Widget im Fehlerfall dennoch als Icon/Text behandelt werden soll.

Statusquelle

Typischerweise liefert status.request.url direkt ein PNG:

"status": {
  "request": {
    "url": "https://example.org/camera/frontdoor/latest.png"
  }
}

Optional kann responseKind = "png" oder responseKind = "jpg" gesetzt werden, wenn der Typ strikt erzwungen werden soll.

Overlay von Titel und Value

Bild-Widgets können unten links ein Text-Overlay anzeigen:

  • title
  • value

Das Overlay wird nur gerendert, wenn mindestens einer der beiden Texte vorhanden ist.

Beispiel:

"title": {
  "mode": "static",
  "value": "Eingang"
},
"value": {
  "mode": "template",
  "value": "{{temperature}} C"
}

WidgetImageConfig

Im bildspezifischen Teil gibt es aktuell drei zentrale Parameter:

Feld Typ Default Bedeutung
contentScale crop, fit, fill_bounds crop Skalierung des Bildes
enableDownload true, false false zeigt unten rechts ein kleines Downloadsymbol und speichert das aktuell angezeigte Bild im Downloads-Ordner
enableExpand true, false false zeigt unten rechts ein Vergrößern-Symbol und öffnet das aktuelle Bild unbeschnitten in einer möglichst bildschirmfüllenden Ansicht

Aktionen im Bild-Overlay

Mit content.onWidgetActions lassen sich zusätzliche Buttons direkt im Widget definieren. Bei Bild-Widgets erscheinen sie unten rechts im selben Overlay wie Download und Vergrößern. Jede Aktion verwendet dieselbe WidgetActionConfig wie widgets[].action.

Beispiel:

"content": {
  "mode": "image",
  "onWidgetActions": [
    {
      "icon": "bolt",
      "label": "Tor auf",
      "action": {
        "type": "endpoint",
        "request": {
          "url": "https://example.org/gate/open"
        },
        "prompt": true,
        "refreshAfterAction": false
      }
    },
    {
      "icon": "camera",
      "label": "Kameraseite",
      "action": {
        "type": "open_url",
        "url": "https://example.org/camera/frontdoor"
      }
    }
  ],
  "image": {
    "contentScale": "crop",
    "enableDownload": true,
    "enableExpand": true
  }
}

Hinweise:

  • icon verwendet denselben Material-Icon-Namensraum wie content.icon.name
  • label ist optional und hilft bei der Unterscheidung mehrerer Buttons; bei prompt: true erscheint es zusätzlich im Bestätigungsdialog und für die Barrierefreiheit
  • action unterstützt dieselben Aktionsarten wie normale Widget-Taps: endpoint, switch_tab und open_url
  • content.onWidgetActions funktioniert bei allen Widget-Arten, nicht nur bei Bild-Widgets
  • frei definierte Overlay-Aktionen erscheinen vor den eingebauten Buttons für Vergrößern und Download
  • bestehende Image-Konfigurationen mit image.onWidgetActions werden weiterhin gelesen; für neue Konfigurationen ist content.onWidgetActions der bevorzugte Pfad

Beispiel

{
  "id": "outdoor-camera",
  "layout": {
    "order": 20,
    "size": "2/1"
  },
  "content": {
    "mode": "image",
    "onWidgetActions": [
      {
        "icon": "bolt",
        "label": "Tor auf",
        "action": {
          "request": {
            "url": "https://example.org/gate/open"
          },
          "prompt": true,
          "refreshAfterAction": false
        }
      }
    ],
    "icon": {
      "name": "camera",
      "defaultColor": "#2F4C57"
    },
    "title": {
      "mode": "static",
      "value": "Eingang"
    },
    "value": {
      "mode": "static",
      "value": "Live"
    },
    "image": {
      "contentScale": "crop",
      "enableDownload": true,
      "enableExpand": true
    }
  },
  "status": {
    "request": {
      "url": "https://example.org/camera/frontdoor/latest.jpg"
    },
    "responseKind": "jpg"
  }
}

Fehler- und Fallback-Verhalten

  • bei mode = "image" und echter PNG- oder JPG-Antwort wird das Bild gezeigt
  • bei mode = "image" ohne Bilddaten fällt das Widget auf Icon/Text zurück
  • bei mode = "auto" entscheidet die Antwortart
  • bei Fehlern wird das Widget wie alle anderen ausgegraut

Empfehlungen

  • Kamerabilder eher in 2/1, 3/1, 2/2 oder full/1 platzieren
  • Overlay-Texte kurz halten
  • enableDownload fuer Kamerasnapshots oder Belegbilder aktivieren, wenn Anwender Einzelbilder lokal sichern sollen
  • enableExpand aktivieren, wenn ein zugeschnittenes Tile als Schnellvorschau dient und das Originalbild bei Bedarf voll sichtbar sein soll
  • content.onWidgetActions für kamera-nahe Schnellaktionen nutzen, zum Beispiel Tor öffnen, Licht schalten oder Kameraseite im Browser öffnen
  • für Kamera-Links zusätzlich eine open_url-Aktion nutzen

Siehe auch