iFrame-Themes

Chastify sendet Designinformationen an iFrame-Erweiterungen, damit Ihre Benutzeroberfläche zur Sperrseite passt, auf der sie eingebettet ist.

Gehen Sie nicht davon aus, dass der Benutzer ein dunkles Design verwendet. Ihre Erweiterung kann in hellen, dunklen, benutzerdefinierten, transparenten und kontrastreichen Designs geöffnet werden.

tipp

Die sicherste Standardeinstellung ist, die Nutzlast des iFrames ui als maßgebliche Quelle für Seitenhintergrund, Textfarbe und Rahmenfarbe zu behandeln und dann eigene lesbare Panels und Badges aus ui.isDark abzuleiten.

Themennutzlast

Wenn Chastify Ihren iFrame öffnet, hängt es eine URI-codierte JSON-Nutzlast an location.hash an.

Die Nutzlast enthält ui:

{
  "bridge": {
    "v": 1,
    "nonce": "request-nonce",
    "parentOrigin": "https://chastify.net"
  },
  "sessionId": "extension-session-id",
  "lockId": "lock-id",
  "ui": {
    "isDark": true,
    "bg": "rgb(10, 10, 10)",
    "text": "#e5e7eb",
    "border": "#27272a"
  }
}

Feldbedeutungen:

ui.isDark: Gibt an, ob die Hostseite aktuell ein dunkles Design verwendet.
ui.bg: Seiten-/Oberflächenhintergrund vom Host. Dies kann eine Farbe oder ein komplexer CSS-Hintergrund sein.
ui.text: Primäre lesbare Textfarbe.
ui.border: Rahmenfarbe, die zum Host-Design passt.

vorsicht

ui.bg kann eine vollständige CSS-Hintergrundzeichenfolge sein, nicht nur eine Hexadezimalfarbe. Verwenden Sie es als CSS-Wert background, nicht als einen Wert, den Sie manuell parsen.

Hash analysieren

type ChastifyThemePayload = {
  ui?: {
    isDark?: boolean;
    bg?: string;
    text?: string;
    border?: string;
  };
};

export function parseHashPayload(): ChastifyThemePayload | null {
  const raw = window.location.hash.startsWith("#")
    ? window.location.hash.slice(1)
    : window.location.hash;

  if (!raw) return null;

  try {
    return JSON.parse(decodeURIComponent(raw));
  } catch {
    return null;
  }
}

Minimale CSS-Variablen

Die Nutzdaten werden einmalig beim Start in CSS-Variablen umgewandelt:

const payload = parseHashPayload();
const ui = payload?.ui ?? {};
const isDark = ui.isDark !== false;

document.documentElement.style.setProperty("--chastify-bg", ui.bg || (isDark ? "#040711" : "#f8fafc"));
document.documentElement.style.setProperty("--chastify-text", ui.text || (isDark ? "#e5e7eb" : "#0f172a"));
document.documentElement.style.setProperty("--chastify-border", ui.border || (isDark ? "#27272a" : "#e2e8f0"));
document.documentElement.dataset.themeMode = isDark ? "dark" : "light";

Verwenden Sie diese Variablen in Ihrer App-Shell:

html,
body,
#root {
  min-height: 100%;
  margin: 0;
}

body {
  background: var(--chastify-bg);
  color: var(--chastify-text);
}

.panel {
  border: 1px solid var(--chastify-border);
}

React-Beispiel

import { useMemo } from "react";

function getTheme(payload: any) {
  const ui = payload?.ui ?? {};
  const isDark = ui.isDark !== false;

  return {
    isDark,
    pageStyle: {
      background: ui.bg || (isDark ? "#040711" : "#f8fafc"),
      color: ui.text || (isDark ? "#e5e7eb" : "#0f172a"),
    } satisfies React.CSSProperties,
    panelClass: isDark
      ? "border-white/10 bg-black/35 text-slate-100"
      : "border-slate-200 bg-white/85 text-slate-950 shadow-sm",
    mutedClass: isDark ? "text-slate-400" : "text-slate-600",
    badgeClass: isDark
      ? "bg-sky-400/15 text-sky-200"
      : "bg-sky-50 text-sky-900 ring-1 ring-sky-200",
  };
}

export function ExtensionApp({ payload }: { payload: any }) {
  const theme = useMemo(() => getTheme(payload), [payload]);

  return (
    <main style={theme.pageStyle} className="min-h-screen p-4">
      <section className={`rounded-2xl border p-4 ${theme.panelClass}`}>
        <h1 className="text-xl font-bold">My Extension</h1>
        <p className={`mt-2 text-sm ${theme.mutedClass}`}>
          This text stays readable on light and dark Chastify themes.
        </p>
        <span className={`mt-3 inline-flex rounded-full px-3 py-1 text-xs font-semibold ${theme.badgeClass}`}>
          Connected
        </span>
      </section>
    </main>
  );
}

Rückenwindmuster

Wenn Sie Tailwind verwenden, verzweigen Sie von ui.isDark für jede Oberfläche, die Text enthält.

const isDarkTheme = payload?.ui?.isDark !== false;

const panelClass = isDarkTheme
  ? "border-white/10 bg-black/30 text-slate-100"
  : "border-slate-200 bg-white/85 text-slate-950 shadow-sm";

const successClass = isDarkTheme
  ? "border-emerald-300/20 bg-emerald-400/10 text-emerald-100"
  : "border-emerald-500/25 bg-emerald-50 text-emerald-950";

const errorClass = isDarkTheme
  ? "border-rose-300/20 bg-rose-400/10 text-rose-100"
  : "border-rose-500/25 bg-rose-50 text-rose-950";

Verwenden Sie die ausgewählten Klassen, in denen der Text gerendert wird:

<div className={`rounded-xl border px-3 py-2 text-sm ${result.ok ? successClass : errorClass}`}>
  <div className="font-semibold">{result.title}</div>
  <div className="mt-1 opacity-85">{result.message}</div>
</div>

Live-Theme-Updates

Das übergeordnete Element kann Live-Theme-Updates senden, während Ihr iFrame geöffnet ist:

type UiUpdateMessage = {
  type: "chastify:ext:ui";
  v: 1;
  nonce: string;
  ui: {
    isDark?: boolean;
    bg?: string;
    text?: string;
    border?: string;
  };
};

Achten Sie auf diese Nachricht und überprüfen Sie die Nonce:

const nonce = payload.bridge.nonce;
const parentOrigin = payload.bridge.parentOrigin;

window.addEventListener("message", (event) => {
  if (event.origin !== parentOrigin) return;

  const msg = event.data as Partial<UiUpdateMessage>;
  if (msg.type !== "chastify:ext:ui" || msg.v !== 1) return;
  if (msg.nonce !== nonce) return;

  applyTheme(msg.ui);
});

Häufige Fehler

Fest codierter text-white oder blasses text-*-100 in Karten ohne eine Alternative mit hellem Design.
Die Gestaltung des Seitenhintergrunds wird zwar übernommen, aber verschachtelte Karten, Abzeichen, Fortschrittsringe und Ergebnisfeeds werden vergessen.
ui.bg wird als einfache Hexadezimalfarbe behandelt. Es kann sich um einen Farbverlauf oder eine browsernormalisierte CSS-Hintergrundzeichenfolge handeln.
Die Verwendung nativer Formularsteuerelemente ohne gleichzeitige Festlegung von Hintergrund- und Textfarbe kann dazu führen, dass Auswahloptionen in dunklen Designs unleserlich werden.
Vorausgesetzt, dass für Designänderungen ein iFrame neu geladen werden muss. Achten Sie auf chastify:ext:ui, wenn Sie Live-Updates erhalten möchten.

warnung

Themendaten dienen ausschließlich der Präsentation. Sie dürfen nicht für Autorisierungen, Vertrauensentscheidungen, Entsperrlogik, Belohnungen, Bestrafungen oder die Backend-Sitzungsidentität verwendet werden.

Checklist

Vor der Veröffentlichung Ihrer iFrame-Erweiterung:

Lichtthema testen.
Test des dunklen Designs.
Testen Sie gegebenenfalls ein benutzerdefiniertes Design.
Prüfen Sie, ob alle Karten, Schaltflächen, Abzeichen, Formularsteuerelemente, Fortschrittsringe und Ergebnismeldungen einen gut lesbaren Kontrast aufweisen.
Prüfen Sie, ob der Text auch auf Mobilgeräten noch passt.
Prüfen Sie, ob sich die Größe des iFrames nach Änderungen am Design oder Inhalt automatisch anpasst.

Weiter: Iframe Quickstart oder API Examples.

Themennutzlast​

Hash analysieren​

Minimale CSS-Variablen​

React-Beispiel​

Rückenwindmuster​

Live-Theme-Updates​

Häufige Fehler​

Checklist​