Пользовательские правила расположения в ACF

Введение

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

Пример правила расположения: «Тип записи == Запись».

Плагин Advanced Custom Fields включает различные типы расположения, удовлетворяющие потребностям большинства сайтов. Кроме того, можно определить дополнительные типы расположения, чтобы реализовать собственную логику отображения группы полей.

В этом руководстве показано, как создать и зарегистрировать пользовательский тип расположения.

Требования

Класс ACF_Location, рассматриваемый в этом руководстве, требует версию 5.9.0 или выше. Если вы ещё этого не сделали, обновите плагин, чтобы воспользоваться этой возможностью.

Если вы используете предыдущую версию, ознакомьтесь вместо этого с этим руководством.

Начало работы

Чтобы создать пользовательский тип расположения, расширьте класс ACF_Location и переопределите некоторые его методы. Затем зарегистрируйте его с помощью функции acf_register_location_type().

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

class My_Location extends ACF_Location {
    function initialize() {
        $this->name = '50_50';
        $this->label = __( 'Пятьдесят на пятьдесят' );
    }
    function match() {
        return rand( 0, 1 );
    }
}
acf_register_location_type( 'My_Location' );

ACF_Location

Класс ACF_Location содержит несколько свойств и методов, не все из которых необходимо настраивать. Перед тем как перейти к рабочему примеру, ознакомьтесь с доступными свойствами и методами, перечисленными ниже.

Свойства

name
(Строка) Уникальное имя, идентифицирующее тип расположения. Например, «post_author».
Имя типа расположения может содержать только строчные буквы, цифры и символы подчёркивания.
```
$this->name = 'post_author';
```
label
(Строка) Метка типа расположения, отображаемая при редактировании группы полей. Например, «Автор записи».
```
$this->label = __('Автор записи');
```
category
(Строка) (Необязательно) Группа, в которой этот тип расположения отображается в выпадающем списке типов расположения.
Допустимы значения «post», «page», «user», «forms» или пользовательская метка. По умолчанию используется значение «post».
```
$this->category = 'post';
```
public
(Логическое значение) (Необязательно) Доступно ли правило расположения для выбора пользователем. По умолчанию — true.
```
$this->public = true;
```
object_type
(Строка) (Необязательно) Тип объекта, связанный с этим расположением.
Принимает тип объекта, доступный через acf_get_object_type(), например «post», «user», «block» и т. д. Определение этого свойства позволяет ACF отображать значок в столбце таблицы групп полей в админ-панели. По умолчанию используется пустая строка, обозначающая «Разные».
```
$this->object_type = 'post';
```

Методы

initialize
Вызывается во время регистрации для инициализации свойств.

public function initialize() {
    $this->name = 'post_author';
    // Определите здесь все остальные свойства.
}

match
Сравнивает указанное правило расположения с аргументами текущего экрана и возвращает true при совпадении.
Возврат true позволяет отображать группу полей на текущем экране. Возврат false предотвращает её отображение.
```
public function match( $rule, $screen, $field_group ) {
    return false;
}
```
get_operators
(Необязательно) Возвращает массив операторов, доступных при редактировании правила.
Если метод не определён, используются операторы по умолчанию «равно» и «не равно».
```
public function get_operators( $rule ) {
    return array(
        '==' => __( "равно" ),
        '!=' => __( "не равно" )
    );
}
```
get_values
(Необязательно) Возвращает массив возможных значений, доступных при редактировании правила.
```
public function get_values( $rule ) {
    return array(
        'foo' => 'Foo',
        'bar' => 'Bar'
    );
}
```
get_object_subtype
(Необязательно) Подобно свойству object_type, этот метод позволяет ACF отображать более точный значок в столбце таблицы групп полей в админ-панели.
Возвращает один или несколько подтипов, связанных с этим расположением.
Допустимые подтипы объектов включают типы записей и таксономии. По умолчанию используется пустая строка.
```
public function get_object_subtype( $rule ) {
    return 'category';
}
```

Пример

Используем некоторые из этих свойств и методов на практике и создадим пользовательский тип расположения «Автор записи». Этот тип расположения позволит отображать группу полей при редактировании записи в зависимости от атрибута автора записи.

1. Настройка

Сначала определим новый класс ACF_Location, используя метод initialize() для настройки свойств типа расположения. В этом примере мы будем работать с файлом темы includes/class-my-acf-location-post-author.php.

includes/class-my-acf-location-post-author.php

<?php 

if( ! defined( 'ABSPATH' ) ) exit;

class My_ACF_Location_Post_Author extends ACF_Location {

    public function initialize() {
        $this->name = 'post_author';
        $this->label = __( "Автор записи", 'acf' );
        $this->category = 'post';
        $this->object_type = 'post';
    }
}

Затем подключим и зарегистрируем этот тип расположения в файле functions.php.

functions.php

add_action('acf/init', 'my_acf_init_location_types');
function my_acf_init_location_types() {

    // Проверяем существование функции, затем подключаем и регистрируем класс пользовательского типа расположения.
    if( function_exists('acf_register_location_type') ) {
        include_once( 'includes/class-my-acf-location-post-author.php' );
        acf_register_location_type( 'My_ACF_Location_Post_Author' );
    }
}

Готово 🎉. Теперь можно отредактировать группу полей и выбрать новый тип расположения.

Выбор типа правила расположения «Автор записи»

2. Настройка выпадающих списков

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

В этом примере мы оставим выпадающий список оператора без изменений: в нём будут отображаться варианты по умолчанию «равно» (==) и «не равно» (!=). Однако выпадающий список значения мы настроим так, чтобы он отображал список всех пользователей.

Функция WordPress get_users() значительно упрощает эту задачу. Следующий фрагмент заполнит массив вариантов, используя ID пользователя в качестве значения параметра и отображаемое имя пользователя в качестве его метки.

includes/class-my-acf-location-post-author.php

public function get_values( $rule ) {
    $choices = array();

    // Загружаем всех пользователей, перебираем их и добавляем в список вариантов.
    $users = get_users();
    if( $users ) {
        foreach( $users as $user ) {
            $choices[ $user->ID ] = $user->display_name;
        }
    }
    return $choices;
}

Наш пользовательский тип расположения постепенно обретает форму! Теперь можно создать правило расположения «Автор записи == Elliot» 🙌.

Выбор значения правила расположения «Автор записи»

Наконец, необходимо определить логику, которая сравнивает правило, например «Автор записи == Elliot», с текущим экраном.

3. Проверка совпадения

При просмотре экрана редактирования WordPress Advanced Custom Fields определяет, какие группы полей отображать, основываясь на их правилах расположения. Для каждого правила расположения проверяется, соответствует ли оно аргументам текущего экрана.

Логика этого «сопоставления» определяется в методе match(). Метод принимает 3 параметра: условия правила, аргументы текущего экрана и группу полей, видимость которой определяется. От метода требуется только вернуть логическое значение, отражающее результат сопоставления.

В этом примере мы сравним выбранное значение правила (ID пользователя) с атрибутом автора записи. Также необходимо учитывать, что этот тип расположения применяется только при редактировании записи, а не пользователя, термина, виджета и т. д.

includes/class-my-acf-location-post-author.php

public function match( $rule, $screen, $field_group ) {

    // Проверяем аргументы экрана на наличие «post_id», который существует при редактировании записи.
    // Для всех остальных экранов редактирования возвращаем false.
    if( isset($screen['post_id']) ) {
        $post_id = $screen['post_id'];
    } else {
        return false;
    }

    // Загружаем объект записи для этого экрана редактирования.
    $post = get_post( $post_id );
    if( !$post ) {
        return false;
    }

    // Сравниваем атрибут автора записи со значением правила.
    $result = ( $post->post_author == $rule['value'] );

    // Возвращаем результат с учётом типа оператора.
    if( $rule['operator'] == '!=' ) {
        return !$result;
    }
    return $result;
}

Поздравляем 🎉 Тип расположения «Автор записи» готов! Группа полей с этим типом расположения будет отображаться только при редактировании записи, автором которой является «Elliot».

Корректное срабатывание типа расположения «Автор записи» для правила «Автор записи == Elliot»

Полный код

Для справки приведён полный код пользовательского типа расположения «Автор записи».

includes/class-my-acf-location-post-author.php

<?php 

if( ! defined( 'ABSPATH' ) ) exit;

class My_ACF_Location_Post_Author extends ACF_Location {

    public function initialize() {
        $this->name = 'post_author';
        $this->label = __( "Автор записи", 'acf' );
        $this->category = 'post';
        $this->object_type = 'post';
    }

    public function get_values( $rule ) {
        $choices = array();

        // Загружаем всех пользователей, перебираем их и добавляем в список вариантов.
        $users = get_users();
        if( $users ) {
            foreach( $users as $user ) {
                $choices[ $user->ID ] = $user->display_name;
            }
        }
        return $choices;
    }

    public function match( $rule, $screen, $field_group ) {

        // Проверяем аргументы экрана на наличие «post_id», который существует при редактировании записи.
        // Для всех остальных экранов редактирования возвращаем false.
        if( isset($screen['post_id']) ) {
            $post_id = $screen['post_id'];
        } else {
            return false;
        }

        // Загружаем объект записи для этого экрана редактирования.
        $post = get_post( $post_id );
        if( !$post ) {
            return false;
        }

        // Сравниваем атрибут автора записи со значением правила.
        $result = ( $post->post_author == $rule['value'] );

        // Возвращаем результат с учётом типа оператора.
        if( $rule['operator'] == '!=' ) {
            return !$result;
        }
        return $result;
    }
}

functions.php

add_action('acf/init', 'my_acf_init_location_types');
function my_acf_init_location_types() {

    // Проверяем существование функции, затем подключаем и регистрируем класс пользовательского типа расположения.
    if( function_exists('acf_register_location_type') ) {
        include_once( 'includes/class-my-acf-location-post-author.php' );
        acf_register_location_type( 'My_ACF_Location_Post_Author' );
    }
}

Итоги

Класс ACF_Location значительно упрощает создание пользовательских правил расположения. Всего в нескольких строках кода мы смогли:

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

Обновлено: 30.09.2026

Пользовательские правила расположения

Введение

Требования

Начало работы

ACF_Location

Свойства

Методы

Пример

1. Настройка

includes/class-my-acf-location-post-author.php

functions.php

2. Настройка выпадающих списков

includes/class-my-acf-location-post-author.php

3. Проверка совпадения

includes/class-my-acf-location-post-author.php

Полный код

includes/class-my-acf-location-post-author.php

functions.php

Итоги

Похожие записи

Смотрите также