WooCommerce显示订单产品自定义元数据

本教程旨在解决 WooCommerce 管理员订单详情页中，产品自定义元数据（如交货时间）随产品更新而变化的问题。我们将介绍如何通过在订单创建时将产品元数据存储到订单行项目，并修改管理员订单详情页的显示逻辑，确保历史订单始终展示下单时的准确信息，避免数据回溯性变更。

挑战：WooCommerce 中产品元数据的动态性问题

在 WooCommerce 中，当我们需要在管理员订单详情页显示产品的自定义元数据（例如“交货时间”、“库存状态”等）时，一个常见的问题是，如果直接使用 get_post_meta() 结合产品 ID 来获取这些信息，那么当产品的元数据在未来被更新时，所有历史订单中显示的相关信息也会随之改变。这会导致历史订单数据与实际下单时的状态不符，影响数据准确性和可追溯性。

例如，如果一个产品最初显示“3天内发货”，而客户在此时下单。几天后，产品更新为“立即发货”。如果您的代码直接从产品获取元数据，那么即使是之前的订单，也会错误地显示“立即发货”，而非下单时的“3天内发货”。

解决方案核心：将元数据绑定至订单行项目

为了解决上述问题，核心思路是在订单创建时，将产品的当前自定义元数据“快照”下来，并存储到对应的订单行项目（Order Line Item）中，而不是仅仅依赖于产品本身的元数据。当需要在管理员订单详情页显示这些信息时，我们再从订单行项目而非产品本身获取。这样，即使产品元数据发生变化，已完成订单的行项目元数据依然保持不变，确保了历史数据的准确性。

本教程将分两步实现此目标：

1. 在结账时捕获并存储产品元数据到订单行项目。
2. 在管理员订单详情页显示这些存储在订单行项目中的元数据。

步骤一：在结账时捕获并存储产品元数据

我们需要利用 woocommerce_checkout_create_order_line_item 钩子，在订单行项目创建时，将产品的自定义元数据获取并保存到该行项目。

/**
 * 在订单行项目创建时，将产品自定义元数据存储到订单行项目。
 *
 * @param WC_Order_Item_Product $item          订单行项目对象。
 * @param string                $cart_item_key 购物车项目键。
 * @param array                 $values        购物车项目值。
 * @param WC_Order              $order         订单对象。
 */
function action_woocommerce_checkout_create_order_line_item( $item, $cart_item_key, $values, $order ) {
    // 获取 WC_Product 实例对象
    $product = $item->get_product();

    // 检查产品是否存在且有效
    if ( ! $product ) {
        return;
    }

    // 获取产品自定义元数据的值，此处以 'prefix-tempiconsegna' 为例
    $value = $product->get_meta( 'prefix-tempiconsegna' );

    // 如果值不为空，则将其存储到订单行项目
    if ( ! empty( $value ) ) {
        $item->update_meta_data( 'prefix-tempiconsegna', $value );
    }
}
add_action( 'woocommerce_checkout_create_order_line_item', 'action_woocommerce_checkout_create_order_line_item', 10, 4 );

代码解释：

• action_woocommerce_checkout_create_order_line_item 函数会在每个订单行项目创建时被调用。
• $item->get_product() 用于获取当前订单行项目对应的 WC_Product 对象。
• $product->get_meta( 'prefix-tempiconsegna' ) 从产品中获取名为 prefix-tempiconsegna 的自定义元数据值。请确保您的产品自定义元数据键名与此处的 'prefix-tempiconsegna' 保持一致。
• $item->update_meta_data( 'prefix-tempiconsegna', $value ) 将获取到的值存储到当前的订单行项目。这样，这个值就成为了订单的一部分，不再与产品本身的元数据动态关联。
• ! empty( $value ) 检查确保只有非空值才会被存储。

步骤二：在管理员订单详情页显示订单行项目元数据

在订单行项目保存了所需的元数据后，我们需要修改 WooCommerce 管理员订单详情页的显示逻辑，以便从订单行项目获取并展示这些数据。这同样分为两部分：添加自定义列标题和填充自定义列内容。

2.1 添加自定义列标题

使用 woocommerce_admin_order_item_headers 钩子在订单商品表格中添加一个新的列标题。

/**
 * 在 WooCommerce 管理员订单详情页的商品表格中添加自定义列标题。
 *
 * @param WC_Order $order 订单对象。
 */
function action_woocommerce_admin_order_item_headers( $order ) {
    // 设置列名称，使用 __() 函数支持国际化
    $column_name = __( 'Tempi Consegna', 'woocommerce' );

    // 输出列标题
    echo '' . $column_name . '';
}
add_action( 'woocommerce_admin_order_item_headers', 'action_woocommerce_admin_order_item_headers', 10, 1 );

代码解释：

• action_woocommerce_admin_order_item_headers 函数会在管理员订单详情页的商品表格头部被调用。
• __( 'Tempi Consegna', 'woocommerce' ) 用于设置列标题，并支持 WooCommerce 的文本域进行翻译。
• echo '' . $column_name . ''; 输出 HTML 表格头部单元格。my-custom-delivery-time 是一个可选的CSS类名，方便后续样式调整。

2.2 填充自定义列内容

使用 woocommerce_admin_order_item_values 钩子为新添加的列填充对应订单行项目的数据。

/**
 * 在 WooCommerce 管理员订单详情页的商品表格中填充自定义列内容。
 *
 * @param WC_Product            $_product 产品对象（在当前上下文可能为null）。
 * @param WC_Order_Item_Product $item     订单行项目对象。
 * @param int                   $item_id  订单行项目ID。
 */
function action_woocommerce_admin_order_item_values( $_product, $item, $item_id ) {
    // 仅针对 "line_item" 类型的项目处理，避免潜在错误
    // 这可以防止处理运费、税费等非产品行项目
    if ( ! $item->is_type('line_item') ) {
        return;
    }

    // 从订单行项目获取存储的元数据值
    $value = $item->get_meta( 'prefix-tempiconsegna' );

    // 如果值不为空，则显示；否则显示默认提示
    if ( ! empty( $value ) ) {
        echo '' . $value . '';
    } else {
        echo '' . __( 'Meta not found!', 'woocommerce' ) . '';        
    }
}
add_action( 'woocommerce_admin_order_item_values', 'action_woocommerce_admin_order_item_values', 10, 3 );

代码解释：

• action_woocommerce_admin_order_item_values 函数会为订单中的每个项目（包括产品、运费、税费等）调用。
• if ( ! $item->is_type('line_item') ) return; 是一个重要的检查，它确保我们只处理实际的产品行项目，避免对运费、税费等其他类型的行项目造成错误或不必要的输出。
• $item->get_meta( 'prefix-tempiconsegna' ) 从当前订单行项目获取之前存储的自定义元数据值。
• 根据获取到的值，输出相应的表格单元格内容。如果元数据为空，提供一个默认的提示信息，提升用户体验。

注意事项与最佳实践

• 一致的元数据键名： 确保在存储和获取元数据时使用的键名（例如 prefix-tempiconsegna）完全一致。
• 代码放置位置： 建议将上述所有代码片段放置在您的主题的 functions.php 文件中，或者创建一个自定义插件来管理这些功能，以确保代码的模块化和在主题更新时的持久性。
• 国际化： 使用 __() 函数处理所有用户可见的字符串，以便您的网站能够支持多语言。
• 错误处理： 在获取元数据时，进行 ! empty() 检查是良好的实践，可以避免在元数据不存在时出现错误或显示空值。同时，$item->is_type('line_item') 检查可以增强代码的健壮性。
• 兼容性： 确保您的代码与您使用的 WooCommerce 版本兼容。通常，这些核心钩子在不同版本间保持稳定。
• 性能： 此方法对性能影响极小，因为它只在订单创建和管理员查看订单时执行。

总结

通过将产品自定义元数据在订单创建时“快照”并存储到订单行项目，我们成功地解决了 WooCommerce 管理员订单详情页中元数据随产品更新而变化的问题。这种方法确保了历史订单数据的准确性和一致性，为商家提供了更可靠的订单管理视图。这种将动态数据转化为静态快照的策略，在处理需要时间点精确性的业务数据时，是非常有效且推荐的做法。