Добавление пользовательских настроек к полям ACF

Обзор

Каждый тип поля ACF может содержать несколько различных настроек, которые можно использовать для настройки внешнего вида и функциональности поля. Существует два основных типа таких настроек: глобальные и зависящие от типа.

Глобальные настройки поля регистрируются один раз и отображаются для каждого типа поля. Примером глобальной настройки может быть параметр «Имя поля» — он отображается у каждого поля ACF, поскольку необходим для работы полей.

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

В этой статье объясняется, как добавлять пользовательские настройки поля как к существующим типам полей, так и к собственным пользовательским типам полей.

Журнал изменений

• Настройки типа поля были перенесены на разные вкладки в версии 6.0
• Начиная с версии 6.0, настройки типа поля теперь выводятся в тегах div вместо тегов tr
• Инструкции, задаваемые для настроек типа поля, теперь отображаются как подсказки в версии 6.0
• Функция acf_render_field_setting() добавлена в версии 5.0

Добавление глобальной настройки поля

Как упоминалось выше, глобальные настройки поля отображаются для каждого типа поля. В ACF 6 эти настройки показываются на вкладке «Общие» для каждого поля.

В следующем примере показано, как добавить новую настройку под названием «Только для админа», которая добавит переключатель true/false ко всем полям и позволит скрывать их от пользователей, не являющихся администраторами.

1. Добавление настройки

Глобальные настройки можно добавить с помощью action hook acf/render_field_settings и функции acf_render_field_setting(). Следующий фрагмент добавит глобальную настройку на вкладку «Общие» для всех типов полей. Обратите внимание, что третий параметр для acf_render_field_setting() установлен в true, чтобы указать, что это глобальная настройка.

function my_admin_only_render_field_settings( $field ) {
    acf_render_field_setting( $field, array(
        'label'        => __( 'Только для админа?', 'my-textdomain' ),
        'instructions' => '',
        'name'         => 'admin_only',
        'type'         => 'true_false',
        'ui'           => 1,
    ), true ); // Если добавляете настройку глобально, вы ДОЛЖНЫ передать true в качестве третьего параметра!
}
add_action( 'acf/render_field_settings', 'my_admin_only_render_field_settings' );

2. Использование настройки

После добавления новой настройки «Только для админа?» мы можем подключиться к любой части ACF и использовать эту настройку. Следующий код подключается к фильтру acf/prepare_field, который выполняется непосредственно перед тем, как поле будет выведено в форме. Это позволит проверить, является ли текущий пользователь администратором, и если нет — не показывать поле:

function my_admin_only_prepare_field( $field ) {
    // Прерываем выполнение, если настройка 'admin_only' отсутствует или равна false.
    if ( empty( $field['admin_only'] ) ) {
        return $field;
    }

    // Не показываем поле, если текущий пользователь не администратор.
    if ( ! current_user_can( 'manage_options' ) ) {
        return false;
    }

    // В противном случае возвращаем исходное поле.
    return $field;
}
add_filter( 'acf/prepare_field', 'my_admin_only_prepare_field' );

3. Проверка настройки

После добавления приведённого выше кода в файл functions.php и использования поля с настройкой «Только для админа?» мы можем войти как администратор или редактор и проверить наличие поля!

Добавление настроек для конкретного типа поля

Настройки поля можно добавлять или ограничивать отдельными типами полей (text, image и т. д.). В ACF 6.0 и выше эти настройки также можно отображать на определённых вкладках внутри типа поля (Общие, Проверка, Представление или Условная логика).

Для добавления настроек поля на эти вкладки можно использовать следующие action hook:

• acf/render_field_settings/type={type} (устаревший action для вкладки «Общие» — можно использовать в ACF 5 для добавления настроек, зависящих от типа поля)
• acf/render_field_general_settings/type={type} (для добавления настроек на вкладку «Общие»)
• acf/render_field_validation_settings/type={type} (для добавления настроек на вкладку «Проверка»)
• acf/render_field_presentation_settings/type={type} (для добавления настроек на вкладку «Представление»)
• acf/render_field_conditional_logic_settings/type={type} (для добавления настроек на вкладку «Условная логика»)

Эти фильтры также применяются в базовом классе acf_field, поэтому если у вас есть пользовательский тип поля, наследующий acf_field, вы можете просто добавить в свой класс один или несколько следующих методов:

• render_field_settings()
• render_field_general_settings()
• render_field_validation_settings()
• render_field_presentation_settings()
• render_field_conditional_logic_settings()

Следующий пример добавит новую настройку «Исключить слова» на вкладку «Проверка» для типа поля textarea. Это добавит текстовое поле, которое позже мы будем использовать для хранения списка слов, запрещённых для использования в textarea.

1. Добавление настройки

Поскольку в этом примере настройка добавляется на вкладку «Проверка», для вывода настройки мы будем использовать action hook acf/render_field_validation_settings/type={$type}.

Обратите внимание, что третий параметр для функции acf_render_field_setting() не используется — это делает настройку специфичной для поля, а не глобальной, как показано выше.

function my_textarea_render_field_settings( $field ) {
    acf_render_field_setting( $field, array(
        'label'        => __( 'Исключить слова', 'my-textdomain' ),
        'instructions' => __( 'Введите слова через запятую', 'my-textdomain' ),
        'name'         => 'exclude_words',
        'type'         => 'text',
    ) );
}
add_action( 'acf/render_field_validation_settings/type=textarea', 'my_textarea_render_field_settings' );

2. Использование настройки

После добавления новой настройки «Исключить слова» и нового поля textarea, использующего эту настройку, мы можем подключиться к любой части ACF и использовать её. Следующий код подключается к фильтру acf/validate_value, который выполняется во время проверки значения. Это позволит нам проверить, содержит ли текущее значение какие-либо слова из списка исключений, и уведомить пользователя с помощью сообщения об ошибке проверки:

function my_textarea_validate_value( $valid, $value, $field, $input ) {
    // Прерываем выполнение, если поле уже недопустимо.
    if ( ! $valid ) {
        return $valid;
    }

    // Прерываем выполнение, если настройка "Исключить слова" не задана.
    if ( empty( $field['exclude_words'] ) ) {
        return $valid;
    }

    // Разбиваем слова в массив, по которому можно пройтись циклом.
    $words = explode( ',', $field['exclude_words'] );
    $words = array_map( 'trim', $words ); // Удаляем пробелы.
    $words = array_values( $words ); // Удаляем пустые значения.

    foreach( $words as $word ) {
        // Проверяем, существует ли слово.
        if( stripos( $value, $word ) !== false ) {
            $valid = sprintf( __( 'Значение не должно содержать "%s"', 'my-textdomain' ), $word );
            break;
        }
    }

    return $valid;
}
add_filter( 'acf/validate_value/type=textarea', 'my_textarea_validate_value', 10, 4 );

3. Проверка настройки

После добавления приведённого выше кода в файл functions.php и использования поля с настройкой exclude_words мы можем отредактировать запись и попытаться сохранить значение.

Добавление пользовательской вкладки настроек поля

С новым форматом вкладок, представленным в ACF 6.0, плагины, добавляющие настройки к полям, могут делать это с помощью нового фильтра acf/field_group/additional_field_settings_tabs, который появился в ACF 6.1.

Например, чтобы добавить новую вкладку под названием «Мои настройки» для каждого поля, используйте:

add_filter( 'acf/field_group/additional_field_settings_tabs', function ( $tabs ) {
    $tabs['my-settings'] = 'Мои настройки';

    return $tabs;
} );

Чтобы добавить поле на эту новую вкладку, используйте фильтр acf/field_group/render_field_settings_tab/$tab-key:

add_action( 'acf/field_group/render_field_settings_tab/my-settings', function ( $field ) {
    acf_render_field_setting(
        $field,
        array(
            'label'        => 'Только для админа?',
            'instructions' => '',
            'name'         => 'admin_only',
            'type'         => 'true_false',
            'ui'           => 1,
        ),
        true
    );
} );

Добавление пользовательской вкладки в настройки группы полей

Также можно добавить пользовательскую вкладку настроек в метабокс «Настройки» в нижней части экрана редактора группы полей, используя фильтр acf/field_group/additional_group_settings_tabs так же, как и выше.

Обновление существующих настроек полей для ACF 6

Пользовательские настройки полей, добавленные с помощью action hook acf/render_field_settings или acf/render_field_settings/type={type}, продолжат работать в ACF 6, а настройки будут отображаться на вкладке «Общие» для любых полей, к которым они были добавлены.

Однако в ACF 6 есть некоторые изменения, которые могут потребовать дополнительного кода.

Перенос существующей настройки поля на другую вкладку

Если вы хотите перенести пользовательскую настройку поля на другую вкладку и при этом поддержать пользователей, которые всё ещё используют ACF 5, вам, скорее всего, понадобится добавить немного кода, чтобы настройка регистрировалась по-разному в ACF 5 и 6 и не отображалась дважды.

Один из способов сделать это — обновить существующий код настройки поля так, чтобы он завершал выполнение раньше, если используется ACF 6.0 или выше.

function render_field_settings( $field ) {
    // Мы используем ACF 6.0 или выше, поэтому здесь регистрировать настройку не нужно.
    if ( version_compare( ACF_MAJOR_VERSION, '6.0', '>=' ) ) {
        return;
    }

    // Остальной код настроек поля.
}

Затем можно добавить отдельную функцию, которая подключается к одному из action hook, зависящих от вкладки, как упоминалось выше.

Изменения в acf_render_field_setting() в ACF 6

В ACF 5 настройки поля выводились как строки таблицы внутри родительской таблицы с классом .acf-table. В ACF 6 и выше настройки типа поля больше не выводятся внутри таблицы.

В результате функция acf_render_field_setting() была обновлена так, чтобы по умолчанию выводить настройки поля, созданные этой функцией, внутри элементов <div>.

Скорее всего, это не вызовет проблем, если вы используете acf_render_field_setting() в одном из action hook, упомянутых выше, или в классе, который наследует acf_field.

Хотя это и не рекомендуется, функцию acf_render_field_setting() можно использовать и вне этих action hook. В таком случае мы рекомендуем проверить все настройки, созданные этой функцией, чтобы убедиться, что они отображаются как ожидается, и при необходимости обновить код.

Изменения инструкций настройки поля в ACF 6

В ACF 6 значение параметра instructions, передаваемого в acf_render_field_settings(), теперь отображается как подсказка, чтобы уменьшить визуальный шум в интерфейсе.

Если вы предпочитаете отображать instructions прямо рядом с настройкой поля, как в ACF 5, это можно сделать, изменив параметр instructions на hint:

function my_textarea_render_field_settings( $field ) {
    acf_render_field_setting( $field, array(
        'label' => __( 'Исключить слова', 'my-textdomain' ),
        'hint'  => __( 'Введите слова через запятую', 'my-textdomain' ),
        'name'  => 'exclude_words',
        'type'  => 'text',
    ) );
}
add_action( 'acf/render_field_validation_settings/type=textarea', 'my_textarea_render_field_settings' );

Это выведет указанный текст подсказки под настройкой поля:

Заключение

Добавлять дополнительные настройки полей в ACF легко, а возможности практически безграничны!

Обновлено: 01.06.2026