Témata iframe

Chastify odesílá informace o motivu do rozšíření iframe, aby se vaše uživatelské rozhraní mohlo shodovat s uzamykatelnou stránkou, na které je motiv vložen.

Nepředpokládejte, že uživatel používá tmavý motiv. Vaše rozšíření lze otevřít ve světlém, tmavém, vlastním, průsvitném a vysoce kontrastním motivu.

tip

Nejbezpečnějším výchozím nastavením je považovat datovou část iframe ui za zdroj pravdivých údajů o pozadí stránky, barvě textu a barvě ohraničení a poté odvodit vlastní čitelné panely a odznaky z ui.isDark.

Užitečná hmotnost tématu

Když Chastify otevře váš iframe, připojí k location.hash datovou část JSON s kódováním URI.

Užitečná zátěž zahrnuje 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"
  }
}

Významy polí:

• ui.isDark: zda hostitelská stránka aktuálně používá tmavý motiv.
• ui.bg: pozadí stránky/povrchu z hostitele. Může se jednat o barvu nebo komplexní CSS pozadí.
• ui.text: primární čitelná barva textu.
• ui.border: barva ohraničení, která odpovídá motivu hostitele.

caution

ui.bg může být kompletní řetězec pozadí CSS, nejen hexadecimální barva. Použijte jej jako hodnotu CSS background, nikoli jako hodnotu, kterou parsujete ručně.

Analyzujte hash

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

Minimální CSS proměnné

Převeďte datovou část na CSS proměnné jednou při spuštění:

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

Použijte tyto proměnné v shellu aplikace:

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

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

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

Příklad React

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

Vzor zadního větru

Pokud používáte Tailwind, větvení od ui.isDark pro každý povrch, který obsahuje 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";

Použijte vybrané třídy, kde se text vykresluje:

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

Aktualizace živých motivů

Nadřazený prvek může odesílat aktualizace živého motivu, i když je váš iframe otevřený:

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

Poslechněte si tuto zprávu a ověřte 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);
});

Časté chyby

• Pevné kódování text-white nebo bledý text-*-100 uvnitř karet bez alternativy se světlým tématem.
• Stylování pozadí stránky, ale zapomínání na vnořené karty, odznaky, průběžné kroužky a výsledky.
• ui.bg se považuje za jednoduchou hexadecimální barvu. Může se jednat o gradient nebo prohlížečem normalizovaný řetězec CSS pozadí.
• Používání nativních ovládacích prvků formuláře bez nastavení barvy pozadí i textu. Možnosti výběru se mohou v tmavých motivech stát nečitelnými.
• Za předpokladu, že pro změny motivu je nutné znovu načíst iframe. Pokud chcete aktuální aktualizace, poslouchejte kód chastify:ext:ui.

warning

Data šablony jsou pouze prezentační data. Nepoužívejte je k autorizaci, rozhodování o důvěře, odemykací logice, odměnám, trestům ani identitě backendové relace.

Kontrolní seznam

Před publikováním rozšíření iframe:

• Testovací světlé téma.
• Vyzkoušejte tmavé téma.
• Pokud je k dispozici, otestujte si vlastní motiv.
• Ověřte, zda všechny karty, tlačítka, odznaky, ovládací prvky formulářů, průběžné kroužky a zprávy o výsledcích mají čitelný kontrast.
• Ověřte, zda se text stále vejde na mobil.
• Ověřte, zda se velikost iframe automaticky mění po změně motivu nebo obsahu.

Dále: Rychlý start pro Iframe nebo Příklady API.