Rank Math自定义字段无法在后台元框预览问题求助

问题分析 #

当前代码可正常在前端输出ACF选项页字段值，但后台Rank Math元框预览失效，核心原因包括：

• Rank Math后台预览时，自定义变量的参数解析逻辑未适配
• 回调函数在AJAX预览上下文里未正确获取ACF选项值
• 缺少Rank Math预览所需的参数定义支持

修改后的代码 #

add_action( 'rank_math/vars/register_extra_replacements', function(){
    rank_math_register_var_replacement(
        'op_shortcode',
        [
            'name'        => esc_html__( 'OP ACF Field', 'rank-math' ),
            'description' => esc_html__( 'Custom ACF field from ACF options page.', 'rank-math' ),
            'variable'    => 'op_shortcode',
            'example'     => esc_html__( 'Chrisad field value', 'rank-math' ),
            'args'        => [
                'field' => [
                    'name'        => esc_html__( 'Field Name', 'rank-math' ),
                    'description' => esc_html__( 'ACF field key/name from options page', 'rank-math' ),
                    'type'        => 'string',
                    'required'    => true,
                ]
            ]
        ],
        'get_op_shortcode_callback'
    );
});

function get_op_shortcode_callback( $args ) {
    // 兼容AJAX预览上下文，确保ACF函数可用
    if ( ! function_exists( 'get_field' ) ) {
        return '';
    }
    
    // 获取传递的字段名参数
    $field_name = isset( $args['field'] ) ? $args['field'] : '';
    if ( empty( $field_name ) ) {
        return '';
    }
    
    // 从ACF选项页读取字段值
    $field_value = get_field( $field_name, 'option', true );
    return $field_value ? $field_value : '';
}

关键改动说明 #

• 标准化参数定义：通过args字段明确声明参数规则，让Rank Math后台能正确识别并传递字段名，解决预览时参数解析失败的问题
• AJAX上下文兼容：添加ACF函数存在性判断，避免预览请求中因函数未加载导致报错
• 参数校验与返回值处理：增加字段名非空校验，确保始终返回有效字符串，适配Rank Math预览的渲染逻辑

使用方法 #

在Rank Math元框中，以%op_shortcode(field=your-field-name)%格式调用自定义字段，将your-field-name替换为ACF选项页的目标字段名/键即可。

额外排查步骤 #

1. 确认ACF选项页已正确创建，字段名与调用时的名称完全匹配
2. 刷新后台页面，清除Rank Math缓存（路径：Rank Math > Status & Tools > Database Tools > Clear Transients）
3. 临时禁用非必要插件，排查是否存在插件冲突

内容的提问来源于stack exchange，提问作者user20278472