Оформление Iframe

Chastify отправляет информацию о теме расширениям iframe, чтобы ваш пользовательский интерфейс соответствовал странице блокировки, в которую он встроен.

Не следует предполагать, что пользователь использует темную тему. Ваше расширение может открываться в светлой, темной, пользовательской, полупрозрачной и высококонтрастной темах.

подсказка

Наиболее безопасный вариант по умолчанию — рассматривать содержимое iframe ui как источник достоверной информации о фоне страницы, цвете текста и цвете границы, а затем создавать собственные читаемые панели и значки на основе ui.isDark.

Тема Полезная нагрузка

Когда Chastify открывает ваш iframe, он добавляет закодированную в URI JSON-данные к location.hash.

Полезная нагрузка включает 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"
  }
}

Значения полей:

ui.isDark: указывает, используется ли на главной странице в данный момент темная тема оформления.
ui.bg: фон страницы/поверхности, заданный хостом. Это может быть цвет или сложный CSS-файл фона.
ui.text: основной читаемый цвет текста.
ui.border: цвет границы, соответствующий теме оформления хоста.

предупреждение

ui.bg может быть полноценной строкой CSS-кода фона, а не только шестнадцатеричным значением цвета. Используйте его как значение CSS background, а не как значение, которое вы анализируете вручную.

Разбор хеша

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

Минимальное количество переменных CSS

Преобразуйте полезную нагрузку в переменные CSS один раз при запуске:

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

Используйте эти переменные в оболочке вашего приложения:

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

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

Схема попутного ветра

Если вы используете Tailwind, создайте ветку от ui.isDark для каждой поверхности, содержащей текст.

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

Используйте выбранные классы там, где отображается текст:

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

Обновления тем в реальном времени

Родительский элемент может отправлять обновления темы в режиме реального времени, пока ваш iframe открыт:

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

Прослушайте это сообщение и проверьте значение 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);
});

Распространенные ошибки

В коде карточек без альтернативной светлой темы жестко заданы значения text-white или бледно-розовые text-*-100.
Оформление фона страницы, но без учёта вложенных карточек, значков, колец прогресса и ленты результатов.
Обрабатываем ui.bg как простой шестнадцатеричный код цвета. Это может быть градиент или стандартизированная в браузере строка CSS для фона.
Использование стандартных элементов управления форм без установки цвета фона и текста. Выбранные параметры могут стать нечитаемыми в темных темах.
Предполагается, что для смены темы требуется перезагрузка iframe. Для получения обновлений в реальном времени следите за кодом chastify:ext:ui.

warning

Данные темы предназначены исключительно для отображения. Не используйте их для авторизации, принятия решений о доверии, логики разблокировки, вознаграждений, наказаний или идентификации сессии в бэкэнде.

Контрольный список

Перед публикацией расширения iframe:

Тема для тестового индикатора.
Протестируйте темную тему.
Если такая возможность доступна, протестируйте пользовательскую тему оформления.
Убедитесь, что все карточки, кнопки, значки, элементы управления формами, индикаторы выполнения и сообщения о результатах имеют читаемый контраст.
Убедитесь, что текст по-прежнему помещается на мобильном устройстве.
Убедитесь, что iframe автоматически изменяет размер после изменения темы или контента.

Далее: Быстрый старт для Iframe или Примеры API.

Тема Полезная нагрузка​

Разбор хеша​

Минимальное количество переменных CSS​

Пример React​

Схема попутного ветра​

Обновления тем в реальном времени​

Распространенные ошибки​

Контрольный список​