Iframe-teman

Chastify skickar temainformation till iframe-tillägg så att ditt användargränssnitt kan matcha låssidan där det är inbäddat.

Anta inte att användaren använder ett mörkt tema. Ditt tillägg kan öppnas i ljusa, mörka, anpassade, genomskinliga och högkontrastteman.

tips

Det säkraste standardvärdet är att behandla iframe-nyttolasten ui som sanningskälla för sidbakgrund, textfärg och kantfärg, och sedan härleda dina egna läsbara paneler och märken från ui.isDark.

Tema nyttolast

När Chastify öppnar din iframe lägger den till en URI-kodad JSON-nyttolast till location.hash.

Nyttolasten inkluderar 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"
  }
}

Fältbetydelser:

ui.isDark: om värdsidan för närvarande använder ett mörkt tema.
ui.bg: bakgrund för sidan/ytan från värden. Detta kan vara en färg eller en komplex CSS-bakgrund.
ui.text: primär läsbar textfärg.
ui.border: kantfärg som matchar värdtemat.

varning

ui.bg kan vara en fullständig CSS-bakgrundssträng, inte bara en hexagonal färg. Använd den som ett CSS background-värde, inte som ett värde du analyserar manuellt.

Analysera hashen

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;
  }
}

Minimala CSS-variabler

Konvertera nyttolasten till CSS-variabler vid uppstart:

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";

Använd dessa variabler i ditt app-skal:

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

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

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

Reagera exempel

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>
  );
}

Medvindsmönster

Om du använder Tailwind, förgrena dig från ui.isDark för varje yta som innehåller text.

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";

Använd de valda klasserna där texten renderas:

<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>

Uppdateringar av live-tema

Föräldern kan skicka live-temauppdateringar medan din iframe är öppen:

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

Lyssna efter meddelandet och verifiera noncen:

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);
});

Vanliga misstag

Hårdkodning av text-white eller bleka text-*-100 inuti kort utan ett alternativ med ljust tema.
Styla sidans bakgrund men glöm kapslade kort, märken, framstegsringar och resultatflöden.
Behandlar ui.bg som en enkel hexagonal färg. Det kan vara en gradient eller en webbläsarnormaliserad CSS-bakgrundssträng.
Använder inbyggda formulärkontroller utan att ställa in både bakgrunds- och textfärg. Valda alternativ kan bli oläsliga i mörka teman.
Förutsatt att en iframe-omladdning behövs för temaändringar. Lyssna efter chastify:ext:ui om du vill ha liveuppdateringar.

warning

Temadata är endast presentationsdata. Använd den inte för auktorisering, förtroendebeslut, upplåsningslogik, belöningar, straff eller identitet för backend-sessioner.

Checklista

Innan du publicerar ditt iframe-tillägg:

Testa ljustema.
Testa mörkt tema.
Testa ett anpassat tema om det är tillgängligt.
Kontrollera att alla kort, knappar, märken, formulärkontroller, förloppsringar och resultatmeddelanden har läsbar kontrast.
Kontrollera att texten fortfarande får plats på mobilen.
Verifiera att iframe-storleken ändras automatiskt efter tema- eller innehållsändringar.

Nästa: Iframe Quickstart eller API-exempel.

Tema nyttolast​

Analysera hashen​

Minimala CSS-variabler​

Reagera exempel​

Medvindsmönster​

Uppdateringar av live-tema​

Vanliga misstag​

Checklista​