Разработка кастомных полей (Custom Fields) через ACF для WordPress

Разработка кастомных полей (Custom Fields) через ACF для WordPress

Advanced Custom Fields (ACF) — де-факто стандарт для добавления структурированных данных к записям WordPress. Редактор получает нормальные поля ввода вместо свободного текстового мета-поля custom-fields. ACF PRO добавляет Repeater, Flexible Content, Gallery и clone — без него сложные структуры данных практически нереализуемы стандартными средствами. Настройка полей под задачу занимает от нескольких часов до 2 дней в зависимости от количества групп и логики условного отображения.

Регистрация групп полей через код

ACF позволяет регистрировать группы полей программно (а не через /wp-admin) — это обязательно для production: конфигурация хранится в коде, а не в БД:

add_action('acf/init', function () {
    acf_add_local_field_group([
        'key'      => 'group_project_details',
        'title'    => 'Детали проекта',
        'fields'   => [
            [
                'key'           => 'field_project_client',
                'label'         => 'Клиент',
                'name'          => 'project_client',
                'type'          => 'text',
                'required'      => 1,
                'placeholder'   => 'Название компании',
            ],
            [
                'key'           => 'field_project_year',
                'label'         => 'Год реализации',
                'name'          => 'project_year',
                'type'          => 'number',
                'min'           => 2000,
                'max'           => 2030,
                'default_value' => date('Y'),
            ],
            [
                'key'           => 'field_project_url',
                'label'         => 'URL проекта',
                'name'          => 'project_url',
                'type'          => 'url',
            ],
            [
                'key'           => 'field_project_tech_stack',
                'label'         => 'Технологии',
                'name'          => 'project_tech_stack',
                'type'          => 'checkbox',
                'choices'       => [
                    'react'      => 'React',
                    'vue'        => 'Vue.js',
                    'laravel'    => 'Laravel',
                    'wordpress'  => 'WordPress',
                    'nextjs'     => 'Next.js',
                ],
                'layout'        => 'horizontal',
            ],
            [
                'key'           => 'field_project_gallery',
                'label'         => 'Галерея скриншотов',
                'name'          => 'project_gallery',
                'type'          => 'gallery',
                'min'           => 0,
                'max'           => 20,
                'mime_types'    => 'jpg,jpeg,png,webp',
                'return_format' => 'array',
            ],
        ],
        'location' => [
            [['param' => 'post_type', 'operator' => '==', 'value' => 'project']],
        ],
        'menu_order'     => 0,
        'position'       => 'normal',
        'style'          => 'seamless',
        'label_placement' => 'top',
    ]);
});

Repeater — повторяющиеся блоки данных

[
    'key'     => 'field_project_results',
    'label'   => 'Результаты проекта',
    'name'    => 'project_results',
    'type'    => 'repeater',
    'min'     => 1,
    'max'     => 10,
    'layout'  => 'table',
    'button_label' => 'Добавить результат',
    'sub_fields' => [
        [
            'key'   => 'field_result_metric',
            'label' => 'Метрика',
            'name'  => 'metric',
            'type'  => 'text',
            'placeholder' => 'Конверсия',
        ],
        [
            'key'   => 'field_result_before',
            'label' => 'До',
            'name'  => 'before',
            'type'  => 'text',
            'placeholder' => '1.2%',
        ],
        [
            'key'   => 'field_result_after',
            'label' => 'После',
            'name'  => 'after',
            'type'  => 'text',
            'placeholder' => '3.8%',
        ],
    ],
],

Вывод Repeater на фронтенде:

if (have_rows('project_results')) {
    echo '<table class="results-table">';
    echo '<thead><tr><th>Метрика</th><th>До</th><th>После</th></tr></thead><tbody>';
    while (have_rows('project_results')) {
        the_row();
        printf(
            '<tr><td>%s</td><td>%s</td><td>%s</td></tr>',
            esc_html(get_sub_field('metric')),
            esc_html(get_sub_field('before')),
            esc_html(get_sub_field('after'))
        );
    }
    echo '</tbody></table>';
}

Flexible Content — конструктор страниц

Flexible Content позволяет редактору собирать страницу из блоков разного типа — по сути внутренний page builder:

[
    'key'     => 'field_page_sections',
    'label'   => 'Секции страницы',
    'name'    => 'page_sections',
    'type'    => 'flexible_content',
    'button_label' => 'Добавить секцию',
    'layouts' => [
        'hero' => [
            'key'        => 'layout_hero',
            'name'       => 'hero',
            'label'      => 'Hero-баннер',
            'sub_fields' => [
                ['key' => 'field_hero_title',  'label' => 'Заголовок', 'name' => 'title',  'type' => 'text'],
                ['key' => 'field_hero_bg',     'label' => 'Фон',       'name' => 'bg',     'type' => 'image', 'return_format' => 'array'],
                ['key' => 'field_hero_button', 'label' => 'Кнопка',    'name' => 'button', 'type' => 'link'],
            ],
        ],
        'text_columns' => [
            'key'        => 'layout_text_columns',
            'name'       => 'text_columns',
            'label'      => 'Текст в колонках',
            'sub_fields' => [
                ['key' => 'field_tc_cols', 'label' => 'Колонки', 'name' => 'columns', 'type' => 'repeater',
                 'sub_fields' => [
                    ['key' => 'field_tc_text', 'name' => 'text', 'label' => 'Текст', 'type' => 'wysiwyg'],
                 ]],
            ],
        ],
    ],
],

Рендер:

if (have_rows('page_sections')) {
    while (have_rows('page_sections')) {
        the_row();
        $layout = get_row_layout();
        get_template_part("template-parts/sections/{$layout}");
    }
}

Условное отображение полей

ACF поддерживает conditional_logic — показывать поле только при определённом значении другого:

[
    'key'               => 'field_show_cta',
    'label'             => 'Показать CTA',
    'name'              => 'show_cta',
    'type'              => 'true_false',
    'ui'                => 1,
],
[
    'key'               => 'field_cta_text',
    'label'             => 'Текст кнопки',
    'name'              => 'cta_text',
    'type'              => 'text',
    'conditional_logic' => [
        [['field' => 'field_show_cta', 'operator' => '==', 'value' => '1']],
    ],
],

Синхронизация через JSON

ACF PRO поддерживает синхронизацию групп через файлы /acf-json/*.json. При изменении структуры через интерфейс — файл обновляется автоматически. Коммитим файлы в git, на другом окружении нажимаем «Sync» или вызываем acf_sync_field_groups().

Получение полей вне цикла

// Поле конкретной записи
$client = get_field('project_client', $post_id);

// Поле опции (option page ACF)
$phone = get_field('company_phone', 'option');

// Поле термина таксономии
$color = get_field('category_color', 'project_category_' . $term_id);

ACF — инструмент для быстрого старта. При росте проекта сложные Flexible Content с десятками layout превращаются в узкое место: запросы к wp_postmeta с JOIN-ами по 100+ строк замедляют страницы. На этом этапе стоит рассматривать кастомные таблицы или переход на headless архитектуру.