Оформление: микрофронтенд-приложения

Справочник по оформлению покрывает полный каталог CSS-переменных. Этот документ описывает, как микрофронтенд-приложение получает тему.

Как тема доходит до вашего приложения

Хост вставляет CSS в iframe вашего микрофронтенд-приложения через конвейер инъекции прокси. Текущая схема времени выполнения — wippy-context-2.0: оформление фасада представлено как theming.global, theming.host и theming.children; дочерняя страница получает свою действующую тему для дочернего контекста как config.theming.global.

L1 — Глобальный уровень (уровень фасада)

CSS-переменные, заданные в глобальной области оформления фасада, автоматически доходят до хоста и всех iframe через инъекции прокси themeConfig и пользовательских переменных. Это основное место для брендовой палитры, акцентного цвета и любого оформления, которое должно применяться единообразно везде.

- name: css_variables
  value: '{"--p-primary":"#4f8ef7","--p-secondary":"#6f7385","--p-danger":"#dc2626"}'

L2 — Ограниченная область (host или children)

Фасад предоставляет отдельные области текущей схемы для оболочки хоста и для дочерних iframe:

Область схемы Куда доходит Для чего использовать
theming.host Только оболочка интерфейса хоста Боковая панель, сообщения чата, разделитель — переопределения BEM хоста
theming.children Только дочерние iframe CSS, применяемый внутри дочерних приложений, но не должный утекать в хост

CSS, заданный в children_css_variables или children_custom_css, доходит до вашего микрофронтенд-приложения; переменные области хоста нацелены только на оболочку Web Host.

L3 — На уровне страницы (config_overrides в YAML реестра)

Задайте странице собственную тему, установив config_overrides.customization.cssVariables / customCSS в YAML записи реестра этой страницы. Переопределение проецируется в theming.global страницы, поэтому оно оформляет страницу и всё, что страница встраивает: вложенное содержимое <w-artifact> / <w-iframe> / html.inject строится из уже слитой конфигурации страницы и наследует тему рекурсивно вниз по поддереву. Это инструмент для поставки самооформленного поддерева: например, административного модуля, чьи страницы несут отдельную тему, распространяющуюся на все размещаемые ими артефакты и подприложения. Соседние страницы и остальную оболочку приложения он не затрагивает.

- name: iframe-demo-themed
  kind: registry.entry
  meta:
    type: view.page
    config_overrides:
      customization:
        cssVariables:
          "--p-primary": "#9c59d1"
          "@light":
            "--p-content-background": "#faf5ff"
          "@dark":
            "--p-content-background": "#1a0d22"
        customCSS: |
          .demo-banner { background: var(--p-primary-color); color: var(--p-primary-contrast-color); }

Записи верхнего уровня применяются во всех режимах темы. @dark и @light заменяют выбранные записи и компилируются как в медиа-блоки режима Auto, так и в принудительные селекторы .w-theme-dark / .w-theme-light. Этими классами владеет хост; приложения не выдумывают параллельный протокол data-theme.

Зеркало в package.json под wippy.configOverrides предоставляет ту же форму для host-less-рендеринга (автономный dev-просмотр, модульные тесты). Держите оба в синхронизации; при наличии хоста побеждает YAML.

Включение инъекции CSS

В блоке wippy вашего package.json настройте, какие инъекции запрашивает ваше микрофронтенд-приложение:

"wippy": {
  "type": "page",
  "proxy": {
    "injections": {
      "css": {
        "themeConfig":      true,   // CSS-переменные --p-* (theme-config.css)
        "primevue":         true,   // CSS компонентов PrimeVue (~455 КБ)
        "markdown":         false,  // стили markdown для .data-body
        "iframe":           true,   // оформление полос прокрутки
        "customCss":        true,   // theming.global.customCSS, проецируемый в дочерний контекст
        "customVariables":  true    // theming.global.cssVariables, проецируемые в дочерний контекст
      },
      "tailwindConfig": false       // УСТАРЕВШЕЕ, только для рантайм-Tailwind; для сборок Vite оставьте false
    }
  }
}

При опущенных флагах прокси iframe использует широкие рантайм-умолчания. Включите эти флаги, чтобы получать CSS темы в своём микрофронтенд-приложении (это краткое изложение с фокусом на оформлении, а не авторитетный список флагов):

  • css.themeConfig — полная система CSS-переменных --p-* (theme-config.css). Включите, чтобы унаследовать палитру темы.
  • css.primevue — стили компонентов PrimeVue. Включите для приложений, использующих PrimeVue.
  • css.customCss — составленный хостом пользовательский CSS для дочернего контекста: глобальный + children пользовательский CSS фасада, слитый в config.theming.global.customCSS, плюс любое переопределение на уровне страницы. Флаг управляет этой инъекцией, а не именует одну конкретную область. Включите, чтобы получать пользовательский CSS фасада/страницы.
  • css.customVariables — проецируемые в дочерний контекст config.theming.global.cssVariables как действующие блоки базы, Auto-light, Auto-dark, принудительного Light и принудительного Dark. Включите, чтобы получать переопределения переменных темы.
  • css.markdown — стили markdown для .data-body. Включайте, только если ваша страница отображает markdown-содержимое.

Полный справочник флагов и рантайм-умолчаний: Инъекция CSS.

Замечание про dev-режим: dev-оверлей стартует с ОТКЛЮЧЁННЫМИ по умолчанию themeConfig, primevue, markdown и iframe. Включите их в оверлее, чтобы увидеть настоящее оформление локально. Отметьте "Auto-accept on reload", чтобы настройка сохранялась между перезагрузками.

Порядок слияния — что что переопределяет

Когда хост применяет AppConfig (побеждает последний записавший):

  1. Умолчания theme-config.css (запасной вариант для разработки)
  2. Фасадные theming.global и обращённая к дочерним контекстам theming.children
  3. Страничные wippy.configOverrides (декларативные, запечённые в страницу)
  4. window.__WIPPY_CONFIG_OVERRIDES__ (во время выполнения, если задано до загрузки прокси)

Для cssVariables: карта переопределений заменяет унаследованную дочернюю карту — пишите полный набор, который вам нужен. Для icons/iconSets: дополняющее слияние. Для axiosDefaults, routePrefix и apiRoutes хост применяет текущие правила слияния AppConfigOverrides для этих полей.

Рантайм-переопределения (window.__WIPPY_CONFIG_OVERRIDES__)

Задайте эту глобальную переменную до запуска proxy.js для оформления, управляемого query-параметрами или флагами функциональности:

Эта глобальная переменная, устанавливаемая до прокси, — аварийный люк для встраивания и host-less-интеграции. В размещённом дочернем контексте window.location принадлежит выбранному движку страницы (при доставке через iframe — about:srcdoc) и не является ни маршрутом хоста, ни его query-контекстом. Используйте декларативные config_overrides страницы или AppConfig, предоставленный хостом. Никогда не выводите состояние хоста из browser location дочернего или родительского контекста.

Проверка

Чтобы убедиться, что CSS-переменные активны на работающей странице: откройте DevTools, выберите контекст внутреннего iframe (не внешней страницы), затем выполните:

getComputedStyle(document.documentElement).getPropertyValue('--p-primary-color')

Непустой результат доказывает лишь то, что какой-то CSS темы загрузился. Сравните точное настроенное значение в корне страницы, на хосте веб-компонента, во внутреннем корне веб-компонента и в отрисованном семантическом цвете; проверьте каждое настроенное семейство. Полный порядок действий: Отладка.

Связанные документы

  • theming.md — каталог CSS-переменных и антипаттерны
  • web-component-theming.md — оформление веб-компонентов (shadow DOM)
  • micro-frontend-app.md — полное руководство по разработке микрофронтенд-приложений
  • host-less-mode.md — dev-оверлей и инъекция CSS в host-less-режиме
  • compliance-checklist.md — полные правила REJECT/WARN для оформления