Кастомизация внешнего вида панели администратора в Admiral

Время прочтения — 10 минут
Содержание
Гибкая настройка внешнего вида административных панелей – боль большинства разработчиков веб-приложений. Особенно если они поставляются как npm-пакеты. Часто такие решения оказываются слишком «жёсткими» в плане внешнего вида: на изменение стилей, адаптацию компонентов под фирменный стиль или просто внесение небольших правок уходит много сил, часов и нервов.
Создавая нашу библиотеку компонентов в Admiral, мы постарались сделать внешний вид панели максимально удобным для кастомизации. В этой статье мы подробно расскажем, как устроена система стилизации, какие подходы и инструменты поддерживают ее гибкость. Вы узнаете, как легко интегрировать собственные стили или переопределять существующие.

Изменение темы приложения

Темы в Admiral работают на основе Consta.design. Если не вдаваться в подробности, то все, что вам необходимо сделать – иметь в своем проекте файлы с переменными, которые задекларированы предопределенными наименованиями.
Директория со всеми необходимыми файлами уже создана и находится здесь. Вы можете менять значения переменных под цели вашего проекта.
Далее передаем ваши пресеты для темной и светлой тем в компонент Admin:

import themeLight from './config/theme/themeLight'
import themeDark from './config/theme/themeDark'


<Admin
    themePresets={{light: themeMaterialLight, dark: themeMaterialDark}}
>
    <Routes />
</Admin>
В верхней части файлов, где определяются цветовые переменные, располагаются базовые цвета — именно от них строится вся остальная палитра. Достаточно изменить значения этих базовых переменных, чтобы автоматически скорректировать все производные цвета темы.

--color-base-base: #171a22;
   --color-base-essential: #fff;
   --color-base-project: #472f92;
   --color-base-phantom: #bb2121;
   --color-base-path: #5856d6;
   --color-base-system: #ced8de;
   --color-base-success: #62bb46;
   --color-base-alert: #eb5757;
   --color-base-warning: #f38b00;
   --color-base-caution: #f2c94c;
   --color-base-normal: #56b9f2;
   --color-base-critical: #33000f;

Кастомизация стилей компонентов

При разработке компонентов нашей библиотеки была заложена логика модификации стилей с помощью CSS. Так вы можете открыть интересующий вас компонент в репозитории, например Card и посмотреть, какие переменные необходимо добавить в ваш проект, чтобы изменить определенные стили.
Card.module.scss

.card {
   width: var(--card-width, 100%);
   padding: var(--card-pt, var(--space-3xl)) var(--card-pr, var(--space-3xl))
       var(--card-pb, var(--space-3xl)) var(--card-pl, var(--space-3xl));


   border-radius: var(--card-radius, var(--radius-m));
   background: var(--card-bg, var(--color-control-bg-default));
   color: var(--card-color, var(--color-control-typo-default));
   box-shadow: var(--shadow-group);
}
На примере выше, чтобы изменить задний фон компонента Card, достаточно создать CSS-переменную –card-bg, а для изменения скругления границ – переменную –card-radius.
Существует 3 способа добавить эти переменные:
  1. Глобально
  2. Постранично
  3. Локально
Кратко рассмотрим особенности каждого из них.

Глобальное добавление переменных

Если стиль нужно применить ко всем компонентам Card в проекте, создайте переменные в глобальном файле стилей и примените их к псевдоклассу :root. Если у вас уже есть файл с глобальными стилями, создайте переменные в начале файла. При отсутствии файла, создайте его в удобном для вас месте и импортируйте в main.tsx следующим образом:
main.tsx

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'
import './global.css'


ReactDOM.render(
   <React.StrictMode>
       <App />
   </React.StrictMode>,
   document.getElementById('root'),
)
global.css

:root {
   --card-bg: red;
   --card-radius: 8px;
}

Постраничное создание переменных

Для переопределения стилей в рамках определенных страниц, оборачиваем их в CSS-класс, которому будут заданы переменные.
Создаём отдельный компонент для страницы.
index.tsx

import React from 'react'
import { CRUD } from '@/src/crud/users'
import styles from './UsersPage.module.scss'


const UsersPage = () => (
   <div className={styles.users_page}>
       <CRUD.IndexPage />
   </div>
)


export default UsersPage
UsersPage.module.scss
Создаём css-файл для страницы.

.users_page {
   --card-bg: blue;
   --card-radius: 30px;
}
Импортируем компонент страницы в необходимую директорию каталога pages для создания роутинга.
pages/users/index.tsx

import UsersPage from '@/src/components/pages/UsersPage'


export default UsersPage

Локальное создание переменных

В случае, если необходимо переопределить стили конкретных компонентов, оборачиваем их в CSS-класс, которому будут заданы переменные.
Например, когда в верхнем контенте страницы CRUD есть компонент Card и мы хотим изменить его стили, можно сделать так:
index.tsx

export const CRUD = createCRUD({
   ...config,
   topContent: (
       <div className={styles.topContent}>
           <Card>
               <h2>Hello!</h2>
           </Card>
       </div>
   ),
})
css-file

.topContent {
   --card-bg: green;
   --card-radius: 8px;
}
✍ Даже если переменные уже заданы в глобальном файле, локальные переменные будут иметь наибольший приоритет.
Пример ниже показывает, как применяется локальная и постраничная модификация, где локальные переменные переопределяют постраничные.
Помимо темы и кастомизации с изменением CSS-переменных, в большинство компонентов можно передавать className. С его помощью вы будете менять тот или иной компонент. Так кастомизировать вашу панель администратора становится намного проще, если вы используете Admiral.
Остались вопросы по кастомизации внешнего вида панели администратора в Admiral? Мы здесь, чтобы помочь!
📩 Написать нам
Читайте также