在woocommerce的日常运营中，有时我们需要在后台订单详情页面添加一些自定义信息，例如车辆服务中的“总里程数”。这些信息不仅需要显示，更重要的是能够被编辑并持久化存储。本教程将分步介绍如何实现这一功能，包括字段的添加、数据的保存和数据的显示。
在WooCommerce后台订单页面添加自定义可编辑字段
要在WooCommerce后台订单详情页的特定位置添加一个可编辑的自定义文本输入框，我们可以利用WooCommerce提供的动作钩子woocommerce_admin_order_data_after_order_details。这个钩子允许我们在订单详情区域的特定位置插入自定义内容。woocommerce_wp_text_input函数是WooCommerce提供的一个便捷工具，用于生成标准化的文本输入字段。
以下代码片段应添加到您主题的functions.php文件或自定义插件中：
/**
* 在WooCommerce后台订单详情页添加自定义可编辑字段
*
* @param WC_Order $order 当前订单对象
*/
add_action( 'woocommerce_admin_order_data_after_order_details', 'add_editable_custom_order_field', 12, 1 );
function add_editable_custom_order_field( $order ) {
// 获取当前订单的自定义字段值，如果不存在则为空
$custom_km_value = get_post_meta( $order->get_id(), 'custom_km', true );
// 使用 woocommerce_wp_text_input 创建一个可编辑的文本输入框
woocommerce_wp_text_input( array(
'id' => 'custom_km', // 字段的唯一ID，用于保存和检索数据
'label' => __( "总里程数:", "woocommerce" ), // 字段的显示标签
'value' => $custom_km_value, // 预填充字段的值，确保编辑时显示已有数据
'wrapper_class' => 'form-field-wide', // CSS类，使字段占据完整宽度
'description' => __( '输入车辆服务的总里程数。', 'woocommerce' ), // 字段描述
) );
}代码解析：
- add_action('woocommerce_admin_order_data_after_order_details', ...): 这是WooCommerce提供的一个钩子，用于在订单详情部分之后插入内容。
- $order: 钩子传递的参数，是当前的WC_Order对象，通过它可以获取订单ID等信息。
- get_post_meta($order->get_id(), 'custom_km', true): 这是关键一步，用于从数据库中检索名为custom_km的自定义字段的当前值。这确保了当您编辑一个已存在的订单时，之前保存的里程数能够正确显示在输入框中。
- woocommerce_wp_text_input(): 一个辅助函数，用于生成标准的WooCommerce后台输入框。
- id: 字段的唯一标识符，建议使用有意义且独特的名称。
- label: 字段旁边显示的文本标签。
- value: 输入框的默认值。在这里，我们传入从数据库中获取的现有值。
- wrapper_class: 用于控制字段样式和布局的CSS类。
保存自定义字段数据
仅仅在页面上显示输入框是不够的，我们还需要确保当订单更新时，用户输入的数据能够被保存到数据库中。WooCommerce提供了woocommerce_process_shop_order_meta动作钩子，它在订单数据保存时触发。我们可以利用这个钩子来捕获并保存我们的自定义字段数据。
/**
* 保存WooCommerce后台订单页面的自定义字段数据
*
* @param int $order_id 当前订单的ID
*/
add_action( 'woocommerce_process_shop_order_meta', 'save_custom_order_field_data' );
function save_custom_order_field_data( $order_id ) {
// 检查是否通过POST请求提交了 'custom_km' 字段
if ( isset( $_POST['custom_km'] ) ) {
// 使用 wc_clean() 对数据进行清理和安全处理，防止XSS攻击
$custom_km_value = wc_clean( $_POST['custom_km'] );
// 使用 update_post_meta() 将数据保存到数据库
update_post_meta( $order_id, 'custom_km', $custom_km_value );
}
}代码解析：
- add_action('woocommerce_process_shop_order_meta', ...): 当WooCommerce处理并保存订单元数据时，此钩子会被触发。
- $order_id: 钩子传递的参数，是当前正在保存的订单的ID。
- isset($_POST['custom_km']): 检查表单提交的数据中是否存在名为custom_km的字段。这是确保数据存在的最佳实践。
- wc_clean($_POST['custom_km']): 非常重要！ wc_clean()是WooCommerce提供的一个安全函数，用于清理用户输入的数据，移除潜在的恶意内容（如HTML标签、脚本等），防止跨站脚本（XSS）攻击。在将任何用户输入保存到数据库之前，务必进行数据清理。
- update_post_meta($order_id, 'custom_km', $custom_km_value): 这是WordPress核心函数，用于向指定文章（在此处是订单，因为WooCommerce订单在底层是自定义文章类型）添加或更新自定义字段（元数据）。如果该字段已存在，则更新其值；如果不存在，则添加该字段。
在订单详情页显示已保存的自定义数据
除了可编辑的输入框外，您可能还希望在订单详情页的其他位置（例如账单地址下方）以只读形式显示已保存的自定义数据。这可以通过另一个WooCommerce钩子实现，例如woocommerce_admin_order_data_after_billing_address。
瑞志企业建站系统(ASP版)2.2
下载
支持模板化设计，基于标签调用数据 支持N国语言，并能根据客户端自动识别当前语言 支持扩展现有的分类类型，并可修改当前主要分类的字段 支持静态化和伪静态 会员管理功能，询价、订单、收藏、短消息功能 基于组的管理员权限设置 支持在线新建、修改、删除模板 支持在线管理上传文件 使用最新的CKEditor作为后台可视化编辑器 支持无限级分类及分类的移动、合并、排序 专题管理、自定义模块管理 支持缩略图和图
/**
* 在WooCommerce后台订单详情页显示已保存的自定义里程数据
*
* @param WC_Order $order 当前订单对象
*/
add_action( 'woocommerce_admin_order_data_after_billing_address', 'display_custom_distance_km', 10, 1 );
function display_custom_distance_km( $order ) {
// 获取已保存的自定义里程数据
$custom_km = get_post_meta( $order->get_ID(), 'custom_km', true );
// 如果数据存在，则显示
if ( ! empty( $custom_km ) ) {
echo '总里程数:
' . esc_html( $custom_km ) . ' 公里
';
}
}代码解析：
- add_action('woocommerce_admin_order_data_after_billing_address', ...): 此钩子用于在账单地址信息之后插入内容。您可以根据需求选择其他钩子来调整显示位置。
- get_post_meta($order->get_ID(), 'custom_km', true): 再次使用此函数来检索已保存的custom_km值。true参数确保返回单个值而不是数组。
- esc_html($custom_km): 推荐！ 在将数据输出到HTML中时，使用esc_html()对数据进行转义是良好的安全实践，可以防止潜在的XSS漏洞。
- if (!empty($custom_km)): 仅当自定义字段有值时才显示，避免显示空行。
完整代码示例
将以上所有代码片段合并，并将其放置在您主题的functions.php文件或自定义插件中，即可实现完整的自定义字段功能：
get_id(), 'custom_km', true );
// 使用 woocommerce_wp_text_input 创建一个可编辑的文本输入框
woocommerce_wp_text_input( array(
'id' => 'custom_km', // 字段的唯一ID，用于保存和检索数据
'label' => __( "总里程数:", "woocommerce" ), // 字段的显示标签
'value' => $custom_km_value, // 预填充字段的值，确保编辑时显示已有数据
'wrapper_class' => 'form-field-wide', // CSS类，使字段占据完整宽度
'description' => __( '输入车辆服务的总里程数。', 'woocommerce' ), // 字段描述
) );
}
/**
* 2. 保存WooCommerce后台订单页面的自定义字段数据
* 使用 woocommerce_process_shop_order_meta 钩子在订单保存时处理数据。
*/
add_action( 'woocommerce_process_shop_order_meta', 'save_custom_order_field_data' );
function save_custom_order_field_data( $order_id ) {
// 检查是否通过POST请求提交了 'custom_km' 字段
if ( isset( $_POST['custom_km'] ) ) {
// 使用 wc_clean() 对数据进行清理和安全处理，防止XSS攻击
$custom_km_value = wc_clean( $_POST['custom_km'] );
// 使用 update_post_meta() 将数据保存到数据库
update_post_meta( $order_id, 'custom_km', $custom_km_value );
}
}
/**
* 3. 在订单详情页显示已保存的自定义里程数据
* 使用 woocommerce_admin_order_data_after_billing_address 钩子在账单地址后显示。
*/
add_action( 'woocommerce_admin_order_data_after_billing_address', 'display_custom_distance_km', 10, 1 );
function display_custom_distance_km( $order ) {
// 获取已保存的自定义里程数据
$custom_km = get_post_meta( $order->get_ID(), 'custom_km', true );
// 如果数据存在，则显示
if ( ! empty( $custom_km ) ) {
echo '总里程数:
' . esc_html( $custom_km ) . ' 公里
';
}
}注意事项与最佳实践
-
钩子选择的灵活性： WooCommerce提供了大量的动作钩子，允许您将自定义字段放置在订单详情页面的不同位置。例如：
- woocommerce_admin_order_data_after_order_details: 订单详情之后。
- woocommerce_admin_order_data_after_billing_address: 账单地址之后。
- woocommerce_admin_order_data_after_shipping_address: 配送地址之后。
- woocommerce_admin_order_totals_after_tax: 订单总计税费之后。 您可以根据实际需求选择最合适的钩子。
- 数据安全与清理： 在保存任何用户输入的数据到数据库之前，务必使用wc_clean()（或WordPress的sanitize_text_field()等）进行清理。在显示数据到前端或后台时，使用esc_html()或esc_attr()进行转义，以防止跨站脚本（XSS）攻击。
- 字段ID的唯一性与命名规范： 为您的自定义字段选择一个独特且描述性的id（例如custom_km）。建议添加前缀（如myplugin_custom_km）以避免与其他插件或主题的字段发生冲突。
- 错误处理与验证： 对于更复杂的自定义字段，您可能需要添加额外的验证逻辑，例如检查输入是否为数字、是否在特定范围内等。这可以在save_custom_order_field_data函数中实现，并在验证失败时向用户显示错误消息。
- 国际化： 示例代码中使用了__("...", "woocommerce")，这是WordPress和WooCommerce进行国际化的标准方式，确保您的标签可以在多语言环境中被翻译。
通过遵循本教程的步骤和最佳实践，您可以轻松地在WooCommerce后台订单页面添加功能强大且安全的自定义可编辑字段，从而更好地管理您的业务数据。
