钩子-WordPress通用API手册-果果开发

Abilities API 提供了WordPress 动作和过滤器钩子，允许开发者监控并响应能力执行事件。

动作

wp_abilities_api_categories_init

在类别注册表首次初始化时触发。这是在注册类别时应使用的正确钩子。

do_action( 'wp_abilities_api_categories_init', $registry );

参数

$registry (\WP_Ability_Categories_Registry): 类别注册表实例。

使用示例

add_action( 'wp_abilities_api_categories_init', 'wporg_register_categories' );
/**
 * 注册自定义能力类别。
 *
 * @param \WP_Ability_Categories_Registry $registry 类别注册表实例。
 */
function wporg_register_categories( $registry ) {
    wp_register_ability_category( 'ecommerce', array(
        'label' => __( '电子商务', 'textdomain' ),
        'description' => __( '与电子商务功能相关的能力。', 'textdomain' ),
    ));

    wp_register_ability_category( 'analytics', array(
        'label' => __( '分析', 'textdomain' ),
        'description' => __( '提供分析数据和洞察力的能力。', 'textdomain' ),
    ));
}

wp_abilities_api_init

在能力注册表初始化完成后触发。这是在注册能力时应使用的正确钩子。

do_action( 'wp_abilities_api_init', $registry );

参数

$registry (\WP_Abilities_Registry): 能力注册表实例。

使用示例

add_action('wp_abilities_api_init', 'wporg_register_abilities');
/**
 * 注册自定义能力。
 */
function wporg_register_abilities() {
    wp_register_ability( 'wporg/ability', array(
        'label'               => __( '标题', 'textdomain' ),
        'description'         => __( '描述。', 'textdomain' ),
        'category'            => 'analytics',
        'input_schema'        => array(
            'type'                 => 'object',
            'properties'           => array(),
            'additionalProperties' => false,
        ),
        'output_schema'       => array(
            'type'        => 'string',
            'description' => '网站标题。',
        ),
        'execute_callback'    => 'wporg_get_site_title',
        'permission_callback' => '__return_true', // 所有人都可以访问此内容
        'meta'                => array(
            'show_in_rest' => true, // 可选：通过 REST API 暴露
        ),
    ) );
}

wp_before_execute_ability

在能力执行前立即触发，权限检查已通过但尚未调用执行回调时。

do_action( 'wp_before_execute_ability', $ability_name, $input );

参数

$ability_name (string): 正在执行的能力的命名空间名称（例如 wporg/get-posts）。
$input (mixed): 传递给能力的输入数据。

使用示例

add_action( 'wp_before_execute_ability', 'log_ability_execution', 10, 2 );
/**
 * 记录每次能力执行尝试。
 * @param string $ability_name 正在执行的能力名称。
 * @param mixed  $input        传递给能力的输入数据。
 */
function log_ability_execution( string $ability_name, $input ) {
    error_log( '即将执行能力：' . $ability_name );
    if ( $input !== null ) {
        error_log( '输入：' . wp_json_encode( $input ) );
    }
}

wp_after_execute_ability

在能力成功执行完毕后立即触发，输出验证通过后。

do_action( 'wp_after_execute_ability', string $ability_name, $input, $result );

参数

$ability_name (string): 已执行能力的命名空间名称。
$input (mixed): 传递给能力的输入数据。
$result (mixed): 能力执行回调返回的经过验证的结果。

使用示例

add_action( 'wp_after_execute_ability', 'log_ability_result', 10, 3 );
/**
 * 记录每次能力执行的结果。
 *
 * @param string $ability_name 已执行能力的名称。
 * @param mixed  $input        传递给能力的输入数据。
 * @param mixed  $result       能力返回的结果。
 */
function log_ability_result( string $ability_name, $input, $result ) {
    error_log( '完成能力：' . $ability_name );
    error_log( '结果：' . wp_json_encode( $result ) );
}

过滤器

wp_register_ability_args

允许在验证并使用参数实例化能力之前修改能力的参数。

$args = apply_filters( 'wp_register_ability_args', array $args, string $ability_name );

参数

$args (array<string,mixed>): 用于实例化能力的参数。完整参数列表请参阅wp_register_ability()。
$ability_name (string): 正在注册的能力的命名空间名称（例如 wporg/get-posts）。

使用示例

add_filter( 'wp_register_ability_args', 'my_modify_ability_args', 10, 2 );
/**
 * 在验证前修改能力参数。
 *
 * @param array<string,mixed> $args         用于实例化能力的参数。
 * @param string              $ability_name 能力名称及其命名空间。
 *
 * @return array<string,mixed> 修改后的能力参数。
 */
function my_modify_ability_args( array $args, string $ability_name ): array {
    // 检查能力名称是否匹配您正在查找的内容。
    if ( 'my-namespace/my-ability' !== $ability_name ) {
      return $args;
    }

    // 根据需要修改参数。
    $args['label'] = __('我的自定义能力标签');

    // 您可以使用旧参数构建新参数。
    $args['description'] = sprintf(
        /* translators: 1: 能力名称 2: 之前的描述 */
        __('这是能力 %s 的自定义描述。之前的描述是 %s', 'text-domain'),
        $ability_name,
        $args['description'] ?? 'N/A'
    );

    // 即使是回调函数也可以处理。
    $args['permission_callback' ] = static function ( $input = null ) use ( $args, $ability_name ) {
        $previous_check = is_callable( $args['permission_callback'] ) ? $args['permission_callback']( $input ) : true;

        // 如果已经失败，则无需更严格的检查。
        if ( ! $previous_check || is_wp_error( $previous_check ) ) {
            return $previous_check;
        }

        return current_user_can( 'my_custom_ability_cap', $ability_name );
    };

    return $args;
}

wp_register_ability_category_args

允许在验证之前修改类别的参数。

$args = apply_filters( 'wp_register_ability_category_args', array $args, string $slug );

参数

$args (array<string,mixed>): 用于实例化类别的参数（标签、描述）。
$slug (string): 正在注册的类别的 slug。

使用示例

add_filter( 'wp_register_ability_category_args', 'my_modify_category_args', 10, 2 );
/**
 * 在验证前修改类别参数。
 *
 * @param array<string,mixed> $args 用于实例化类别的参数。
 * @param string              $slug 正在注册的类别的 slug。
 *
 * @return array<string,mixed> 修改后的类别参数。
 */
function my_modify_category_args( array $args, string $slug ): array {
    if ( 'my-category' === $slug ) {
        $args['label'] = __( '我的自定义标签', 'textdomain' );
        $args['description'] = __( '这是我为此类别编写的自定义描述。', 'textdomain' );
    }
    return $args;
}