本文详解如何在 woocommerce 订单详情表中展示商品短描述（excerpt），并基于该摘要对订单商品项进行自然排序，提供可直接复用的优化代码及关键注意事项。
本文详解如何在 woocommerce 订单详情表中展示商品短描述（excerpt），并基于该摘要对订单商品项进行自然排序，提供可直接复用的优化代码及关键注意事项。
在 WooCommerce 电商场景中，清晰呈现订单内容对客服处理、客户确认及后台分析至关重要。默认情况下，订单详情页仅显示商品名称与数量，缺乏上下文信息。通过在订单项名称前添加商品短描述（即 post_excerpt），能显著提升可读性；进一步按该摘要字母序排序，则使同类商品（如“配件”“套装”“说明书”等标准化短描述）集中呈现，便于快速核查。
✅ 正确显示商品短描述
以下代码通过 woocommerce_order_item_name 钩子，在订单详情页、邮件通知等所有调用该钩子的位置注入短描述。我们做了三项关键优化：
- 使用 $item->get_product_id() 安全获取产品 ID（兼容变体、虚拟商品等）；
- 调用 get_the_excerpt($product_id) 获取已过滤的短描述（自动截断、支持 HTML 过滤）；
- 增加非空判断，避免空白分隔符污染显示。
function filter_woocommerce_order_item_name( $item_name, $item, $is_visible ) {
$product_id = $item->get_product_id();
$excerpt = get_the_excerpt( $product_id );
if ( ! empty( $excerpt ) ) {
return esc_html( $excerpt ) . ' — ' . $item_name;
}
return $item_name;
}
add_filter( 'woocommerce_order_item_name', 'filter_woocommerce_order_item_name', 10, 3 );⚠️ 注意作用域：该钩子在前台订单页（/my-account/view-order/xxx/）、后台订单编辑页及所有 WooCommerce 邮件模板中均会触发。若仅需在前台订单详情页显示，建议结合条件判断：
if ( is_wc_endpoint_url( 'view-order' ) || is_admin() && isset( $_GET['post'] ) ) { // 仅限订单详情页或后台订单编辑页 }
✅ 按短描述自然排序订单项
原始尝试失败的核心原因在于：$a['excerpt'] 是未定义键——woocommerce_order_get_items 返回的 $items 数组中每个元素是 WC_Order_Item_Product 对象（或数组形式的兼容结构），不预先包含 excerpt 字段。必须在排序回调中实时获取。
以下代码使用 woocommerce_order_get_items 钩子（优先级 10，接收 $items, $order, $types 三参数），利用 uasort() 保持键值关联，并通过 strnatcmp() 实现“自然排序”（如 v1.10 排在 v1.2 之后，符合人类直觉）：
function filter_woocommerce_order_get_items( $items, $order, $types ) {
uasort( $items, function( $a, $b ) {
$excerpt_a = get_the_excerpt( $a->get_product_id() ?? $a['product_id'] ?? 0 );
$excerpt_b = get_the_excerpt( $b->get_product_id() ?? $b['product_id'] ?? 0 );
return strnatcmp( $excerpt_a, $excerpt_b );
} );
return $items;
}
add_filter( 'woocommerce_order_get_items', 'filter_woocommerce_order_get_items', 10, 3 );? 兼容性说明：WooCommerce 7.0+ 中 $items 元素为 WC_Order_Item 对象（推荐用 $a->get_product_id()）；旧版本可能返回关联数组（回退使用 $a['product_id']）。上述代码已做双重兼容处理，确保跨版本稳定运行。
? 总结与最佳实践
- ✅ 显示逻辑：短描述应前置且带分隔符（如 —），增强语义区分；务必 esc_html() 防 XSS（尤其当短描述含用户输入内容时）；
- ✅ 排序逻辑：禁止预存字段到 $items 数组（易引发缓存/并发问题），始终实时计算 excerpt；
- ✅ 性能提示：get_the_excerpt() 内部已启用对象缓存，单次订单内多次调用无额外 DB 查询开销；
- ✅ 扩展建议：如需按其他字段（如 SKU、分类、自定义字段）排序，只需将 get_the_excerpt(...) 替换为对应获取逻辑即可复用该排序框架。
将两段代码加入主题的 functions.php 或专用插件中，刷新订单详情页即可立即生效——简洁、健壮、面向生产环境。
