Числовые поля в ACF PRO: работаем с Number и Range — настройка диапазонов, валидация и практические кейсы
После текстовых полей числовые — второй по частоте кластер в практике: счётчики, рейтинги, цены, приоритеты, время чтения. Оба поля — Number и Range — хранят чистое число, но решают разные задачи: Number — про точный ввод значения, Range — про выбор значения из заданного диапазона. В этой статье разберём настройки обоих полей, безопасный вывод, работу с запросами WordPress и главное — критерии выбора: когда какое поле применять и почему.
Number или Range: как выбрать поле
Оба поля хранят число (int или float) и оба поддерживают ограничения min/max и шаг. Разница — в интерфейсе ввода и, как следствие, в типе задач.
| Критерий | Number | Range |
|---|---|---|
| Как вводится | Точное значение с клавиатуры | Ползунок в границах 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 ?>Разбор по строкам:
- Значение записываем в переменную
$viewsи проверяем на пустоту — чтобы не выводить блок «Просмотров: » при незаполненном поле. 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 ?>Разбор по строкам:
is_numeric($difficulty)— проверка типа даже для Range: это защита от неожиданных данных (пустого значения, строки после миграции).- Условия превращают число в осмысленный класс и текст: значениям 1–2 соответствует «Легко», 3–4 — «Средне», 5 — «Сложно». Границы групп легко сдвинуть под вашу шкалу.
- В атрибут класса уходит
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 с их валидацией и безопасным выводом — с такими же подробными примерами и готовыми решениями. Подписывайтесь и следите за обновлениями, чтобы не пропустить новые гайды.
коментарии