WordPress 文章添加自定义字段面板（Meta Box）完整教程

2020-11-29 · Ryan · 发表评论

在 WordPress 开发中，为文章或自定义文章类型添加自定义字段面板（Meta Box）是一项常见需求。本文将以添加“产品价格”字段为例，详细介绍从创建、保存到显示自定义字段的完整流程。

核心函数：add_meta_box

创建自定义字段面板的核心是 add_meta_box 函数，其基本语法如下：

add_meta_box( $id, $title, $callback, $post_type, $context, $priority, $callback_args );

参数说明

$id：Meta Box 的唯一标识符（ID）。
$title：显示在面板顶部的标题。
$callback：用于输出面板内容的回调函数。
$post_type：面板应用的文章类型（如 ‘post‘, ‘page‘, ‘product‘）。
$context：面板在编辑页面的显示位置（如 ‘side‘, ‘normal‘, ‘advanced‘）。
$priority：面板的显示优先级（如 ‘high‘, ‘core‘, ‘default‘, ‘low‘）。

步骤一：注册 Meta Box

首先，需要通过 add_meta_boxes 钩子注册你的 Meta Box。以下代码为 ‘product‘ 文章类型在侧边栏添加一个“产品价格”面板。

add_action( 'add_meta_boxes', 'register_product_price_meta_box' );
function register_product_price_meta_box() {
    add_meta_box(
        'product_price_meta_box', // 唯一 ID
        '产品价格', // 标题
        'render_product_price_meta_box', // 回调函数
        'product', // 文章类型
        'side', // 位置
        'low' // 优先级
    );
}

步骤二：创建回调函数（渲染表单）

回调函数负责在面板内输出 HTML 表单。务必包含安全验证字段（nonce）并处理已存储的值。

function render_product_price_meta_box( $post ) {
    // 添加安全验证字段
    wp_nonce_field( 'save_product_price_meta', 'product_price_meta_nonce' );
    // 获取已保存的值
    $price = get_post_meta( $post->ID, '_product_price', true );
    // 输出表单字段
    echo '产品价格：';
    echo '';
}

步骤三：保存 Meta Box 数据

当文章保存或更新时，需要验证并保存自定义字段的值。这是最关键的安全环节。

add_action( 'save_post', 'save_product_price_meta_box' );
function save_product_price_meta_box( $post_id ) {
    // 1. 检查 nonce 是否存在且有效
    if ( ! isset( $_POST['product_price_meta_nonce'] ) || ! wp_verify_nonce( $_POST['product_price_meta_nonce'], 'save_product_price_meta' ) ) {
        return;
    }
    // 2. 检查自动保存（避免在自动保存时处理）
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }
    // 3. 检查用户权限
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }
    // 4. 获取、清理并保存字段数据
    if ( isset( $_POST['product_price'] ) ) {
        $price = sanitize_text_field( $_POST['product_price'] );
        update_post_meta( $post_id, '_product_price', $price );
    }
}

步骤四：在前端模板中调用字段值

保存后，你可以在主题模板文件中使用 get_post_meta 函数获取并显示该值。

<?php
$price = get_post_meta( get_the_ID(), '_product_price', true );
if ( ! empty( $price ) ) {
    echo '价格：' . esc_html( $price );
}
?>

扩展：在文章列表页显示自定义字段

你还可以将自定义字段添加到后台文章列表（All Posts）的列中，方便管理。

// 1. 添加自定义列
add_filter( 'manage_product_posts_columns', 'add_product_price_admin_column' );
function add_product_price_admin_column( $columns ) {
    $columns['product_price'] = '产品价格';
    return $columns;
}
// 2. 在自定义列中填充数据
add_action( 'manage_product_posts_custom_column', 'display_product_price_in_admin_column', 10, 2 );
function display_product_price_in_admin_column( $column, $post_id ) {
    if ( $column === 'product_price' ) {
        $price = get_post_meta( $post_id, '_product_price', true );
        echo ! empty( $price ) ? esc_html( $price ) : '—';
    }
}

完整代码与使用说明

将以上所有代码片段按顺序添加到当前主题的 functions.php 文件末尾即可。请确保：

代码中的文章类型 ‘product‘ 需与你实际使用的类型一致。
字段键名（如 ‘_product_price‘）在整个代码中保持一致。
所有函数名应唯一，避免与其他插件或主题冲突。

通过以上步骤，你就能为 WordPress 文章或任何自定义文章类型稳健地添加、保存和显示自定义字段面板了。