Стилизация

Выберите из различных предварительно стилизованных тем или настройте свою собственную в FishtVue.

Архитектура

FishtVue - это библиотека, не зависящая от дизайна, поэтому, в отличие от некоторых других UI-библиотек, она не навязывает определенный стиль, такой как Material Design. Стилизация отделена от компонентов с помощью тем. Тема состоит из двух частей: базы и пресета. База - это стилевые правила с CSS-переменными в качестве заполнителей, тогда как пресет - это набор дизайн-токенов для заполнения базы, сопоставляя токены с CSS-переменными. База может быть настроена с разными пресетами.

Дизайн-токены

Основой архитектуры стилизованного режима является концепция, называемая дизайн-токеном. Пресет определяет конфигурацию токенов в трех уровнях: примитивные, семантические и компонентные.

Примитивные токены

Примитивные токены не имеют контекста. Цветовая палитра, такая как blue-50 до blue-900, является хорошим примером примитивного токена. Токен с именем blue-500 может использоваться как основной цвет или фон сообщения, но само по себе имя токена не указывает на контекст. Обычно они используются семантическими токенами.

Семантические токены

Семантические токены определяют контент, и их имена указывают, где они используются. Хорошо известным примером семантического токена является primary.color. Семантические токены сопоставляются с примитивными токенами или другими семантическими токенами. Группа токенов colorScheme - это специальная переменная для определения токенов на основе активной цветовой схемы в приложении, позволяя использовать разные токены в зависимости от цветовой схемы, например, темного режима.

Токены компонентов

Токены компонентов - это изолированные токены для каждого компонента, такие как inputtext.background или button.color, которые сопоставляются с семантическими токенами. Например, токен компонента button.background сопоставляется с семантическим токеном primary.color, который сопоставляется с примитивным токеном green.500.

Лучшие практики

Используйте примитивные токены при определении основной цветовой палитры.
Используйте семантические токены для указания общих элементов дизайна, таких как кольцо фокуса, основные цвета и поверхности.
Используйте токены компонентов при настройке конкретного компонента.

Определяя свои собственные дизайн-токены как пользовательский пресет, вы сможете определить свой собственный стиль, не касаясь CSS. Переопределение компонентов FishtVue с помощью классов стилей не является лучшей практикой и должно быть последним средством; дизайн-токены - это рекомендуемый подход.

Опции темы

Свойство optionsTheme позволяет вам настроить глобальное поведение темизации в FishtVue. Оно поддерживает установку имени темы, пользовательских префиксов CSS-переменных, селекторов темного/светлого режима и расширенных опций, таких как CSS-слои и контроль минификации.

Базовое использование

main.ts

import FishtVue from 'fishtvue/config';

app.use(FishtVue, {
    optionsTheme: {
        nameTheme: "Aurora",
        prefix: "fishtvue",
        layers: "layer",
        isNotMinifyCSS: true,
        lightModeSelector: "html.light",
        darkModeSelector: "html.dark",
    },
});

nameTheme

Опция nameTheme позволяет вам выбрать, какой встроенный пресет темы использовать. Вы можете выбрать из "Aurora", "Harmony" или "Sapphire", в зависимости от визуального стиля, который вы хотите для своего приложения. По умолчанию используется "Aurora". Эта настройка особенно полезна, если вы планируете переключаться между разными дизайн-системами или нуждаетесь в согласованной теме для нескольких проектов.

main.ts

optionsTheme: {
    nameTheme: "Aurora"
}

prefix

Опция prefix позволяет вам определить пользовательский префикс для всех CSS-переменных, сгенерированных темой. По умолчанию он установлен на "fishtvue".

main.ts

optionsTheme: {
    prefix: "fishtvue"
}

lightModeSelector

Опция lightModeSelector позволяет вам установить пользовательский CSS-селектор для управления тем, когда должны применяться стили светлого режима. По умолчанию светлый режим всегда активен (поэтому значение - просто пустая строка). Эта опция становится полезной, если вы вручную переключаетесь между светлым и темным режимами и хотите иметь больше контроля над тем, как применяется светлый режим.

main.ts

optionsTheme: {
    lightModeSelector: "html.light"
}

darkModeSelector

Опция darkModeSelector позволяет вам указать CSS-селектор, который будет активировать стили темного режима. Например, вы можете использовать "html.dark" или ".dark-mode", если вы вручную переключаете темный режим в своем приложении. Если вы ничего не установите, будет использоваться предпочтение системы по умолчанию. Вы также можете полностью отключить темный режим, установив эту опцию в false.

main.ts

optionsTheme: {
    darkModeSelector: "html.dark"
}

Пример: Переключение темного режима

index.html


<button @click="toggleDarkMode">Переключить темный режим</button>

script.js

function toggleDarkMode() {
    document.documentElement.classList.toggle('dark');
}

Чтобы полностью отключить поддержку темного режима:

optionsTheme: {
    darkModeSelector: false
}

layers

Опция layers позволяет вам обернуть сгенерированный CSS в пользовательский CSS-каскадный слой. Это помогает управлять приоритетом стилей и упрощает интеграцию с другими фреймворками. Вы можете использовать встроенный слой "fishtvue" или определить свой собственный. По умолчанию слой не применяется, если вы явно не установите эту опцию.

optionsTheme: {
    layers: "fishtvue"
}

Или определите пользовательский порядок каскада:

optionsTheme: {
    layers: "base, fishtvue, overrides"
}

isNotMinifyCSS

Опция isNotMinifyCSS контролирует, должен ли сгенерированный CSS быть минифицирован. По умолчанию она установлена в false, что означает, что CSS будет минифицирован для лучшей производительности. Если вы установите ее в true, минификация будет отключена, что может сделать вывод более удобным для чтения и отладки во время разработки.

optionsTheme: {
    isNotMinifyCSS: true
}

Встроенные пресеты

FishtVue включает несколько пресетов тем, разработанных для различных философий дизайна:

Aurora – Пресет по умолчанию, яркий и современный
Harmony – Минималистичный и мягкий
Sapphire – Дизайн, ориентированный на предприятие

Эти пресеты могут быть расширены или использованы в качестве справочников для создания вашей собственной пользовательской дизайн-системы.

Советы

Сочетайте prefix и layers для правильного пространства имен и организации вашего CSS.
Используйте darkModeSelector и lightModeSelector для поддержки тем, управляемых пользователем.
Отключите isNotMinifyCSS в продакшене для оптимальной производительности.

Утилиты

usePreset

Полностью заменяет текущие пресеты. Распространенный случай использования - динамическое изменение пресета во время выполнения.

import {usePreset} from '@fishtvue/themes';

const onButtonClick
()
{
    usePreset(MyPreset);
}

updatePreset

Объединяет предоставленные токены с текущим пресетом. Примером может быть динамическое изменение основной цветовой палитры.

import {updatePreset} from '@fishtvue/themes';

const changePrimaryColor
()
{
    updatePreset({
        semantic: {
            primary: {
                50: '{indigo.50}',
                100: '{indigo.100}',
                200: '{indigo.200}',
                300: '{indigo.300}',
                400: '{indigo.400}',
                500: '{indigo.500}',
                600: '{indigo.600}',
                700: '{indigo.700}',
                800: '{indigo.800}',
                900: '{indigo.900}',
                950: '{indigo.950}'
            }
        }
    });
}

updatePrimaryPalette

Обновляет основные цвета. Это сокращение для выполнения того же обновления с использованием updatePreset.

import {updatePrimaryPalette} from '@fishtvue/themes';

const changePrimaryColor
()
{
    updatePrimaryPalette({
        50: '{indigo.50}',
        100: '{indigo.100}',
        200: '{indigo.200}',
        300: '{indigo.300}',
        400: '{indigo.400}',
        500: '{indigo.500}',
        600: '{indigo.600}',
        700: '{indigo.700}',
        800: '{indigo.800}',
        900: '{indigo.900}',
        950: '{indigo.950}'
    });
}

updateSurfacePalette

Обновляет цвета поверхности. Это сокращение для выполнения того же обновления с использованием updatePreset.

import {updateSurfacePalette} from '@fishtvue/themes';

const changeSurfaces
()
{
    // Изменяет поверхности как в светлом, так и в темном режиме
    updateSurfacePalette({
        50: '{zinc.50}',
        // ...
        950: '{zinc.950}'
    });
}

const changeLightSurfaces
()
{
    // Изменяет поверхности только в светлом режиме
    updateSurfacePalette({
        light: {
            50: '{zinc.50}',
            // ...
            950: '{zinc.950}'
        }
    });
}

const changeDarkSurfaces
()
{
    // Изменяет поверхности только в темном режиме
    updateSurfacePalette({
        dark: {
            50: '{zinc.50}',
            // ...
            950: '{zinc.950}'
        }
    });
}

$dt

Функция $dt возвращает информацию о токене, такую как полный путь и значение. Это полезно, если вам нужно программно получить доступ к токенам.

import {$dt} from '@fishtvue/themes';

const duration = $dt('transition.duration');
/*
    duration: {
        name: '--transition-duration',
        variable: 'var(--p-transition-duration)',
        value: '0.2s'
    }
*/

const primaryColor = $dt('primary.color');
/*
    primaryColor: {
        name: '--primary-color',
        variable: 'var(--p-primary-color)',
        value: {
            light: {
                value: '#10b981',
                paths: {
                    name: 'semantic.primary.color',
                    binding: {
                        name: 'primitive.emerald.500'
                    }
                }
            }
        },
        dark: {
            value: '#34d399',
            paths: {
                name: 'semantic.primary.color',
                binding: {
                    name: 'primitive.emerald.400'
                }
            }
        }
    }
}
*/

palette

Возвращает оттенки и тона заданного цвета от 50 до 950 в виде объекта.

import {palette} from '@fishtvue/themes';

// Пользовательский цвет
const values1 = palette('#10b981');

// Копирование существующего набора токенов
const primaryColor = palette('{blue}');