ACF Blocks: Initial Gutenberg Preview Empty Despite Default Field Values (Timber + render_callback)

从 GutenbergHelper.php 开始，重点查看 acfRenderCallback()，然后追踪从 BlockLinkTiles/functions.php 进行的注册，以及 BlockLinkTiles/index.twig 所需的数据。在 Gutenberg 编辑器中复现首次插入，并确定受支持的默认值路径；当初始渲染无需与字段交互即可接收已配置的值，且后续渲染仍保持正确时，即表示完成。

Describe the bug
When registering a custom ACF block using acf_register_block_type() with a render_callback, the Gutenberg editor preview is blank on the very first load after inserting the block — even though default field values are defined. The data object passed to render_callback is empty on this initial render. As soon as any field value is changed in the inspector controls, the preview updates correctly and continues to work from that point on.

To Reproduce

1. Register a custom ACF block using acf_register_block_type() with a render_callback
2. Define default values for the block's fields in ACF
3. Open a page or post in the Gutenberg editor
4. Insert the custom block for the first time
5. Observe that the block preview is blank — the render_callback receives an empty data object

Expected behavior
On initial insertion of the block into the editor, the render_callback should receive the defined default field values and render an accurate preview immediately, without requiring any user interaction.

Screenshots or Video
https://www.youtube.com/watch?v=ldLwg3o8PPY

Code

We use a central GutenbergHelper class to register and render all ACF blocks for Gutenberg.

GutenbergHelper.php — handles block registration and the shared render_callback:

<?php

namespace Flynt\Utils;

use ACFComposer\ACFComposer;
use Flynt\ComponentManager;
use Timber\Timber;

class GutenbergHelper
{
    public static function acfRenderCallback($block, $content, $is_preview = false, $post_id = 0)
    {
        $componentName = str_replace('acf/', '', $block['name']);

        $componentManager = ComponentManager::getInstance();
        $filePath = $componentManager->getComponentFilePath($block['filePath'], 'index.twig');

        $relativeFilePath = ltrim(str_replace(get_template_directory(), '', $filePath), '/');

        if (!is_file($filePath)) {
            trigger_error("Template not found: {$filePath}", E_USER_WARNING);
            return '';
        }

        $fields = \get_fields() ?? [];
        $fields['is_preview'] = $is_preview;

        $fields = apply_filters(
           "Flynt/addComponentData?name={$componentName}",
            $fields,
            $componentName
        );

        $fields['block'] = $block;

        Timber::render($relativeFilePath, $fields);
    }

    public static function registerGutenbergBlock($component)
    {
        ACFComposer::registerFieldGroup([
            'name' => $component['name'],
            'title' => $component['label'],
            'fields' => $component['sub_fields'] ?? [],
            'location' => array(
                array(
                    array(
                        'param' => 'block',
                        'operator' => '==',
                        'value' => 'acf/' . strtolower($component['name']),
                    ),
                ),
            ),
        ]);

        if (function_exists('acf_register_block_type')) {
            $componentName = $component['name'];
            $componentLabel = $component['label'] ?? $componentName;
            $gutenbergConfig = self::getComponentGutenbergConfig($componentName);

            $blockConfig = array(
                'name' => $componentName,
                'title' => $componentLabel,
                'filePath' => $component['filePath'] ?? $componentLabel,
                'render_callback' => [self::class, 'acfRenderCallback'],
                'category' => $gutenbergConfig['category'] ?? 'custom-blocks',
                'icon' => $gutenbergConfig['icon'] ?? 'grid-view',
                'keywords' => $gutenbergConfig['keywords'] ?? ['content'],
                'supports' => $gutenbergConfig['supports'] ?? array(
                    'align' => array( 'wide', 'full' ),
                    'anchor' => true,
                    'customClassName' => true,
                    'color' => array('text' => true, 'background' => true),
                    'layout' => array('allowInheriting' => true),
                    'typography' => array(
                        'fontSize' => false,
                        'lineHeight' => false,
                        'fontWeight' => false,
                    ),
                    'spacing' => array('margin' => true, 'padding' => true),
                ),
            );

            acf_register_block_type($blockConfig);
        }
    }

    private static function getComponentGutenbergConfig($componentName): array
    {
        $functionName = "Flynt\\Components\\{$componentName}\\getGutenbergConfig";
        if (function_exists($functionName)) {
            return call_user_func($functionName);
        }
        return [];
    }
}

BlockLinkTiles/functions.php — example block registration with field definitions including default_value:

<?php

namespace Flynt\Components\BlockLinkTiles;

use Flynt\FieldVariables;
use Flynt\Utils\GutenbergHelper;

function getACFLayout()
{
    return [
        'name' => 'blockLinkTiles',
        'label' => __('Link Tiles', 'flynt'),
        'filePath' => 'BlockLinkTiles',
        'sub_fields' => [
            [
                'label' => __('Content', 'flynt'),
                'name' => 'contentTab',
                'type' => 'tab',
                'placement' => 'top',
                'endpoint' => 0,
            ],
            [
                'label' => __('Color', 'flynt'),
                'name' => 'color',
                'type' => 'select',
                'choices' => FieldVariables\getThemeColorChoices(),
                'default_value' => 'orange',
                'wrapper' => ['width' => 100],
            ],
            [
                'label' => __('Links', 'flynt'),
                'name' => 'links',
                'type' => 'repeater',
                'layout' => 'block',
                'min' => 3,
                'max' => 4,
                'sub_fields' => [
                    [
                        'label' => __('Label', 'flynt'),
                        'name' => 'label',
                        'type' => 'text',
                        'default_value' => 'Title',
                    ],
                    [
                        'label' => __('Link', 'flynt'),
                        'name' => 'link',
                        'type' => 'link',
                        'required' => 0,
                    ],
                ],
            ],
        ],
    ];
}

function getGutenbergConfig(): array
{
    return [
        'icon' => 'screenoptions',
        'keywords' => ['links', 'tiles', 'gradient', 'cta'],
        'category' => 'custom-blocks',
    ];
}

add_action('acf/init', function () {
    if (function_exists('acf_register_block_type')) {
        $component = getACFLayout();
        GutenbergHelper::registerGutenbergBlock($component);
    }
});

BlockLinkTiles/index.twig — Timber template, relies on links and color being present in the context:

{% set componentOptions = {
    name: 'BlockLinkTiles',
    loadOn: 'visible',
    class: 'has-global-padding'
} %}

{% set content %}
  <div class="block-link-tiles-wrapper">
    {% if links and links|length > 0 %}
      {% set total = links|length %}
      <div class="flex flex-col gap-sm md:flex-row">
        {% for row in links %}
          {% include 'Components/BlockLinkTiles/Partials/_tile.twig' with {
            link: row.link,
            label: row.label|default(row.link.title),
            index: loop.index0,
            total: total,
            gradientSlugDesktop: gradientSlugDesktop|default('dark-sunset'),
            gradientSlugMobile: gradientSlugMobile|default('dark-sunset-vertical')
          } %}
        {% endfor %}
      </div>
    {% endif %}
  </div>
{% endset %}

{% include 'Components/_Containers/FlyntComponent.twig' with {
    content: content,
    componentOptions: componentOptions
} %}

Our question: what is the correct, supported way to access field default values inside render_callback on the very first render of a newly inserted block, before any data has been saved or interacted with?

Version Information:

• WordPress Version: 6.9.4
• PHP Version: 8.3
• ACF Version: ACF PRO 6.8.0.1
• Timber 2.2.0 for templating
• Browser: Brave 1.88.136

Additional context

• The block renders correctly on the website frontend
• The issue only occurs on the very first render after inserting the block in the editor — subsequent loads of an already-saved block work fine