Базовая структура Carbon-компонента

Carbon Components Svelte — это обертка для официальной библиотеки компонентов IBM Carbon Design System, адаптированная под фреймворк Svelte. Каждый компонент строится вокруг реактивной модели Svelte и обеспечивает готовый пользовательский интерфейс с соблюдением рекомендаций дизайна.

Импорт и подключение компонентов

Компонент Carbon подключается через модульный импорт:

<script>
  import { Button, TextInput } from 'carbon-components-svelte';
</script>
  • Button — кнопка с поддержкой разных стилей и размеров.
  • TextInput — поле ввода с опциями валидации и состояния (error, warning, success).

Важно: все компоненты Carbon уже содержат встроенные стили. Для корректного отображения необходимо подключить глобальный CSS:

import 'carbon-components-svelte/css/all.css';

Основная структура компонента

Каждый Carbon-компонент имеет три ключевых слоя:

  1. Контейнер Svelte — <script> и <style> для логики и локальных стилей.
  2. JSX-подобный шаблон — разметка компонента с использованием <ComponentName {...props} />.
  3. Пропсы и события — свойства для настройки внешнего вида и поведения, события для реакции на действия пользователя.

Пример базового компонента:

<script>
  import { Button, TextInput } from 'carbon-components-svelte';
  
  let inputValue = '';
  
  function handleClick() {
    console.log('Нажата кнопка');
  }
</script>

<TextInput
  bind:value={inputValue}
  labelText="Введите текст"
  placeholder="Текст"
/>

<Button on:click={handleClick} kind="primary">
  Отправить
</Button>

Ключевые моменты:

  • bind:value связывает внутреннее состояние Svelte с компонентом Carbon.
  • on:click — стандартная Svelte-событийная привязка.
  • kind="primary" — настройка внешнего вида компонента, поддерживаются варианты secondary, tertiary, ghost.

Пропсы и их типизация

Carbon Components Svelte поддерживает полную типизацию для TypeScript и автодополнение в редакторах:

<Button
  kind="secondary"
  size="sm"
  disabled={false}
  tooltipText="Нажмите кнопку"
/>

Основные пропсы для большинства компонентов:

  • kind — визуальный стиль (primary, secondary, danger, ghost).
  • size — размер (sm, md, lg).
  • disabled — блокировка компонента.
  • labelText / placeholder — текстовые метки.
  • tooltipText — описание, показываемое при наведении.

Использование правильного сочетания пропсов обеспечивает соответствие принципам Carbon Design System.

Работа с событиями

Каждый компонент поддерживает стандартные события Svelte, а также собственные события Carbon. Примеры:

<Button on:click={() => console.log('Клик')}>
  Кнопка
</Button>

<TextInput
  bind:value={inputValue}
  on:input={(e) => console.log('Изменение:', e.detail.value)}
/>
  • on:click — обычное событие кнопки.
  • on:input — событие изменения значения с объектом detail.value, содержащим новый текст.

Carbon-компоненты поддерживают также события focus, blur и пользовательские события специфичных компонентов (например, on:change у Select).

Компоновка и вложенность

Компоненты можно комбинировать для построения сложных интерфейсов. Например, форма с несколькими полями:

<form>
  <TextInput labelText="Имя" bind:value={name} />
  <TextInput labelText="Email" bind:value={email} type="email" />
  <Button kind="primary" on:click={submitForm}>Отправить</Button>
</form>

Рекомендации по структуре:

  • Каждый компонент оборачивать в логически отдельный блок.
  • Использовать реактивные переменные Svelte для хранения состояния.
  • Следовать соглашениям Carbon по отступам и сетке, чтобы визуальная согласованность соблюдалась без дополнительного CSS.

Локальная кастомизация стилей

Хотя Carbon предоставляет готовый CSS, локальные изменения возможны через Svelte <style> и классы:

<style>
  .custom-button {
    margin-top: 1rem;
    background-color: #0f62fe;
  }
</style>

<Button class="custom-button" kind="primary">
  Кастомная кнопка
</Button>
  • class добавляется к стандартным классам Carbon.
  • Не рекомендуется полностью переопределять базовые стили, чтобы сохранить консистентность интерфейса.

Резюме структуры

  • Импорт компонентов и CSS.
  • Пропсы для настройки внешнего вида и поведения.
  • События для реагирования на действия пользователя.
  • Композиция компонентов для сложного интерфейса.
  • Стилизация через классы и локальные стили без нарушения стандартной темы.

Эта структура позволяет строить интерфейсы, полностью соответствующие Carbon Design System, сохраняя преимущества реактивной модели Svelte.

Оглавление