Примеры и компоненты проекта

Эта страница объясняет, как перенести пример из справочника в проект и когда вместо набора утилит нужен собственный компонент проекта.

Как работать с примерами

Пример на странице компонента показывает настоящий вид и публичный код одного сценария. Эта глава описывает, как перенести пример в проект, не потеряв структуру. Результат и код во вкладках «HTML» и «JavaScript» относятся к одному и тому же.

Как перенести пример в проект:

1. Откройте страницу компонента в справочнике (/ru/components/…).
2. Посмотрите результат во вкладке «Пример».
3. Скопируйте код из вкладки HTML или JavaScript.
4. Замените демонстрационный текст и данные своими.
5. Проверьте клавиатуру, фокус, узкий экран и обе темы — с той версией Framework, которая закреплена в проекте.

Правила:

• Берите только публичные классы и атрибуты — те, что перечислены на странице компонента. Служебные обёртки вокруг примера принадлежат сайту документации и могут меняться.
• Сохраняйте утилиты на частях компонента (Анатомия: корень, части, модификаторы, состояния): это часть структуры.
• Не урезайте структуру. Пропущенная часть ломает вид или доступность: например, без sf-input-field поле теряет границу и кольцо фокуса, а без sf-input-text доступным именем поля станет весь текст оболочки — вместе с подсказкой и звёздочкой.
• Пример не доказывает совместимость. Он работает с той версией, которую показывает сайт; проверяйте с версией своего проекта.

Смотрите также: Анатомия: корень, части, модификаторы, состояния — анатомия компонента; Доступность: что компонент даёт и что остаётся за автором — доступность.

Компонент проекта или утилиты

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

Достаточно утилит, когда фрагмент — раскладка или единичная поправка: карточка из стандартных частей, отступ между полями, выравнивание строки. Утилита поверх компонента допустима для единичной корректировки снаружи (отступ, ширина, место в сетке).

Нужен компонент проекта, когда:

• одна и та же структура повторяется в нескольких местах проекта;
• у неё есть варианты или состояния, которые должны выглядеть одинаково;
• набор утилит на элементе стал длинным и копируется целиком.

Сначала поищите в Framework. Если похожий компонент есть, используйте его модификаторы. Если не хватает варианта, который нужен не только вам, — это задача для Framework, а не повод переопределять его классы в проекте.

Правила компонента проекта:

• Своё имя. Префикс sf- носят компоненты Framework и пакетов компонентов; компонент проекта называется своим префиксом, как и проектные Smart-теги.
• Та же грамматика: корень, части через дефис, модификаторы через два дефиса, состояния короткими словами.
• Только токены. Цвета — ролями (--sf-primary, --sf-outline, --sf-surface-0), размеры — ступенями лестницы, стороны — логическими свойствами.
• Готовые компоненты внутри — целиком. Кнопка внутри карточки проекта остаётся .sf-button со своими модификаторами; не перерисовывайте её своими правилами.
• Состояния по образцу Состояния: нативные признаки, кольцо фокуса, недоступность без реакций, сообщение об ошибке.
• Высота — парой, граница контрола — --sf-outline.
• Измерение. Проверьте высоту рядом с полем и кнопкой той же ступени, обе темы, обе ширины.

Изменить вид компонента Framework можно модификаторами, общими классами (spacing-*, radius-*) и общими токенами; глубокий вид Smart-компонента — его внешним шаблоном (см. Как менять дизайн).

Смотрите также: Утилиты и компоненты: где проходит граница — граница между утилитами и компонентами; Состояния — состояния; Поверхности, высота и границы — поверхности и границы.

Смотрите также

• Как менять дизайн — Как менять дизайн.
• Токены, роли цвета и темы — Дизайн-токены, Цветовые роли и Темы; лестница размеров, отступы, фокус — Одна лестница размеров, Пространство и Фокус.
• Утилиты, которые раскладывают части компонента и ставятся поверх него, — Раскладка и Утилиты и компоненты: где проходит граница.
• Loader и поставка — Как работает Loader; совместимость и обновление — Жизненный цикл изменений.
• Поведение, события и состояние поверх тех же классов — Smart-компоненты.
• Сборка страниц и блоков из компонентов — Макеты и композиция (см. Построение макета).
• Проверки, которые держат эти правила (граница контрола, пара высоты, геометрия, фокус), — Принципы качества для всего Framework и Как Framework проверяет себя.