Обзор
В этой статье рассматривается, как регистрировать поля и группы полей через файл functions.php. У использования PHP для регистрации полей есть много преимуществ, главное из которых — настройка и распространение. Возможность определять поля внутри файлов темы позволяет разработчикам избегать потери данных при работе в нескольких средах (dev/staging/live). Кроме того, это уменьшает число обращений к базе данных и может ускорить ваш сайт.
Если вам нужен только способ распространения между несколькими средами, пожалуйста, ознакомьтесь с функцией local json, поскольку она решает эту задачу с минимальными усилиями.
Начало работы
Добавлять группы полей и сами поля очень просто. ACF может даже сгенерировать для вас PHP-код со страницы меню Импорт / Экспорт в админке WP!
👨💻 Примечание: важно помнить, что key каждой группы полей и key каждого поля должны быть уникальными. key — это ссылка, по которой ACF находит, сохраняет и загружает данные. Если 2 поля или 2 группы добавлены с одинаковым key, то позже добавленное переопределит исходное.
👨💻 Примечание: группы полей и поля, зарегистрированные через код, не будут видны/доступны для редактирования на странице админки «Редактировать группы полей».
Функции
Ниже приведен список функций, которые будут использоваться в примерах ниже. Эти и другие функции вы можете найти в файле core/local.php.
| Название | Описание |
|---|---|
acf_add_local_field_group( $field_group ) | Добавляет группу полей в локальный кэш |
acf_add_local_field( $field ) | Добавляет поле в локальный кэш |
acf_get_local_field( $key ) | Получить локальное поле |
acf_remove_local_field( $key ) | Удалить локальное поле |
Пример
Базовый
Этот пример показывает, как добавить группу полей.
functions.php
if( function_exists('acf_add_local_field_group') ):
acf_add_local_field_group(array (
'key' => 'group_1',
'title' => 'Моя группа',
'fields' => array (
array (
'key' => 'field_1',
'label' => 'Подзаголовок',
'name' => 'sub_title',
'type' => 'text',
'prefix' => '',
'instructions' => '',
'required' => 0,
'conditional_logic' => 0,
'wrapper' => array (
'width' => '',
'class' => '',
'id' => '',
),
'default_value' => '',
'placeholder' => '',
'prepend' => '',
'append' => '',
'maxlength' => '',
'readonly' => 0,
'disabled' => 0,
)
),
'location' => array (
array (
array (
'param' => 'post_type',
'operator' => '==',
'value' => 'post',
),
),
),
'menu_order' => 0,
'position' => 'normal',
'style' => 'default',
'label_placement' => 'top',
'instruction_placement' => 'label',
'hide_on_screen' => '',
));
endif;Минимальный
Каждое поле содержит множество настроек, которые можно убрать, чтобы сократить код. В этом случае ACF подставит отсутствующие значения по умолчанию.
functions.php
if( function_exists('acf_add_local_field_group') ):
acf_add_local_field_group(array(
'key' => 'group_1',
'title' => 'Моя группа',
'fields' => array (
array (
'key' => 'field_1',
'label' => 'Подзаголовок',
'name' => 'sub_title',
'type' => 'text',
)
),
'location' => array (
array (
array (
'param' => 'post_type',
'operator' => '==',
'value' => 'post',
),
),
),
));
endif;Отдельно
Можно добавлять группу полей и само поле по отдельности. Это позволяет определить поле как переменную и добавить его в несколько групп полей. Обратите внимание: $field должен содержать настройку parent, значение которой совпадает с ключом группы полей либо другого родительского поля (repeater / flexible content).
functions.php
if( function_exists('acf_add_local_field_group') ):
acf_add_local_field_group(array(
'key' => 'group_1',
'title' => 'Моя группа',
'fields' => array (),
'location' => array (
array (
array (
'param' => 'post_type',
'operator' => '==',
'value' => 'post',
),
),
),
));
acf_add_local_field(array(
'key' => 'field_1',
'label' => 'Подзаголовок',
'name' => 'sub_title',
'type' => 'text',
'parent' => 'group_1'
));
endif;Добавление внутри хука
Приведенные выше функции можно использовать в корне файла functions.php или внутри хука acf/init. Этот хук был добавлен в ACF v5.2.7 и рекомендуется к использованию.
Преимущество использования этого хука в том, что функция гарантированно существует и не будет выполняться, если ACF не активен.
functions.php
function my_acf_add_local_field_groups() {
acf_add_local_field_group(array(
'key' => 'group_1',
'title' => 'Моя группа',
'fields' => array (
array (
'key' => 'field_1',
'label' => 'Подзаголовок',
'name' => 'sub_title',
'type' => 'text',
)
),
'location' => array (
array (
array (
'param' => 'post_type',
'operator' => '==',
'value' => 'post',
),
),
),
));
}
add_action('acf/init', 'my_acf_add_local_field_groups');Настройки группы
Ниже приведен список доступных настроек группы полей. Обратите внимание: эти настройки можно просмотреть при редактировании группы полей и экспортировать с минимальными усилиями.
Настройки группы
$group = array(
/* (string) Уникальный идентификатор группы полей. Должен начинаться с 'group_' */
'key' => 'group_1',
/* (string) Отображается в заголовке метабокса */
'title' => 'Моя группа',
/* (array) Массив полей */
'fields' => array(),
/* (array) Массив, содержащий 'группы правил', где каждая 'группа правил' — это массив, содержащий 'правила'.
Каждая группа считается как 'или', а каждое правило — как 'и'. */
'location' => array(
array(
array(
'param' => 'post_type',
'operator' => '==',
'value' => 'post',
),
),
),
/* (int) Группы полей отображаются от меньшего к большему значению. По умолчанию 0 */
'menu_order' => 0,
/* (string) Определяет положение на экране редактирования. По умолчанию normal. Варианты: 'acf_after_title', 'normal' или 'side' */
'position' => 'normal',
/* (string) Определяет стиль метабокса. По умолчанию 'default'. Варианты: 'default' или 'seamless' */
'style' => 'default',
/* (string) Определяет, где размещаются подписи полей относительно самих полей. По умолчанию 'top'.
Варианты: 'top' (над полями) или 'left' (рядом с полями) */
'label_placement' => 'top',
/* (string) Определяет, где размещаются инструкции к полям относительно самих полей. По умолчанию 'label'.
Варианты: 'label' (под подписями) или 'field' (под полями) */
'instruction_placement' => 'label',
/* (array) Массив элементов, которые нужно скрыть на экране */
'hide_on_screen' => '',
);
Настройки поля
Ниже приведен список доступных общих настроек поля. Помимо этих общих настроек, каждый тип поля также получает собственные настройки, перечисленные ниже на странице.
Настройки поля
$field = array (
/* (string) Уникальный идентификатор поля. Должен начинаться с 'field_' */
'key' => 'field_1',
/* (string) Отображается при редактировании значения поля */
'label' => 'Подзаголовок',
/* (string) Используется для сохранения и загрузки данных. Одно слово, без пробелов. Можно использовать подчеркивания и дефисы */
'name' => 'sub_title',
/* (string) Тип поля (text, textarea, image и т. д.) */
'type' => 'text',
/* (string) Инструкции для авторов. Показываются при отправке данных */
'instructions' => '',
/* (int) Обязательно ли значение поля. По умолчанию 0 */
'required' => 0,
/* (mixed) Условно скрывает или показывает это поле на основе значений других полей.
Лучше использовать ACF UI и экспорт, чтобы понять структуру массива. По умолчанию 0 */
'conditional_logic' => 0,
/* (array) Массив атрибутов, задаваемых элементу поля */
'wrapper' => array (
'width' => '',
'class' => '',
'id' => '',
),
/* (mixed) Значение по умолчанию, которое ACF использует, если значение еще не было сохранено */
'default_value' => '',
);
Настройки типа поля
Ниже приведен список дополнительных настроек, доступных для каждого типа поля.
Базовые
Настройки текстового поля
$text_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Отображается внутри поля ввода. По умолчанию '' */
'placeholder' => '',
/* (string) Отображается перед полем ввода. По умолчанию '' */
'prepend' => '',
/* (string) Отображается после поля ввода. По умолчанию '' */
'append' => '',
/* (string) Ограничивает количество символов. По умолчанию '' */
'maxlength' => '',
/* (bool) Делает поле только для чтения. По умолчанию 0 */
'readonly' => 0,
/* (bool) Делает поле недоступным. По умолчанию 0 */
'disabled' => 0,
);Настройки поля textarea
$textarea_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Отображается внутри поля ввода. По умолчанию '' */
'placeholder' => '',
/* (string) Ограничивает количество символов. По умолчанию '' */
'maxlength' => '',
/* (int) Ограничивает число строк и высоту. По умолчанию '' */
'rows' => '',
/* (new_lines) Определяет, как отображать переносы строк. По умолчанию 'wpautop'.
Варианты: 'wpautop' (автоматически добавлять абзацы), 'br' (автоматически добавлять <br>) или '' (без форматирования) */
'new_lines' => '',
/* (bool) Делает поле только для чтения. По умолчанию 0 */
'readonly' => 0,
/* (bool) Делает поле недоступным. По умолчанию 0 */
'disabled' => 0,
);Настройки числового поля
$number_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Отображается внутри поля ввода. По умолчанию '' */
'placeholder' => '',
/* (string) Отображается перед полем ввода. По умолчанию '' */
'prepend' => '',
/* (string) Отображается после поля ввода. По умолчанию '' */
'append' => '',
/* (int) Минимальное значение числа. По умолчанию '' */
'min' => '',
/* (int) Максимальное значение числа. По умолчанию '' */
'max' => '',
/* (int) Шаг изменения. По умолчанию '' */
'step' => '',
);Настройки поля email
$email_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Отображается внутри поля ввода. По умолчанию '' */
'placeholder' => '',
/* (string) Отображается перед полем ввода. По умолчанию '' */
'prepend' => '',
/* (string) Отображается после поля ввода. По умолчанию '' */
'append' => '',
);Настройки поля URL
$url_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Отображается внутри поля ввода. По умолчанию '' */
'placeholder' => '',
);Настройки поля пароля
$password_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Отображается внутри поля ввода. По умолчанию '' */
'placeholder' => '',
/* (string) Отображается перед полем ввода. По умолчанию '' */
'prepend' => '',
/* (string) Отображается после поля ввода. По умолчанию '' */
'append' => '',
);Содержимое
Настройки поля WYSIWYG
$wysiwyg_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Укажите, какие вкладки доступны. По умолчанию 'all'.
Варианты: 'all' (визуальный редактор и текст), 'visual' (только визуальный режим) или text (только текст) */
'tabs' => 'all',
/* (string) Укажите панель инструментов редактора. По умолчанию 'full'.
Варианты: 'full' (полная), 'basic' (базовая) или пользовательская панель инструментов (https://www.advancedcustomfields.com/resources/customize-the-wysiwyg-toolbars/) */
'toolbar' => 'full',
/* (bool) Показывать кнопку загрузки медиафайлов. По умолчанию 1 */
'media_upload' => 1,
);Настройки поля oEmbed
$oembed_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (int) Укажите ширину элемента oEmbed. Может быть переопределена через CSS */
'width' => '',
/* (int) Укажите высоту элемента oEmbed. Может быть переопределена через CSS */
'height' => '',
);Настройки поля изображения
$image_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Укажите тип значения, возвращаемого get_field(). По умолчанию 'array'.
Варианты: 'array' (массив изображения), 'url' (URL изображения) или 'id' (ID изображения) */
'return_format' => 'array',
/* (string) Укажите размер изображения, который показывается при редактировании. По умолчанию 'thumbnail'. */
'preview_size' => 'thumbnail',
/* (string) Ограничивает медиатеку изображений. По умолчанию 'all'.
Варианты: 'all' (все изображения) или 'uploadedTo' (загруженные в запись) */
'library' => 'all',
/* (int) Укажите минимальную ширину в px, требуемую при загрузке. По умолчанию 0 */
'min_width' => 0,
/* (int) Укажите минимальную высоту в px, требуемую при загрузке. По умолчанию 0 */
'min_height' => 0,
/* (int) Укажите минимальный размер файла в MB, требуемый при загрузке. По умолчанию 0
Можно также указывать единицу измерения, например '256KB' */
'min_size' => 0,
/* (int) Укажите максимальную ширину в px, допустимую при загрузке. По умолчанию 0 */
'max_width' => 0,
/* (int) Укажите максимальную высоту в px, допустимую при загрузке. По умолчанию 0 */
'max_height' => 0,
/* (int) Укажите максимальный размер файла в MB, допустимый при загрузке. По умолчанию 0
Можно также указывать единицу измерения, например '256KB' */
'max_size' => 0,
/* (string) Список расширений типов файлов, разрешенных при загрузке, через запятую. По умолчанию '' */
'mime_types' => '',
);Настройки поля файла
$file_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Укажите тип значения, возвращаемого get_field(). По умолчанию 'array'.
Варианты: 'array' (массив файла), 'url' (URL файла) или 'id' (ID файла) */
'return_format' => 'array',
/* (string) Укажите размер файла, который показывается при редактировании. По умолчанию 'thumbnail'. */
'preview_size' => 'thumbnail',
/* (string) Ограничивает медиатеку файлов. По умолчанию 'all'.
Варианты: 'all' (все файлы) или 'uploadedTo' (загруженные в запись) */
'library' => 'all',
/* (int) Укажите минимальный размер файла в MB, требуемый при загрузке. По умолчанию 0
Можно также указывать единицу измерения, например '256KB' */
'min_size' => 0,
/* (int) Укажите максимальный размер файла в MB, допустимый при загрузке. По умолчанию 0
Можно также указывать единицу измерения, например '256KB' */
'max_size' => 0,
/* (string) Список расширений типов файлов, разрешенных при загрузке, через запятую. По умолчанию '' */
'mime_types' => '',
);Настройки поля галереи
$gallery_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (int) Укажите минимальное количество вложений, которое нужно выбрать. По умолчанию 0 */
'min' => 0,
/* (int) Укажите максимальное количество вложений, которое можно выбрать. По умолчанию 0 */
'max' => 0,
/* (string) Укажите размер изображения, который показывается при редактировании. По умолчанию 'thumbnail'. */
'preview_size' => 'thumbnail',
/* (string) Ограничивает медиатеку изображений. По умолчанию 'all'.
Варианты: 'all' (все изображения) или 'uploadedTo' (загруженные в запись) */
'library' => 'all',
/* (int) Укажите минимальную ширину в px, требуемую при загрузке. По умолчанию 0 */
'min_width' => 0,
/* (int) Укажите минимальную высоту в px, требуемую при загрузке. По умолчанию 0 */
'min_height' => 0,
/* (int) Укажите минимальный размер файла в MB, требуемый при загрузке. По умолчанию 0
Можно также указывать единицу измерения, например '256KB' */
'min_size' => 0,
/* (int) Укажите максимальную ширину в px, допустимую при загрузке. По умолчанию 0 */
'max_width' => 0,
/* (int) Укажите максимальную высоту в px, допустимую при загрузке. По умолчанию 0 */
'max_height' => 0,
/* (int) Укажите максимальный размер файла в MB, допустимый при загрузке. По умолчанию 0
Можно также указывать единицу измерения, например '256KB' */
'max_size' => 0,
/* (string) Список расширений типов файлов, разрешенных при загрузке, через запятую. По умолчанию '' */
'mime_types' => '',
);Варианты выбора
Настройки поля select
$select_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (array) Массив вариантов, где ключ ('red') используется как значение, а значение ('Red') — как метка */
'choices' => array(
'red' => 'Красный'
),
/* (bool) Разрешить выбирать значение null (пустое). По умолчанию 0 */
'allow_null' => 0,
/* (bool) Разрешить выбирать несколько значений. По умолчанию 0 */
'multiple' => 0,
/* (bool) Использовать интерфейс select2. По умолчанию 0 */
'ui' => 0,
/* (bool) Загружать варианты через AJAX. Для этого параметр ui тоже должен быть true. По умолчанию 0 */
'ajax' => 0,
/* (string) Отображается внутри поля select2. По умолчанию '' */
'placeholder' => '',
);Настройки поля checkbox
$checkbox_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (array) Массив вариантов, где ключ ('red') используется как значение, а значение ('Red') — как метка */
'choices' => array(
'red' => 'Красный'
),
/* (string) Укажите расположение чекбоксов. По умолчанию 'vertical'.
Варианты: 'vertical' или 'horizontal' */
'layout' => 'vertical',
/* (bool) Разрешить пользователю добавлять собственные варианты. По умолчанию false. */
'allow_custom' => false,
/* (bool) Разрешить сохранять пользовательские варианты в списке значений поля. По умолчанию false. */
'save_custom' => false,
/* (bool) Добавляет в список чекбокс «Выбрать все». По умолчанию false. */
'toggle' => false,
/* (string) Указывает формат возвращаемого значения при загрузке. По умолчанию 'value'.
Варианты: 'value', 'label' или 'array' */
'return_format' => 'value',
);Настройки поля radio
$radio_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (array) Массив вариантов, где ключ ('red') используется как значение, а значение ('Red') — как метка */
'choices' => array(
'red' => 'Красный'
),
/* (bool) Разрешить ввод собственного варианта через текстовое поле */
'other_choice' => 0,
/* (bool) Разрешить добавлять пользовательское значение в список вариантов этого поля. По умолчанию 0.
Не работает с полями, зарегистрированными через PHP, только с полями из БД */
'save_other_choice' => 0,
/* (string) Укажите расположение чекбоксов. По умолчанию 0.
Варианты: 'vertical' или 'horizontal' */
'layout' => 0,
);Настройки поля «Истина / Ложь»
$true_false_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Текст, отображаемый рядом с чекбоксом */
'message' => 0,
);Связанные
Настройки поля объекта записи
$post_object_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (mixed) Укажите массив типов записей, чтобы отфильтровать доступные варианты. По умолчанию '' */
'post_type' => '',
/* (mixed) Укажите массив таксономий, чтобы отфильтровать доступные варианты. По умолчанию '' */
'taxonomy' => '',
/* (bool) Разрешить выбирать значение null (пустое). По умолчанию 0 */
'allow_null' => 0,
/* (bool) Разрешить выбирать несколько значений. По умолчанию 0 */
'multiple' => 0,
/* (string) Укажите тип значения, возвращаемого get_field(). По умолчанию 'object'.
Варианты: 'object' (объект записи) или 'id' (ID записи) */
'return_format' => 'object',
);Настройки поля ссылки на страницу
$page_link_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (mixed) Укажите массив типов записей, чтобы отфильтровать доступные варианты. По умолчанию '' */
'post_type' => '',
/* (mixed) Укажите массив таксономий, чтобы отфильтровать доступные варианты. По умолчанию '' */
'taxonomy' => '',
/* (bool) Разрешить выбирать значение null (пустое). По умолчанию 0 */
'allow_null' => 0,
/* (bool) Разрешить выбирать несколько значений. По умолчанию 0 */
'multiple' => 0,
);Настройки поля связи
$relationship_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (mixed) Укажите массив типов записей, чтобы отфильтровать доступные варианты. По умолчанию '' */
'post_type' => '',
/* (mixed) Укажите массив таксономий, чтобы отфильтровать доступные варианты. По умолчанию '' */
'taxonomy' => '',
/* (array) Укажите доступные фильтры, используемые для поиска записей.
Варианты: 'search' (поле поиска), 'post_type' (выбор типа записи) и 'taxonomy' (выбор таксономии) */
'filters' => array('search', 'post_type', 'taxonomy'),
/* (array) Укажите визуальные элементы для каждой записи.
Варианты: 'featured_image' (иконка избранного изображения) */
'elements' => array(),
/* (int) Укажите минимальное количество записей, которое нужно выбрать. По умолчанию 0 */
'min' => 0,
/* (int) Укажите максимальное количество записей, которое можно выбрать. По умолчанию 0 */
'max' => 0,
/* (string) Укажите тип значения, возвращаемого get_field(). По умолчанию 'object'.
Варианты: 'object' (объект записи) или 'id' (ID записи) */
'return_format' => 'object',
);Настройки поля таксономии
$taxonomy_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (string) Укажите таксономию, из которой выбирать термины. По умолчанию 'category' */
'taxonomy' => '',
/* (array) Укажите внешний вид поля таксономии. По умолчанию 'checkbox'
Варианты: 'checkbox' (чекбоксы), 'multi_select' (поле выбора — несколько значений), 'radio' (радиокнопки) или 'select' (поле выбора) */
'field_type' => 'checkbox',
/* (bool) Разрешить выбирать значение null (пустое). По умолчанию 0 */
'allow_null' => 0,
/* (bool) Разрешить сохранять выбранные термины как связи с записью */
'load_save_terms' => 0,
/* (string) Укажите тип значения, возвращаемого get_field(). По умолчанию 'id'.
Варианты: 'object' (объект термина) или 'id' (ID термина) */
'return_format' => 'id',
/* (bool) Разрешить добавлять новые термины через всплывающее окно */
'add_term' => 1
);Настройки поля пользователя
$user_field = array(
/* ... Вставьте сюда общие настройки ... */
/* (array) Массив ролей, чтобы ограничить список пользователей, доступных для выбора */
'role' => array(),
/* (bool) Разрешить выбирать значение null (пустое). По умолчанию 0 */
'allow_null' => 0,
/* (bool) Разрешить выбирать несколько значений. По умолчанию 0 */
'multiple' => 0,
);
Обновлено: 01.06.2026