Iframe-temaer

Chastify sender temaoplysninger til iframe-udvidelser, så din brugergrænseflade kan matche den låste side, hvor den er integreret.

Antag ikke, at brugeren bruger et mørkt tema. Din udvidelse kan åbnes i lyse, mørke, brugerdefinerede, gennemskinnelige og højkontrast-temaer.

tip

Den sikreste standard er at behandle iframe ui-nyttelasten som sandhedens kilde for sidebaggrund, tekstfarve og kantfarve og derefter udlede dine egne læsbare paneler og badges fra ui.isDark.

Tema nyttelast

Når Chastify åbner din iframe, tilføjer den en URI-kodet JSON-nyttelast til location.hash.

Nyttelasten indeholder 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"
  }
}

Feltbetydninger:

• ui.isDark: om værtsiden i øjeblikket bruger et mørkt udseende tema.
• ui.bg: side-/overfladebaggrund fra værten. Dette kan være en farve eller en kompleks CSS-baggrund.
• ui.text: primær læsbar tekstfarve.
• ui.border: kantfarve, der matcher værtstemaet.

caution

ui.bg kan være en fuld CSS-baggrundsstreng, ikke kun en hex-farve. Brug den som en CSS background-værdi, ikke som en værdi, du parser manuelt.

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

Minimale CSS-variabler

Konverter nyttelasten til CSS-variabler ved opstart:

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

Brug disse variabler i din 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-eksempel

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

Hvis du bruger Tailwind, skal du forgrene fra ui.isDark for hver overflade, der indeholder tekst.

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

Brug de valgte klasser, hvor teksten gengives:

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

Forælderen kan sende live temaopdateringer, mens din iframe er åben:

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

Lyt efter den besked, og bekræft 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);
});

Almindelige fejl

• Hardkodning af text-white eller lyse text-*-100 inde i kort uden et alternativ med et lyst tema.
• Styling af sidens baggrund, men glem indbyggede kort, badges, statusringe og resultatfeeds.
• Behandler ui.bg som en simpel hex-farve. Det kan være en gradient eller en browser-normaliseret CSS-baggrundsstreng.
• Brug af native formularkontroller uden at indstille både baggrunds- og tekstfarve. Valgmuligheder kan blive ulæselige i mørke temaer.
• Forudsat at en iframe-genindlæsning er nødvendig for temaændringer. Lyt efter chastify:ext:ui, hvis du vil have liveopdateringer.

warning

Temadata er kun præsentationsdata. Brug dem ikke til godkendelse, tillidsbeslutninger, oplåsningslogik, belønninger, straffe eller identitet af backend-sessioner.

Tjekliste

Før du udgiver din iframe-udvidelse:

• Test af lystema.
• Test mørkt tema.
• Test et brugerdefineret tema, hvis det er muligt.
• Kontroller, at alle kort, knapper, badges, formularkontroller, statusringe og resultatmeddelelser har læsbar kontrast.
• Bekræft at teksten stadig passer på mobilen.
• Bekræft, at iframe-størrelsen automatisk ændres efter ændringer af tema eller indhold.

Næste: Iframe Quickstart eller API-eksempler.