如何在自定义文章类型的ACF下拉框中显示分类描述字段

ACF默认的Taxonomy（分类法）字段不会自动渲染分类的Description字段，通过ACF原生钩子即可实现需求，全程不需要开放分类管理页权限，完全兼容Publishpress Capabilities Manager配置的受限用户角色。

你当前注册分类法的代码无需额外修改，直接通过以下扩展方案即可实现效果： #

下拉选项直接追加描述（适配现有下拉选择交互） #

将以下代码加入当前主题的functions.php文件，或自定义功能插件中，代码默认仅对你注册的clubregions分类法生效：

// 为ACF分类字段选项追加分类描述
add_filter('acf/fields/taxonomy/result', 'append_tax_description_to_acf_option', 10, 4);
function append_tax_description_to_acf_option($text, $term, $field, $post_id) {
    // 非目标分类法直接返回原文本
    if ($term->taxonomy !== 'clubregions') {
        return $text;
    }
    // 有描述时在分类名后追加浅灰色说明文字
    if (!empty($term->description)) {
        $text .= sprintf(
            ' <span style="color:#919191;font-weight:normal;">— %s</span>',
            esc_html($term->description)
        );
    }
    return $text;
}

该钩子是ACF官方提供的合法扩展点，会自动继承当前用户的权限校验逻辑，不会出现越权访问问题，下拉框、单选列表、多选列表形式的分类字段都可以用这段代码修改选项文本。 #

可选优化：选中分类后展示完整描述 #

如果担心下拉选项内文字过长影响选择效率，可以追加以下代码，用户选中对应分类后，在选择框下方独立展示完整分类说明：

// 分类选中后实时展示对应描述
add_action('acf/input/admin_footer', 'render_selected_tax_description', 10);
function render_selected_tax_description() {
    global $current_screen;
    // 仅在clubdetails文章类型编辑页加载脚本
    if ($current_screen->post_type !== 'clubdetails') {
        return;
    }
    // 提前拉取所有分类的描述，缓存到前端
    $terms = get_terms([
        'taxonomy'   => 'clubregions',
        'hide_empty' => false,
    ]);
    $term_map = [];
    foreach ($terms as $term) {
        $term_map[$term->term_id] = esc_js($term->description);
    }
    ?>
    <script>
    jQuery(document).ready(function($){
        const termDescMap = <?php echo json_encode($term_map); ?>;
        // 替换为你自己的ACF分类字段对应选择器
        const fieldSelector = '.acf-field-替换为你的字段key';

        $(document).on('change', `${fieldSelector} select`, function(){
            const selectedId = parseInt($(this).val());
            let $tipBox = $(this).siblings('.tax-desc-notice');
            if (!$tipBox.length) {
                $tipBox = $('<div class="tax-desc-notice" style="margin-top:8px;padding:7px 10px;background:#f0f6fc;border-left:3px solid #2271b1;font-size:12px;color:#50575e;"></div>');
                $(this).after($tipBox);
            }
            if (selectedId && termDescMap[selectedId]) {
                $tipBox.text(termDescMap[selectedId]).show();
            } else {
                $tipBox.hide();
            }
        }).trigger('change');
    });
    </script>
    <?php
}

使用注意：将代码中acf-field-替换为你的字段key替换为实际ACF字段的选择器，字段key可在ACF字段编辑页右上角开启“显示字段键”选项后查看，格式为field_xxxxxx，最终选择器格式为.acf-field-field_xxxxxx。

配置注意事项 #

你当前注册clubregions分类法时设置了'show_in_rest' => false，如果后续切换为古腾堡块编辑器编辑clubdetails类型文章，需要将该参数改为true，否则ACF在REST模式下无法拉取分类数据；经典编辑器场景下不受该参数影响，上述代码可直接运行。

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