Question

add_action( string $tag,  callable $function_to_add,  int $priority = 10,  int $accepted_args = 1 )

将函数挂在特定动作上。

---

description

Action 动作是 WordPress 核心在执行过程中特定点或特定事件发生时的挂钩。插件可以指定一个或多个PHP函数在这些点上执行，使用动作API。

---

参数

$tag

(string)
(Required)
$function_to_add  所挂载的动作（action）的名称。也可以是一个主题或插件文件内部的一个动作，或者特定的标签“all”，这个函数将被所有的钩子（hooks）调用。

$function_to_add

(callable)
(Required)
希望调用的函数名称。

$priority

(int)
(Optional)
用于指定与特定的动作相关联的函数的执行顺序。数字越小，执行越早，具有相同优先级的函数在它们被添加到动作的顺序执行。
Default value: 10

$accepted_args

(int)
(Optional)
挂钩函数所接受的参数数量。在 WordPress1.5.1 及以后的版本中，挂钩函数可以是调用do_action() 或 apply_filters()时设置的参数。例如，comment_id_not_found动作将传递任何函数，若该函数将所请求的评论编号连接到该动作。
Default value: 1

---

返回值

(true) 总是返回 true。

---

源代码

File: wp-includes/plugin.php

function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
	return add_filter($tag, $function_to_add, $priority, $accepted_args);
}

---

更新日志

Version	description
1.2.0	Introduced.

---

更多的信息

Usage

add_action( $hook, $function_to_add, $priority, $accepted_args );

找到数字和名称参数的一个动作，简单的搜索代码库调用 do_action()。例如，如果你是挂载到 save_post'，你会发现它在 post.php 中这样编写：

do_action( 'save_post', $post_ID, $post, $update );

你的 add_action 可以这样编写：

add_action( 'save_post', 'wpdocs_my_save_post', 10, 3 );

你的毁掉函数可以这样编写：

function wpdocs_my_save_post( $post_ID, $post, $update ) {
   // do stuff here
}

---

相关函数

Uses

• wp-includes/plugin.php:add_filter()

---

Used By

• wp-includes/class-wp-editor.php:
  _WP_Editors::enqueue_default_editor()
• wp-includes/nav-menu.php:
  _wp_delete_customize_changeset_dependent_auto_drafts()
• wp-includes/widgets/class-wp-widget-text.php:
  WP_Widget_Text::_register()
• wp-includes/widgets/class-wp-widget-media.php:
  WP_Widget_Media::_register()
• wp-includes/class-wp-customize-manager.php:
  WP_Customize_Manager::import_theme_starter_content()
• wp-includes/class-wp-post-type.php:
  WP_Post_Type::register_meta_boxes()
• wp-includes/class-wp-post-type.php:
  WP_Post_Type::add_hooks()
• wp-includes/class-wp-customize-widgets.php:
  WP_Customize_Widgets::selective_refresh_init()
• wp-includes/customize/class-wp-customize-selective-refresh.php:
  WP_Customize_Selective_Refresh::init_preview()
• wp-includes/customize/class-wp-customize-selective-refresh.php:
  WP_Customize_Selective_Refresh::enqueue_preview_scripts()
• wp-includes/customize/class-wp-customize-selective-refresh.php:
  WP_Customize_Selective_Refresh::__construct()
• wp-includes/rest-api.php:
  rest_api_default_filters()
• wp-includes/class-wp-customize-setting.php:
  WP_Customize_Setting::aggregate_multidimensional()
• wp-includes/admin-bar.php:
  wp_admin_bar_customize_menu()
• wp-includes/class-wp-widget-factory.php:
  WP_Widget_Factory::__construct()
• wp-includes/customize/class-wp-customize-site-icon-control.php:
  WP_Customize_Site_Icon_Control::__construct()
• wp-includes/customize/class-wp-customize-nav-menu-item-setting.php:
  WP_Customize_Nav_Menu_Item_Setting::__construct()
• wp-includes/class-wp-customize-nav-menus.php:
  WP_Customize_Nav_Menus::customize_preview_init()
• wp-includes/class-wp-customize-nav-menus.php:
  WP_Customize_Nav_Menus::__construct()
• wp-admin/includes/class-wp-site-icon.php:
  WP_Site_Icon::__construct()
• wp-login.php:
  login_header()
• wp-admin/includes/class-language-pack-upgrader.php:
  Language_Pack_Upgrader::bulk_upgrade()
• wp-admin/includes/class-theme-upgrader.php:
  Theme_Upgrader::install()
• wp-admin/includes/class-theme-upgrader.php:
  Theme_Upgrader::upgrade()
• wp-admin/includes/class-plugin-upgrader.php:
  Plugin_Upgrader::install()
• wp-admin/includes/class-plugin-upgrader.php:
  Plugin_Upgrader::upgrade()
• wp-admin/includes/class-wp-list-table.php:
  WP_List_Table::__construct()
• wp-admin/includes/class-wp-theme-install-list-table.php:
  WP_Theme_Install_List_Table::prepare_items()
• wp-admin/includes/update.php:
  wp_plugin_update_rows()
• wp-admin/includes/update.php:
  wp_theme_update_rows()
• wp-admin/includes/plugin.php:
  uninstall_plugin()
• wp-admin/includes/plugin.php:
  add_menu_page()
• wp-admin/includes/plugin.php:
  add_submenu_page()
• wp-admin/includes/class-wp-plugin-install-list-table.php:
  WP_Plugin_Install_List_Table::prepare_items()
• wp-admin/includes/class-wp-internal-pointers.php:
  WP_Internal_Pointers::enqueue_scripts()
• wp-admin/custom-header.php:
  Custom_Image_Header::__construct()
• wp-admin/custom-header.php:
  Custom_Image_Header::init()
• wp-admin/custom-background.php:
  Custom_Background::__construct()
• wp-admin/custom-background.php:
  Custom_Background::init()
• wp-includes/class-wp-customize-manager.php:
  WP_Customize_Manager::customize_preview_init()
• wp-includes/class-wp-customize-manager.php:
  WP_Customize_Manager::setup_theme()
• wp-includes/class-wp-customize-manager.php:
  WP_Customize_Manager::__construct()
• wp-includes/theme.php:
  _custom_header_background_just_in_time()
• wp-includes/general-template.php:
  add_thickbox()
• wp-includes/functions.php:
  wp_auth_check_load()
• wp-includes/functions.php:
  wp_maybe_load_widgets()
• wp-includes/widgets/class-wp-widget-recent-comments.php:
  WP_Widget_Recent_Comments::__construct()
• wp-includes/class-wp-locale.php:
  WP_Locale::init()
• wp-includes/class-wp-embed.php:
  WP_Embed::__construct()
• wp-includes/class-wp-admin-bar.php:
  WP_Admin_Bar::add_menus()
• wp-includes/class-wp-admin-bar.php:
  WP_Admin_Bar::initialize()
• wp-includes/plugin.php:
  register_activation_hook()
• wp-includes/plugin.php:
  register_deactivation_hook()
• wp-includes/class-wp-customize-setting.php:
  WP_Customize_Setting::preview()
• wp-includes/media.php:
  wp_enqueue_media()
• wp-includes/media.php:
  wp_playlist_scripts()
• wp-includes/class-wp-rewrite.php:
  WP_Rewrite::wp_rewrite_rules()
• wp-includes/class-wp-rewrite.php:
  WP_Rewrite::flush_rules()
• wp-includes/rewrite.php:
  add_feed()
• wp-includes/class.wp-scripts.php:
  WP_Scripts::__construct()
• wp-includes/class-wp-customize-widgets.php:
  WP_Customize_Widgets::customize_preview_init()
• wp-includes/class-wp-customize-widgets.php:
  WP_Customize_Widgets::__construct()
• wp-includes/class-wp-customize-widgets.php:
  WP_Customize_Widgets::schedule_customize_register()
• wp-includes/comment.php:
  wp_set_comment_status()
• wp-includes/class-wp-editor.php:
  _WP_Editors::editor_settings()
• wp-includes/media-template.php:
  wp_print_media_templates()

---

使用举例

在类中使用 add_action

当你的插件或主题使用类来创建时，使用 add_action 钩子，在类中添加 $this 和 函数名称 到你的 add_action 回调，像这样：

/**
 * Class WP_Docs_Class.
 */
class WP_Docs_Class {

	/**
	 * Constructor
	 */
	public function __construct() {
		add_action( 'save_post', array( $this, 'wpdocs_save_posts' ) );
	}

	/**
	 * Handle saving post data.
	 */
	public function wpdocs_save_posts() {
		// do stuff here...
	}
}

$wpdocsclass = new WP_Docs_Class();

在类的静态方法中调用 add_action

如果类被称为静态的方法是像下面为不可用。这也适用于如果类是扩展的。使用以下：

/**
 * Class WP_Docs_Static_Class.
 */
class WP_Docs_Static_Class {

	/**
	 * Initializer for setting up action handler
	 */
	public static function init() {
		add_action( 'save_post', array( get_called_class(), 'wpdocs_save_posts' ) );
	}

	/**
	 * Handler for saving post data.
	 */
	public static function wpdocs_save_posts() {
		// do stuff here...
	}
}

WP_Docs_Static_Class::init();

简单使用

博客发表新内容时用电子邮件通知朋友：

/**
 * Send email to my friends.
 *
 * @param int $post_id Post ID.
 * @return int Post ID.
 */
function wpdocs_email_friends( $post_id ) {
	$friends = 'bob@example.org, susie@example.org';
	wp_mail( $friends, "sally's blog updated", 'I just put something on my blog: http://blog.example.com' );

	return $post_id;
}
add_action( 'publish_post', 'wpdocs_email_friends' );

接受的参数

挂钩函数可以选择接受从动作调用的参数，如果有任何要传递的话。在这个简单的例子中，echo_comment_id  函数需要 $comment_id 参数，该参数将在 comment_id_not_found 过滤钩子运行时通过 do_action() 传递。

/**
 * Warn about comment not found
 *
 * @param int $comment_id Comment ID.
 */
function echo_comment_id( $comment_id ) {
	printf( 'Comment ID %s could not be found', esc_html( $comment_id ) );
}
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );