update_sub_field()

Описание

Обновляет значение определённого дочернего поля.

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

Параметры

update_sub_field($selector, $value, [$post_id]);

$selector (string|array) (Обязательный) Имя или ключ дочернего поля либо массив родительских элементов и номеров строк.
$value (mixed) (Обязательный) Новое значение.
$post_id (mixed) (Необязательный) ID записи, в которой сохраняется значение. По умолчанию используется текущая запись.

Результат

(bool) Возвращает true при успешном обновлении и false при ошибке.

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

Добавлена в версии 5.0.0

Примеры

Обновление дочернего поля внутри цикла have_rows()

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

if( have_rows('repeater') ) {
    $i = 0;
    while( have_rows('repeater') ) {
        the_row();
        $i++;
        update_sub_field('caption', "Эта подпись находится в строке {$i}");
    }
}

Обновление дочернего поля вне цикла have_rows()

В этом примере показано, как обновить значение дочернего поля вне цикла have_rows(). Здесь параметру $selector передаётся массив, содержащий комбинацию имён полей и номеров строк. Этот массив должен читаться слева направо: отношения от родительских элементов к дочерним разделяются номерами строк.

Обратите внимание на примечания об индексации строк.

// Обновить «caption» в первой строке «repeater».
update_sub_field( array('repeater', 1, 'caption'), 'Эта подпись предназначена для первой строки repeater!' );

Обновление вложенного дочернего поля

Функцию update_sub_field() также можно использовать для обращения к вложенному дочернему полю внутри и вне цикла have_rows(). В этом примере показано, как обновить вложенное дочернее поле обоими способами.

// Цикл по родительским строкам.
if( have_rows('repeater') ) {
    $parent_i = 0;
    while( have_rows('repeater') ) {
        the_row();
        $parent_i++;

        // Цикл по дочерним строкам.
        if( have_rows('sub_repeater') ) {
            $child_i = 0;
            while( have_rows('sub_repeater') ) {
                the_row();
                $child_i++;

                // Обновить значение вложенного дочернего поля со ссылкой на индексы родительской и дочерней строк.
                update_sub_field('sub_sub_field', "Это значение предназначено для строки repeater {$parent_i} и строки sub_repeater {$child_i}");
            }
        }
    }
}

// Напрямую обратиться к вложенному дочернему полю.
update_sub_field( array('repeater', 1, 'sub_repeater', 2, 'sub_sub_field'), 'Это значение предназначено для строки repeater 1 и строки sub_repeater 2!' );

Примечания

Смещение индекса

При обращении к дочернему полю с использованием определённого номера строки обратите внимание, что нумерация строк начинается с 1, а не с 0. Это означает, что первая строка имеет индекс 1, вторая — индекс 2 и так далее.

Чтобы начать нумерацию индексов с 0, используйте настройку row_index_offset следующим образом.

functions.php

add_filter('acf/settings/row_index_offset', '__return_zero');

Обновлено: 30.09.2026