如何在自定义WordPress主题的Classic Editor中添加文章自定义布局选项？

首先纠正你的误解：不需要直接在single.php里创建布局选项，single.php是前端显示文章的模板，而编辑器的自定义选项属于后台功能，需要通过WordPress的自定义字段（Meta Box）+ 媒体库调用API来实现，以下是具体步骤：

1. 创建自定义Meta Box（后台编辑器区域） #

通过PHP在主题的functions.php里注册Meta Box，把布局选项和图片上传控件加到经典编辑器下方：

// 注册自定义Meta Box
add_action('add_meta_boxes', 'custom_layout_meta_box');
function custom_layout_meta_box() {
    add_meta_box(
        'custom_layout_box', // Meta Box ID
        '自定义布局选项', // 标题
        'render_custom_layout_box', // 渲染回调函数
        'post', // 应用到文章类型
        'normal', // 位置（编辑器下方）
        'default' // 优先级
    );
}

// 渲染Meta Box内容
function render_custom_layout_box($post) {
    // 安全验证字段，防止恶意提交
    wp_nonce_field('save_custom_layout', 'custom_layout_nonce');
    
    // 获取已保存的布局数据
    $saved_layout = get_post_meta($post->ID, '_custom_layout', true);
    $selected_layout = isset($saved_layout['type']) ? $saved_layout['type'] : '';
    $image_id = isset($saved_layout['image_id']) ? $saved_layout['image_id'] : '';
    $image_url = $image_id ? wp_get_attachment_url($image_id) : '';
    
    // 布局选择下拉框
    echo '<p><label for="layout_type">选择布局：</label>';
    echo '<select id="layout_type" name="layout_type">';
    echo '<option value="">-- 选择布局 --</option>';
    echo '<option value="full_width_image" ' . selected($selected_layout, 'full_width_image', false) . '>全屏图片</option>';
    echo '<option value="two_column_image" ' . selected($selected_layout, 'two_column_image', false) . '>两列图片</option>';
    echo '</select></p>';
    
    // 图片上传区域
    echo '<div id="image_upload_container" style="display: ' . ($selected_layout ? 'block' : 'none') . ';">';
    echo '<p><label>上传图片：</label></p>';
    echo '<img id="preview_image" src="' . esc_url($image_url) . '" style="max-width: 200px; margin-bottom: 10px;" ' . (!$image_url ? 'hidden' : '') . '>';
    echo '<button type="button" id="upload_image_btn" class="button">添加图片</button>';
    echo '<input type="hidden" id="image_id" name="image_id" value="' . esc_attr($image_id) . '">';
    echo '</div>';
}

2. 添加JS调用媒体库 #

在主题里添加自定义JS，让“添加图片”按钮能打开WordPress媒体库：

// 可放在主题的js文件里，或通过wp_enqueue_script加载
jQuery(document).ready(function($) {
    var mediaUploader;
    
    $('#upload_image_btn').click(function(e) {
        e.preventDefault();
        if (mediaUploader) {
            mediaUploader.open();
            return;
        }
        
        mediaUploader = wp.media({
            title: '选择图片',
            button: {
                text: '使用此图片'
            },
            multiple: false // 单张图片上传
        });
        
        mediaUploader.on('select', function() {
            var attachment = mediaUploader.state().get('selection').first().toJSON();
            $('#image_id').val(attachment.id);
            $('#preview_image').attr('src', attachment.url).show();
        });
        
        mediaUploader.open();
    });
    
    // 切换布局时显示/隐藏图片上传区域
    $('#layout_type').change(function() {
        var selected = $(this).val();
        $('#image_upload_container').toggle(!!selected);
    });
});

记得在functions.php里注册并加载这个JS文件：

add_action('admin_enqueue_scripts', 'custom_layout_admin_scripts');
function custom_layout_admin_scripts($hook) {
    // 只在文章编辑页面加载
    if ($hook !== 'post.php' && $hook !== 'post-new.php') {
        return;
    }
    wp_enqueue_script('custom-layout-js', get_template_directory_uri() . '/js/custom-layout.js', array('jquery', 'media-upload', 'thickbox'), '1.0', true);
    wp_enqueue_style('thickbox');
}

3. 保存布局数据到文章Meta #

在functions.php里添加保存逻辑：

add_action('save_post', 'save_custom_layout_data');
function save_custom_layout_data($post_id) {
    // 验证权限和安全字段
    if (!isset($_POST['custom_layout_nonce']) || !wp_verify_nonce($_POST['custom_layout_nonce'], 'save_custom_layout')) {
        return;
    }
    if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
        return;
    }
    if (!current_user_can('edit_post', $post_id)) {
        return;
    }
    
    // 保存布局数据
    $layout_data = array(
        'type' => isset($_POST['layout_type']) ? sanitize_text_field($_POST['layout_type']) : '',
        'image_id' => isset($_POST['image_id']) ? intval($_POST['image_id']) : ''
    );
    update_post_meta($post_id, '_custom_layout', $layout_data);
}

4. 在single.php里渲染布局 #

回到single.php，读取保存的Meta数据，根据布局类型渲染对应的前端样式：

// 获取布局数据
$custom_layout = get_post_meta(get_the_ID(), '_custom_layout', true);
if ($custom_layout && !empty($custom_layout['type'])) {
    switch ($custom_layout['type']) {
        case 'full_width_image':
            $image_url = wp_get_attachment_url($custom_layout['image_id']);
            if ($image_url) {
                echo '<div class="full-width-image"><img src="' . esc_url($image_url) . '" alt="全屏图片"></div>';
            }
            break;
        case 'two_column_image':
            $image_url = wp_get_attachment_url($custom_layout['image_id']);
            if ($image_url) {
                echo '<div class="two-column-image"><div class="column"><img src="' . esc_url($image_url) . '" alt="两列图片"></div><div class="column">这里可添加第二列内容，或扩展为多图片上传</div></div>';
            }
            break;
    }
}

然后在主题的CSS里添加对应的布局样式：

.full-width-image img {
    width: 100%;
    height: auto;
}
.two-column-image {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 20px;
}
.two-column-image .column img {
    width: 100%;
    height: auto;
}

关键术语说明 #

• Meta Box：WordPress后台用于添加自定义字段的容器，是实现编辑器扩展的核心方式
• Post Meta：存储文章自定义数据的数据库字段，通过get_post_meta和update_post_meta操作
• Media Library API：WordPress提供的用于调用媒体库的JS接口，无需自行开发上传功能

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