ECSSv0.2

🇷🇺 Русский

🇬🇧 English

🇷🇺 Русский

🇬🇧 English

Тема

React ​

@ecss/react-adapter генерирует типизированные React-компоненты из объявлений @block и @element. id адаптера — 'react'.

Установка ​

sh
npm i -D @ecss/react-adapter
sh
pnpm add -D @ecss/react-adapter
sh
yarn add -D @ecss/react-adapter

Требуется установленный react версии 18 или выше.

Подключение ​

Адаптер регистрируется в ecss.config.ts через defineConfig из @ecss/config — конфиг не привязан к конкретному сборщику, его читает ECSS-плагин вашего бандлера. defaultAdapter задаёт адаптер, применяемый к .ecss-файлам по умолчанию:

ts
// ecss.config.ts
import { defineConfig } from '@ecss/config';
import { reactAdapter } from '@ecss/react-adapter';

export default defineConfig({
  adapters: [reactAdapter()],
  defaultAdapter: 'react',
});

Использование ​

Компоненты импортируются напрямую из .ecss-файла — по одному на каждый @block. Имя компонента формируется как {префикс}{BlockName} (по умолчанию префикс E): @block Button → EButton.

tsx
import { EButton } from './Button.ecss';

<EButton as="button" params={{ variant: 'primary' }} onClick={handleClick}>
  Нажми меня
</EButton>;

Проп params ​

Параметры блока передаются единственным пропом params. Их типы берутся из сгенерированного интерфейса {Block}Params (например ButtonParams), поэтому передать несуществующее значение @enum не получится.

params обязателен, если у блока есть хотя бы один обязательный @param (без ?); если все параметры опциональны или их нет вовсе — проп можно опустить.

tsx
<EButton params={{ variant: 'primary' }} /> // variant обязателен
<ECard />                                    // у Card все параметры опциональны

Проп as ​

По умолчанию компонент рендерится как <div>. Проп as принимает любой HTML-тег и меняет корневой элемент. Компонент типизирован generic-параметром по выбранному тегу, поэтому набор допустимых HTML-атрибутов сужается автоматически:

tsx
<EButton as="button" type="submit" params={{ variant: 'primary' }}>Отправить</EButton>

<EButton as="a" href="/about" params={{ variant: 'ghost' }}>Ссылка</EButton>

При as="a" доступны href, target и прочие атрибуты <a>; при as="button" — type, disabled и т.д.

className, style, ref и остальные пропы ​

  • className — конкатенируется с классом блока, не затирая его;
  • style — мёрджится поверх CSS-переменных, сгенерированных из params;
  • ref — пробрасывается на корневой DOM-элемент;
  • все прочие пропы (onClick, aria-*, data-*, …) пробрасываются на корневой элемент как есть.

Суб-компоненты (@element) ​

Если @block содержит @element, они становятся вложенными компонентами через статические свойства корневого:

tsx
import { EButton } from './Button.ecss';

<EButton params={{ withIcon: true }}>
  <EButton.Icon>
    <svg>{/* … */}</svg>
  </EButton.Icon>
  <EButton.Text>Нажми меня</EButton.Text>
</EButton>;

Суб-компоненты поддерживают тот же проп as (по умолчанию <div>), но не принимают params.

Опции ​

Единственная опция фабрики — componentNamePrefix (префикс имени компонента, по умолчанию 'E'): reactAdapter({ componentNamePrefix: 'My' }) → MyButton. Подробнее — в обзоре адаптеров.

Поддержка версий React ​

Адаптер определяет мажорную версию React, установленного в проекте, и подстраивает генерируемый код:

  • React 19+ — ref передаётся как обычный проп;
  • React 18 — компонент оборачивается в forwardRef.

Версия читается из react/package.json относительно корня проекта и кешируется. Если React не удаётся разрешить, адаптер выводит предупреждение и использует React 19 как значение по умолчанию.

См. также ​