87 lines
No EOL
1.9 KiB
Markdown
87 lines
No EOL
1.9 KiB
Markdown
# 使用钩子
|
|
|
|
## 钩子回调命名规范
|
|
|
|
钩子回调方法命名：使用 `handle_{钩子名称}` 并添加 `@internal` 注解。
|
|
|
|
**示例：**
|
|
|
|
```php
|
|
/**
|
|
* 处理 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` 注解
|
|
|
|
```php
|
|
/**
|
|
* 在订单处理完成后触发。
|
|
*
|
|
* @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"` 查找钩子引入的时间
|
|
|
|
**动作钩子示例：**
|
|
|
|
```php
|
|
/**
|
|
* 在产品保存后触发。
|
|
*
|
|
* @param int $product_id 产品 ID。
|
|
* @param WC_Product $product 产品对象。
|
|
*
|
|
* @since 9.5.0
|
|
*/
|
|
do_action( 'woocommerce_product_saved', $product_id, $product );
|
|
```
|
|
|
|
**过滤器钩子示例：**
|
|
|
|
```php
|
|
/**
|
|
* 在产品价格显示前进行过滤。
|
|
*
|
|
* @param string $price 格式化后的价格。
|
|
* @param WC_Product $product 产品对象。
|
|
*
|
|
* @since 9.5.0
|
|
*/
|
|
$price = apply_filters( 'woocommerce_product_price', $price, $product );
|
|
``` |
