Строки: string schema

Схема string в Yup представляет собой базовый строительный блок для валидации текстовых значений в JavaScript-объектах. Она используется для описания правил, которым должна соответствовать строка: длина, формат, обязательность, преобразования и дополнительные пользовательские проверки.

Создание строки в Yup начинается с вызова фабрики string():

import * as Yup from 'yup';

const schema = Yup.string();

На этом этапе схема уже применима и считает валидными любые строковые значения, включая пустую строку и undefined, если не добавлены дополнительные ограничения.

Обязательность значения

Для указания обязательного поля используется метод required():

const schema = Yup.string().required();

Поведение required() заключается в том, что значения undefined, null и пустая строка считаются невалидными. При этом важно учитывать, что пустая строка трактуется как отсутствие значения, а не как корректный ввод.

Сообщение об ошибке может быть переопределено:

Yup.string().required('Поле обязательно для заполнения');

Метод notRequired() явно обозначает, что поле не является обязательным, даже если ранее в цепочке использовались ограничения.

Допустимость null и пустых значений

По умолчанию строковая схема не принимает null. Для разрешения этого значения используется nullable():

Yup.string().nullable();

Комбинация nullable() и required() требует аккуратного применения, поскольку required() по-прежнему будет отклонять null в большинстве сценариев.

Пустые строки при необходимости можно трактовать как отсутствие значения через кастомные преобразования.

Ограничения длины строки

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

Минимальная длина

Yup.string().min(5);

Значение должно содержать не менее 5 символов.

Максимальная длина

Yup.string().max(20);

Строка не может превышать 20 символов.

Точная длина

Yup.string().length(10);

Допустимы только строки длиной ровно 10 символов.

Каждый из методов поддерживает пользовательское сообщение:

Yup.string().min(5, 'Минимум 5 символов');

Проверка формата через регулярные выражения

Метод matches() позволяет задавать произвольные шаблоны:

Yup.string().matches(/^[a-zA-Z]+$/, 'Только латинские буквы');

Дополнительно можно управлять поведением при пустых значениях:

Yup.string().matches(/^[0-9]+$/, {
  message: 'Только цифры',
  excludeEmptyString: true
});

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

Предопределённые типы строк

Yup включает набор специализированных валидаторов:

Email

Yup.string().email('Некорректный email');

Проверка выполняется по стандартному шаблону email-адреса.

URL

Yup.string().url('Некорректный URL');

Поддерживает стандартные протоколы и структуру адреса.

UUID (через matches)

Хотя отдельного метода может не быть в базовой конфигурации, UUID часто реализуется через регулярные выражения:

Yup.string().matches(
  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
  'Некорректный UUID'
);

Преобразования строки

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

trim

Удаление пробелов по краям:

Yup.string().trim();

lowercase

Приведение к нижнему регистру:

Yup.string().lowercase();

uppercase

Приведение к верхнему регистру:

Yup.string().uppercase();

Преобразования применяются до выполнения валидации, что влияет на итоговое сравнение с правилами.

Значения по умолчанию

Метод default() задаёт значение, если поле отсутствует:

Yup.string().default('guest');

При валидации объектов это значение будет подставлено автоматически, если ключ не задан.

Пользовательские проверки через test

Метод test() используется для сложной логики, выходящей за рамки стандартных ограничений:

Yup.string().test(
  'no-spaces',
  'Строка не должна содержать пробелы',
  value => !value || !value.includes(' ')
);

Структура теста включает:

  • имя теста
  • сообщение об ошибке
  • функцию проверки

Функция может возвращать true/false или использовать асинхронную логику:

Yup.string().test(
  'check-exists',
  'Значение не существует',
  async value => {
    const exists = await apiCheck(value);
    return !exists;
  }
);

Условная валидация через when

Метод when() позволяет изменять правила в зависимости от других полей:

Yup.string().when('role', {
  is: 'admin',
  then: schema => schema.required(),
  otherwise: schema => schema.notRequired()
});

Также поддерживаются функции:

Yup.string().when('type', (type, schema) => {
  return type === 'strict'
    ? schema.min(10)
    : schema.min(3);
});

Композиция правил и порядок выполнения

Методы Yup применяются в цепочке, и порядок имеет значение:

Yup.string()
  .trim()
  .lowercase()
  .min(3)
  .max(10)
  .required();

Сначала выполняются преобразования, затем проверки ограничений, после чего применяется обязательность поля.

Поведение пустых значений

Пустые строки в Yup не всегда равнозначны отсутствию значения. В зависимости от схемы:

  • required() считает '' невалидным
  • notRequired() допускает ''
  • min() может интерпретировать '' как длину 0

Для унификации часто используется комбинация:

Yup.string()
  .trim()
  .transform(value => (value === '' ? undefined : value))
  .notRequired();

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

Каждый метод допускает передачу строки или объекта с параметрами:

Yup.string()
  .min(5, 'Слишком короткое значение')
  .max(10, 'Слишком длинное значение')
  .required('Поле обязательно');

Также можно использовать функции для динамических сообщений:

Yup.string().min(5, ({ min }) => `Минимум ${min} символов`);

Интеграция строковой схемы в объектные структуры

Строковые схемы часто используются внутри объектов:

const schema = Yup.object({
  username: Yup.string().required(),
  email: Yup.string().email().required(),
  bio: Yup.string().max(200)
});

Каждое поле валидируется независимо, но в рамках общей структуры объекта.

Особенности внутренней логики

Строковая схема в Yup работает как последовательный pipeline:

  1. преобразование (transform)
  2. приведение формата (trim, lowercase, uppercase)
  3. базовые проверки (required, nullable)
  4. ограничения (min, max, length)
  5. пользовательские проверки (test)

Такая структура обеспечивает предсказуемость результата даже при сложных цепочках правил.

Оглавление