Утилиты

Методы экземпляра, общие для ReactiveResponsiveState и ContainerState (наряду с API подписки), плюс несколько автономных функций.

Синхронизация CSS-переменных

syncCSSVars(options?)

() => void

Синхронизирует все ключи брейкпоинтов с CSS custom properties (1 / 0) на document.documentElement (или на кастомном элементе). Автоматически удаляет свойства для ключей, убранных при изменении конфига.

const stop = state.syncCSSVars({ element: document.body, prefix: '--bp-' })
// → --bp-mobile: 1; --bp-desktop: 0; …
stop() // очистка

element

HTMLElement · по умолчанию: document.documentElement

Целевой HTML-элемент.

prefix

string · по умолчанию: '--responsive-'

Префикс имени CSS custom property.

Диспатч DOM-событий

emitDOMEvents(target?, options?)

() => void

Диспатчит DOM CustomEvent на target при каждом изменении брейкпоинтов:

• responsive:change — срабатывает при любом изменении состояния; event.detail — полный снапшот состояния
• responsive:mobile:enter — срабатывает, когда mobile становится true
• responsive:mobile:leave — срабатывает, когда mobile становится false

const stop = state.emitDOMEvents(document, { prefix: 'bp:' })

document.addEventListener('bp:change', (e) => console.log(e.detail))
document.addEventListener('bp:mobile:enter', () => initDrawer())
document.addEventListener('bp:desktop:leave', () => destroyDesktopChart())

stop()

prefix (emitDOMEvents)

string · по умолчанию: 'responsive:'

Префикс имени кастомного события.

Преобразование в сигнал

toSignal(key, factory)

Signal<boolean>

Привязывает ключ брейкпоинта к записываемому сигналу из любой библиотеки сигналов. Сигнал синхронизируется через on().

// @preact/signals-core
import { signal } from '@preact/signals-core'
const isMobile = state.toSignal('mobile', signal)
isMobile.value // реактивный boolean

// Angular signal
import { signal } from '@angular/core'
const isMobile = state.toSignal('mobile', signal)

// Vue ref
import { ref } from 'vue'
const isMobile = state.toSignal('mobile', ref)

Получение media query

getMediaQueries()

Record<string, string>

Возвращает сгенерированные строки CSS media query для каждого ключа брейкпоинта.

const mq = state.getMediaQueries()
// { mobile: '(max-width: 600px)', desktop: '(min-width: 961px)' }

Снапшот состояния

getState<T>()

T

Возвращает стабильный снапшот текущего состояния. Одна и та же ссылка между изменениями — безопасно для React useSyncExternalStore.

Порядок брейкпоинтов

getOrder()

string[]

Возвращает настроенный массив порядка брейкпоинтов (либо пустой массив, если не задан).

Гидратация SSR

hydrate(initialState)

Гидратация SSR: устанавливает начальное состояние из серверного снапшота, чтобы предотвратить сдвиг разметки. Обновляет только те ключи, что есть в текущем конфиге — ключ, отсутствующий в актуальном конфиге (например, после того как setConfig() сузил набор ключей), отбрасывается. В dev-сборках отбрасывание ключа также логирует один console.warn с перечислением всех отброшенных ключей; в production-сборках, как и раньше, никакого предупреждения нет.

state.hydrate({ mobile: false, tablet: false, desktop: true })

Уничтожение

destroy()

Удаляет все слушатели matchMedia / ResizeObserver, очищает всех подписчиков и отменяет любой ожидающий таймер debounce.

Строка media query

toMediaQueryString(conditions)

string · автономная функция (не метод state)

Конвертирует MediaQueryConfig в строку CSS media query. Полезно для CSS-in-JS или отладки.

import { toMediaQueryString } from 'responsive-media'

toMediaQueryString([
  { type: 'min-width', value: 768 },
  { type: 'max-width', value: 1024 },
])
// → "(min-width: 768px) and (max-width: 1024px)"

toMediaQueryString([
  [{ type: 'max-width', value: 600 }],
  [{ type: 'orientation', value: 'portrait' }],
])
// → "(max-width: 600px), (orientation: portrait)"

Сопоставление

match(state, map, fallback?)

Автономная функция (не метод state). Возвращает первое значение в map, чей ключ равен true в state. Приоритет соответствует порядку вставки в map.

import { match } from 'responsive-media'
import { responsiveState } from 'responsive-media'

const cols = match(responsiveState.proxy, { mobile: 1, tablet: 2, desktop: 4 })
const View = match(responsiveState.proxy, { mobile: MobileMenu, desktop: DesktopNav })
const label = match(responsiveState.proxy, { sm: 'Compact', lg: 'Full' }, 'Default')

Подписка на media query

subscribeMediaQuery(query, callback)

() => void · автономная функция (не метод state)

Низкоуровневая реактивная обёртка вокруг одной сырой строки CSS media query. Фреймворк-агностична — адаптеры Vue и React используют её внутри себя.

import { subscribeMediaQuery } from 'responsive-media'

const off = subscribeMediaQuery('(prefers-color-scheme: dark)', (matches) => {
  document.body.classList.toggle('dark', matches)
})
off() // очистка

Размер вьюпорта

getViewportSize()

{ width: number; height: number }

Размер окна, на сервере — 0 на 0.

subscribeViewportSize(callback, options?)

() => void

Вызывает callback сразу, а затем при каждом resize и orientationchange, с ограничением частоты. Возвращает функцию отписки.

import { subscribeViewportSize } from 'responsive-media'

const stop = subscribeViewportSize(({ width, height }) => console.log(width, height), {
  throttle: 200,
})

• throttle — number · по умолчанию: 100. Миллисекунды между вызовами; первое изменение доставляется сразу, а последнее не теряется. 0 доставляет каждое событие.

Состояние для размера

statesFromSize(config, size)

Record<string, boolean>

Булево состояние конфига для заданного { width, height } без участия браузера. Понимает условия width, height, orientation и aspect-ratio — те же, что и состояние контейнера. На нём построены подсказки запроса.

statesFromSize(config, { width: 390, height: 844 }) // { mobile: true, tablet: true, desktop: false }

Серверный снимок

getSsrState()

Record<string, boolean>

Стабильный снимок того, каким состояние бывает на сервере: значения ssrState, а для остальных ключей false. В браузере он тот же, и именно это позволяет адаптерам гидратироваться без несовпадения.

Состояние пользовательских предпочтений

getUserPreferencesState()

ReactiveResponsiveState

Общее состояние поверх AccessibilityPreset, которое читает useUserPreferences(). Используйте его из обычного JavaScript — с теми же subscribe, on и getState, что и у любого другого состояния.

Экспорт в CSS

toMediaQueries, toScssModule, toScssMap, toCustomMedia и toTailwindScreens записывают конфиг для стилей — см. Интеграция с CSS.