yandex

ACF Pro: кастомные поля

Кастомные поля, типы записей, таксономии и блоки

VS Code с кодом WordPress и ACF PRO на ноутбуке (стиль лофт

Числовые поля в ACF PRO: работаем с Number и Range — настройка диапазонов, валидация и практические кейсы

85
0
VS Code с кодом WordPress и ACF PRO на ноутбуке (стиль лофт)

После текстовых полей числовые — второй по частоте кластер в практике: счётчики, рейтинги, цены, приоритеты, время чтения. Оба поля — Number и Range — хранят чистое число, но решают разные задачи: Number — про точный ввод значения, Range — про выбор значения из заданного диапазона. В этой статье разберём настройки обоих полей, безопасный вывод, работу с запросами WordPress и главное — критерии выбора: когда какое поле применять и почему.

Number или Range: как выбрать поле

Оба поля хранят число (int или float) и оба поддерживают ограничения min/max и шаг. Разница — в интерфейсе ввода и, как следствие, в типе задач.

КритерийNumberRange
Как вводитсяТочное значение с клавиатурыПолзунок в границах min/max
Типовое применениеПросмотры, цена, артикул-номер, внешний ID, порядковый номерСложность, приоритет вывода, время чтения, коэффициент
Диапазон значенийЛюбой, хоть 1–100 000Заранее заданный и обычно небольшой
Точность дробныхЛюбая (0.01 и точнее)Ограничена шагом, тонкую настройку ползунком делать неудобно
Кто вводитРедактор знает точное числоРедактор выбирает «на глаз», ползунок снижает ошибки ввода

Практические правила выбора:

  • Значение вводится редко и точно — Number. ID внешнего сервиса, фиксированный коэффициент, цена из прайса, счётчик, который обновляется кодом, а не редактором.
  • Значение — оценка по шкале — Range. «Сложность 1–5», «приоритет вывода 1–10», «время чтения 1–60 минут». Ползунок сразу показывает диапазон и текущее положение, редактору не нужно помнить границы.
  • Большие числа — Number. Ползунок на диапазоне 1–100 000 бесполезен: шаг в 1 деление неощутим.
  • Ввод для неспециалиста — Range. Если редактор — не технический человек, ползунок с единицами измерения («баллов», «минут», «%») проще и безопаснее, чем свободный ввод цифр.

Короткая проверка: если редактор должен ввести конкретное число — Number; если выбрать положение на шкале — Range. Числовая природа у обоих одинаковая, поэтому всё, что ниже про вывод, запросы и валидацию, работает для обоих полей.

Поле Number: что это и зачем нужно

Number в ACF — инструмент для ввода и хранения числовых значений: от простых количественных показателей до метрик для расчётов. Его сила — строгая валидация: в поле нельзя сохранить текст, только число.

Типовые кейсы использования:

  • Счётчик просмотров статьи — точное число без риска получить текст вместо цифры.
  • Рейтинг публикации (1–5) — оценка, которую потом выводят звёздами или в микроразметке.
  • Цена товара или услуги — чистое число для расчётов и фильтрации.
  • Количество оставшихся мест (например, в мастер-классе) — контроль доступности.
  • Порядок сортировки — приоритет вывода постов в кастомной сетке.

Преимущества поля:

  • Валидация на уровне базы: в поле нельзя сохранить текст — только число.
  • Гибкие ограничения: мин/макс, шаг.
  • Простота интеграции: работает с get_field(), REST API, шаблонами.
  • Совместимость с сортировкой и фильтрацией: числа легко использовать в WP_Query через meta_query.

Настройки поля Number

  • Field Name — машинное имя латиницей без пробелов, например post_views.
  • Label — понятное название для редактора: «Просмотры статьи».
  • Minimum — минимальное значение (например, 0).
  • Maximum — максимальное значение (например, 99 999).
  • Step — шаг: 1 для целых чисел, 0.5 для половинчатых оценок.
  • Instructions — подсказка редактору: что хранится в поле и в каком формате.
  • Required — включите, если поле обязательно.

Практический пример: счётчик просмотров статьи

Задача — показать количество просмотров под заголовком статьи. Значение обновляется отдельно (плагином или своим кодом), шаблон только читает его. Имя поля: post_views.

<?php $views = get_field('post_views') ?>
<?php if(!empty($views)): ?>
    <span class="post-views">
        Просмотров: <?php echo absint($views) ?>
    </span>
<?php endif ?>
Разбор по строкам:
  1. Значение записываем в переменную $views и проверяем на пустоту — чтобы не выводить блок «Просмотров: » при незаполненном поле.
  2. absint($views) приводит значение к неотрицательному целому числу: даже если в базу попало что-то неожиданное, на страницу выйдет корректное число.

Функции для приведения типа выбираются по контексту: absint() — для целых неотрицательных значений (счётчики, количество), floatval() — для дробных (цены, коэффициенты). Если значение попадает в атрибут или микроразметку, используйте esc_attr()/esc_js(), как в текстовых полях.

Три оговорки по остальным сценариям из практики:

  • Цена. Число из поля форматируйте на уровне шаблона — number_format($price, 2, '.', '') плюс символ валюты. Хранить в поле строку «1 200 ₽» нельзя: это уже текст, и фильтрация по нему сломается. Валюту выносите в отдельное поле-выбор, а не в цену.
  • Сортировка по полю. В WP_Query используйте 'orderby' => 'meta_value_num' и 'order' => 'DESC' — тогда посты выстроятся по числу (приоритет, просмотры). Классическая ошибка — meta_value без _num: сортировка становится лексикографической, и «10» окажется меньше «2».
  • Фильтрация по диапазону. В meta_query для сравнения BETWEEN обязательно указывайте 'type' => 'NUMERIC' — иначе WordPress сравнивает значения как строки, и границы диапазона работают непредсказуемо.

Поле Range: что это и зачем нужно

Range в ACF — поле-ползунок: значение задаётся визуально в границах min/max. Оно выгодно там, где важна наглядность и ограничение диапазона: снижает ошибки ввода, даёт понятный интерфейс и легко интегрируется в шаблоны.

Типовые кейсы использования:

  • Оценка сложности материала (1–5) — редактор выставляет уровень ползунком, на фронтенде выводится бейдж «Легко / Средне / Сложно».
  • Порог срабатывания логики — например, «показывать блок, если цена больше X»: значение хранится как число, но задаётся через удобный интерфейс.
  • Рекомендуемое время чтения (минуты) — ползунок от 1 до 60, значение используется в бейдже «~15 минут».
  • Коэффициент для расчётов (скидка, множитель) — чистое число в базе, удобный ввод в админке.

Преимущества поля:

  • Наглядность: ползунок сразу показывает диапазон и текущее значение.
  • Жёсткие границы: невозможно задать значение вне min/max.
  • Валидация на уровне поля: в базу попадает только число.
  • Единицы измерения: в настройках можно указать «баллов», «минут», «%» — это улучшает UX редактора.

Настройки поля Range

  • Field Name — машинное имя латиницей без пробелов, например article_difficulty.
  • Label — название для редактора: «Сложность статьи».
  • Minimum — например, 1.
  • Maximum — например, 5.
  • Step — 1 для целых значений, 0.5 для половинных.
  • Unit — единицы измерения (опционально): «баллов» — отображаются рядом с ползунком.
  • Instructions — подсказка редактору: что означает шкала (например, «1 — для начинающих, 5 — для опытных разработчиков»).

Практический пример: бейдж «Сложность» на карточке статьи

Задача — показать уровень сложности в виде текста и цвета класса. Имя поля: article_difficulty.

<?php $difficulty = get_field('article_difficulty') ?>
<?php if(is_numeric($difficulty)): ?>
    <?php
    if($difficulty <= 2) {
        $badge_class = 'easy';
        $badge_text  = 'Легко';
    } elseif($difficulty <= 4) {
        $badge_class = 'medium';
        $badge_text  = 'Средне';
    } else {
        $badge_class = 'hard';
        $badge_text  = 'Сложно';
    }
    ?>
    <span class="difficulty-badge <?php echo esc_attr($badge_class) ?>">
        <?php echo esc_html($badge_text) ?> (<?php echo absint($difficulty) ?> баллов)
    </span>
<?php endif ?>
Разбор по строкам:
  1. is_numeric($difficulty) — проверка типа даже для Range: это защита от неожиданных данных (пустого значения, строки после миграции).
  2. Условия превращают число в осмысленный класс и текст: значениям 1–2 соответствует «Легко», 3–4 — «Средне», 5 — «Сложно». Границы групп легко сдвинуть под вашу шкалу.
  3. В атрибут класса уходит esc_attr(), в текст — esc_html(), в числовой вывод — absint(): как и для текстовых полей, экранирование выбирается под контекст.

Тот же принцип масштабируется на другие кейсы: для времени чтения достаточно absint($time) в бейдже «~12 минут», для пороговой логики — обычное сравнение if($price > $threshold), для динамического CSS (ширина прогресс-бара) — приведение значения шкалы к процентам через min()/max(). Если нужно сгруппировать записи по диапазонам («Лёгкие / Средние / Сложные» на одной странице), это делается серией запросов WP_Query с meta_query и compare => BETWEEN — по одной на каждую группу, с 'type' => 'NUMERIC'.

Важные нюансы и лучшие практики

Общие для обоих полей:

  • Всегда валидируйте значение: is_numeric() перед использованием, absint() для целых, floatval() для дробных — даже если поле настроено корректно, данные в базе могут прийти из миграции или импорта.
  • Не доверяйте вводу без ограничений: задавайте min/max и step в настройках поля — это отсекает некорректные значения ещё в админке.
  • Для сортировки — только meta_value_num, для фильтрации — только 'type' => 'NUMERIC' в meta_query. Иначе сравнение пойдёт лексикографически: «10» будет меньше «2».
  • Храните только чистые данные: пробелы, валюту, суффиксы («5 баллов») — не в поле, а в шаблоне при выводе.
  • Экранируйте вывод: esc_html(), esc_attr(), esc_js() — по контексту, как и для любых полей.
  • Избегайте сложных вычислений на фронтенде: всю логику делайте на PHP — предсказуемо и безопасно.
  • REST API отдаёт Number и Range как числа, что удобно для фронтенд-интеграций.

Для Number отдельно: не храните форматированные строки («1 200 ₽») — для валюты заведите отдельное поле или выводите символ в шаблоне.

Для Range отдельно: не полагайтесь на ползунок как на единственный источник истины в критичных расчётах — значение всё равно валидируйте, как любое другое.

Частые ошибки и как их избежать

ОшибкаКак исправить
Вывод значения без проверкиОборачивайте в if(is_numeric($value)) и используйте absint()/floatval()
Сортировка по meta_value вместо meta_value_numИспользуйте 'orderby' => 'meta_value_num' для чисел
Фильтрация без 'type' => 'NUMERIC' в meta_queryВсегда указывайте тип сравнения для числовых полей
Хранение форматированных чисел («1 200 ₽») в полеХраните чистое число, форматируйте только при выводе
Отсутствие min/max в настройкахНастройте границы и шаг в интерфейсе ACF
Прямой вывод из get_field() в HTML без экранированияПрименяйте esc_attr(), esc_html(), esc_js() по контексту

Чек-лист перед публикацией

  • Поле выбрано по правилу «конкретное число — Number, значение на шкале — Range».
  • Заданы min/max и step, для Range — единицы измерения.
  • Instructions объясняют редактору смысл значения и шкалу.
  • В шаблоне: проверка is_numeric(), приведение типа, экранирование под контекстом.
  • В запросах: meta_value_num для сортировки, 'type' => 'NUMERIC' для фильтрации.
  • Форматирование (валюта, суффиксы) — только в шаблоне, не в данных.

Заключение

Числовые поля Number и Range в ACF PRO — простой, но мощный инструмент для работы с числовыми данными: от счётчиков и цен до ползунков сложности и приоритетов. Их сила — в строгой типизации и совместимости с запросами WordPress: вы получаете надёжные данные, которые можно безопасно выводить, сортировать и фильтровать. Number берите для точного ввода, Range — для значений на шкале: оба хранят число, различие — только в интерфейсе.

Тема ACF PRO очень обширна, и числовые поля — ещё один шаг: впереди поля Email, URL и Password — завершение кластера базовых полей, а дальше поля выбора, Repeater для повторяющихся блоков, ACF Blocks для интеграции с Gutenberg и многое другое. В следующей публикации разберём поля Email, URL и Password с их валидацией и безопасным выводом — с такими же подробными примерами и готовыми решениями. Подписывайтесь и следите за обновлениями, чтобы не пропустить новые гайды.

VS Code с кодом WordPress и ACF PRO на ноутбуке (стиль лофт
предыдущая

Текстовые поля в ACF: настраиваем Text и Textarea, выводим в шаблоне и применяем на практике

коментарии
0 0 голоса
Рейтинг статьи
Подписаться
Уведомить о
guest
0 комментариев
Старые
Новые Популярные