@IsHexColor

Декоратор @IsHexColor в библиотеке Class-validator предназначен для валидации строковых значений, представляющих цвет в шестнадцатеричном формате. Он используется в классах DTO (Data Transfer Object) и позволяет гарантировать, что входные данные соответствуют стандарту HEX-цветов, применяемых в CSS, графических интерфейсах и конфигурационных схемах.

Основная задача декоратора — проверка строки на соответствие формату:

  • #RRGGBB
  • #RGB
  • и в некоторых конфигурациях расширенные варианты с альфа-каналом (#RRGGBBAA, #RGBA), в зависимости от параметров валидации и версии реализации.

Базовое применение

Декоратор применяется к строковому свойству класса и не требует дополнительных параметров в простейшем случае.

import { IsHexColor } from 'class-validator';

class ThemeDto {
  @IsHexColor()
  primaryColor: string;
}

В этом примере свойство primaryColor должно содержать корректный HEX-код цвета, например:

  • #ffffff
  • #000
  • #1a2b3c

Любое значение, не соответствующее формату, будет считаться ошибочным.

Поддерживаемые форматы HEX

Валидация охватывает несколько распространённых форматов записи:

1. Полный шестнадцатеричный формат

#RRGGBB

Пример:

  • #ff0000
  • #00ff00
  • #0000ff

Каждая пара символов отвечает за интенсивность красного, зелёного и синего каналов.

2. Сокращённый формат

#RGB

Пример:

  • #f00
  • #0f0
  • #00f

Каждый символ автоматически интерпретируется как дублирующийся (#f00 → #ff0000).

3. Формат с альфа-каналом (в зависимости от конфигурации)

#RRGGBBAA
#RGBA

Пример:

  • #ff000080
  • #0f08

Альфа-канал определяет прозрачность цвета.

Внутренняя логика проверки

@IsHexColor использует регулярное выражение для проверки строки. Общая логика сводится к следующим шагам:

  1. Проверка наличия символа # в начале строки.

  2. Проверка длины строки:

    • 4 символа (#RGB)
    • 7 символов (#RRGGBB)
    • 5 или 9 символов при поддержке альфа-канала

  3. Проверка соответствия допустимым символам:

    • 0–9
    • a–f
    • A–F

Любые отклонения приводят к ошибке валидации.

Использование в составе сложных DTO

В реальных приложениях цветовые значения часто используются в сочетании с другими параметрами конфигурации интерфейса.

import { IsString, IsHexColor, IsOptional } from 'class-validator';

class ButtonStyleDto {
  @IsHexColor()
  backgroundColor: string;

  @IsHexColor()
  textColor: string;

  @IsOptional()
  @IsHexColor()
  borderColor?: string;
}

В этом случае валидируются сразу несколько свойств, каждое из которых должно содержать корректный HEX-код.

Поведение при ошибках

При несоответствии формату Class-validator формирует объект ошибок, содержащий:

  • имя свойства
  • переданное значение
  • описание нарушения

Пример результата:

[
  {
    "property": "primaryColor",
    "value": "blue",
    "constraints": {
      "isHexColor": "primaryColor must be a hex color"
    }
  }
]

Сообщение по умолчанию может быть переопределено через параметры декоратора.

Кастомизация сообщения об ошибке

Хотя @IsHexColor не предоставляет большого набора опций, стандартный механизм Class-validator позволяет задать собственное сообщение.

import { IsHexColor } from 'class-validator';

class ThemeDto {
  @IsHexColor({ message: 'Неверный формат HEX-цвета' })
  primaryColor: string;
}

Это особенно полезно при построении пользовательских API, где требуется локализация или унифицированные сообщения об ошибках.

Сочетание с другими валидаторами

@IsHexColor часто используется совместно с другими декораторами для усиления проверки входных данных.

Проверка обязательности и формата

import { IsNotEmpty, IsHexColor } from 'class-validator';

class ColorDto {
  @IsNotEmpty()
  @IsHexColor()
  value: string;
}

Здесь сначала проверяется наличие значения, затем его корректность.

Особенности и ограничения

Несмотря на универсальность, декоратор имеет ряд особенностей:

  • Проверяет только строку, без преобразования типов
  • Не интерпретирует цвет, а лишь проверяет формат
  • Не выполняет нормализацию регистра
  • Не валидирует цветовую модель (RGB/CMYK и т.д.), только HEX

Это означает, что значение #GGGGGG будет отклонено, несмотря на правильную длину и структуру, так как символы не входят в допустимый диапазон шестнадцатеричной системы.

Практические сценарии использования

Конфигурация UI

В системах настройки интерфейса HEX-цвета часто приходят от клиента:

class UiConfigDto {
  @IsHexColor()
  accentColor: string;

  @IsHexColor()
  background: string;
}

Темизация приложений

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

class ThemeDto {
  @IsHexColor()
  primary: string;

  @IsHexColor()
  secondary: string;

  @IsHexColor()
  danger: string;
}

Хранение дизайн-токенов

HEX-значения применяются как часть дизайн-систем:

class DesignTokenDto {
  @IsHexColor()
  brandColor: string;

  @IsHexColor()
  hoverColor: string;
}

Поведение при работе с API

При использовании Class-validator в связке с NestJS или аналогичными фреймворками, проверка @IsHexColor происходит на этапе валидационного пайплайна. Это позволяет отсечь некорректные запросы до попадания в бизнес-логику.

Типичный сценарий:

  1. Получение JSON-запроса
  2. Преобразование в DTO
  3. Валидация всех полей
  4. Возврат ошибки при несоответствии HEX-формату

Сравнение с ручной проверкой

Использование @IsHexColor заменяет необходимость ручного написания регулярных выражений:

const regex = /^#([0-9a-fA-F]{3}){1,2}$/;

или расширенного варианта:

const regex = /^#([0-9a-fA-F]{3,4}){1,2}$/;

Декоратор инкапсулирует эту логику и снижает вероятность ошибок при повторном использовании.

Оглавление