woocommerce/.ai/skills/woocommerce-backend-dev/zh-cn/hooks.md

使用钩子

钩子回调命名规范

钩子回调方法命名：使用 handle_{钩子名称} 并添加 @internal 注解。

示例：

/**
 * 处理 woocommerce_init 钩子。
 *
 * @internal
 */
public function handle_woocommerce_init() {
    // 初始化组件
}

/**
 * 处理 woocommerce_before_checkout 钩子。
 *
 * @internal
 *
 * @param WC_Checkout $checkout 结账对象。
 */
public function handle_woocommerce_before_checkout( $checkout ) {
    // 设置结账流程
}

钩子文档块

如果修改了触发钩子的行但没有文档块：

1. 添加包含描述和 @param 标签的文档块
2. 使用 git log -S "hook_name" 查找钩子引入的时间
3. 添加包含该版本的 @since 注解

/**
 * 在订单处理完成后触发。
 *
 * @param int $order_id 已处理的订单 ID。
 * @param array $order_data 订单数据。
 *
 * @since 8.2.0
 */
do_action( 'woocommerce_order_processed', $order_id, $order_data );

钩子文档要求

所有钩子必须包含以下内容的文档块：

• 钩子触发时机的描述
• 传递给钩子的每个参数的 @param 标签
• 包含版本号的 @since 注解（最后一行，前面空一行）
  • 对于新钩子：使用 trunk 分支上 includes/class-woocommerce.php 中的版本，移除 -dev 后缀
  • 对于现有钩子：使用 git log -S "hook_name" 查找钩子引入的时间

动作钩子示例：

/**
 * 在产品保存后触发。
 *
 * @param int        $product_id 产品 ID。
 * @param WC_Product $product    产品对象。
 *
 * @since 9.5.0
 */
do_action( 'woocommerce_product_saved', $product_id, $product );

过滤器钩子示例：

/**
 * 在产品价格显示前进行过滤。
 *
 * @param string     $price   格式化后的价格。
 * @param WC_Product $product 产品对象。
 *
 * @since 9.5.0
 */
$price = apply_filters( 'woocommerce_product_price', $price, $product );