编辑“WordPress插件API/常用动作(action)”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress插件及插件开发资源|上一页]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>
本文列出了WordPress 2.1及以上版本中可用于插件开发的动作钩子（hook)。

*想了解过滤器钩子和动作钩子的定义和作用？请看[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API.html 插件API]。   
*想了解插件的基本编写过程？请看[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91.html 插件开发]。     
*想查看过滤器钩子函数列表？请看[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API%E4%B9%8B%E5%B8%B8%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8%E5%87%BD%E6%95%B0.html 插件API之常用过滤器]。     
*想查找WordPress 2.1之前版本的过滤器钩子和动作钩子？请看[http://codex.wordpress.org/Plugin_API/Hooks_2.0.x Plugin API/Hooks   2.0.x]。 

注意：为本文添加词条或做其它改动时，请参照当前格式。添加时请说明过滤器函数适用的数据类型，如果过滤器函数接收多个参数，请在参数列表中说明

==在典型请求中运行的动作钩子==
在WordPress 2.7中，当已登录用户在默认[http://www.wordpress.la/theme.html 主题]打开网站主页时，WordPress会运行以下动作钩子函数：

#plugins_loaded 
#sanitize_comment_cookies 
#setup_theme 
#auth_cookie_malformed 
#auth_cookie_valid 
#set_current_user 
#init 
#widgets_init 
#parse_request 
#send_headers 
#pre_get_posts 
#posts_selection 
#wp 
#template_redirect 
#get_header 
#wp_head 
#wp_print_styles 
#wp_print_scripts 
#loop_start 
#loop_end 
#get_sidebar 
#wp_meta 
#get_footer 
#wp_footer 

==日志、页面、附件以及类别相关的动作钩子函数==
add_attachment

附件文件首次加入[[数据库]]时，执行add_attachment函数。函数接收的参数：附件ID。

add_category

与create_category相同。

clean_post_cache

清除日志缓存时，执行该动作函数。函数接收的参数：日志ID。参见[http://codex.wordpress.org/Function_Reference/clean_post_cache clean_post_cache()]。

create_category

生成新类别时，执行该动作函数。函数接收的参数：类别ID。

delete_attachment

从[[数据库]]和相应链接/日志中删除某个类别后，执行该动作函数。函数接收的参数：类别ID。

delete_post

将要删除某篇日志或页面时，执行该动作函数。函数接收的参数：日志ID或页面ID。

deleted_post

删除某篇日志或页面后，执行该动作函数。函数接收的参数：日志ID或页面ID。

edit_attachment

数据库中附件文件被更新时执行该动作函数。函数接收的参数：附件ID。

edit_category

更新/编辑某个类别时（包括添加/删除日志或博客[[反向链接]]，或更新日志/[[博客]]反向链接的类别），执行该动作函数。函数接收的参数：类别ID。

edit_post

更新/编辑某篇日志或页面时（包括添加/更新评论，这会导致日志评论总数的更新），执行该动作函数。函数接收的参数：日志ID或页面ID。

pre_post_update

更新日志或页面前执行该动作函数。函数接收的参数：日志ID。

private_to_publish

当日志状态从private（私密）更改为published（公开）时，执行该动作函数。函数接收的参数：日志对象。（用以翻译日志状态的动作函数目前可用；参见wp_transition_post_status()）。

publish_page

发表页面或编辑某个状态为“published”的页面时，执行该动作函数。函数接收的参数：页面ID。（警告：该动作函数不能在WordPress 2.3以及更高版本中运行；但动作函数'transition_post_status'能够运行。更新信息：publish_page动作函数可在WordPress 2.6及之后版本中运行。）

publish_phone

通过[[电子邮件]]添加新日志后，执行该动作函数。函数接收的参数：日志ID。

publish_post

发表日志或编辑某个状态为“published”的日志时，执行该动作函数。函数接收的参数：日志ID。

save_post

新建或更新一篇日志/页面时，执行该动作函数。更新可以来自导入、日志/页面编辑框、xmlrpc或[[邮件]]日志。函数接收的参数：日志ID。

更新信息存入数据库后执行该动作函数。

注意：日志ID可能会参照日志的修改版而不是最新发布版。wp_is_post_revision可获取日志最新版的ID。

wp_insert_post

与save_post相同，更新信息存入数据库后执行该动作函数。

xmlrpc_public_post

通过[[XML]]RPC请求发表日志，或通过XMLRPC编辑某个状态为“published”的日志时，执行该动作函数。函数接收的参数：日志ID。

==评论、Ping以及引用通告相关动作钩子函数==
comment_closed

尝试显示评论输入框而日志却设置为不允许评论时，执行该动作函数。函数接收的参数：日志ID。

comment_id_not_found

试图显示评论或评论输入框却未找到日志ID时，执行该动作函数。函数接收的参数：日志ID。

comment_flood_trigger

调用wp_die以阻止接收评论前，若检测到评论数量异常增多，执行该动作函数。函数接收的参数：上一次评论发表时间，当前评论发表时间。

comment_on_draft

日志为草稿状态却试图显示评论或评论输入框时，执行该动作函数。函数接收的参数：日志ID。

comment_post

评论刚被存入数据库时，执行此动作函数。函数接收的参数：评论ID，评论审核状态（"spam"，0（表示未审核），1（表示已审核））。

edit_comment

数据库中的评论被更新或编辑后，执行此动作函数。函数接收的参数：评论ID。

delete_comment

评论即将被删除前，执行此动作函数。函数接收的参数：评论ID。

pingback_post

日志新添加pingback后，执行此动作函数。函数接收的参数：评论ID。

pre_ping

执行pingback前，执行此动作函数。函数接收的参数：将要处理的日志链接数组，以及日志的“pung”设置。

trackback_post

日志新添加trackback后，执行此动作函数。函数接收的参数：评论ID。

wp_blacklist_check

执行该动作函数以判断评论是否应被禁止。函数接收的参数：评论者的名称、[[电子邮件]]、[[URL]]、评论内容、[[IP]]地址、用户代理（[[浏览器]]）。该函数可执行wp_die以拒绝评论，也可以修改某个参数以使评论中可包含用户在WordPress选项中设置的黑名单[[关键词]]。

wp_set_comment_status

评论状态发生改变时，执行此动作函数。函数接收的参数：评论ID，表明新状态的状态字符串（"delete", "approve", "spam", "hold"）。

==反向链接动作钩子函数==
add_link

新反向链接首次加入数据库时，执行此动作函数。函数接收的参数：链接ID。

delete_link

删除反向链接时，执行此动作函数。函数接收的参数：链接ID。

edit_link

编辑[[反向链接]]时，执行此动作函数。函数接收的参数：链接ID。

==Feed动作钩子函数==
atom_entry

在atom订阅中，显示某篇博客日志信息后（但关闭该日志标签前），执行此动作函数。

atom_head

在atom订阅中，显示所订阅的某个[[博客]]信息后，还未显示该博客第一篇日志前，执行此动作函数。

atom_ns

为atom订阅的根[[XML]]元素执行此动作函数（以添加命名空间）。

commentrss2_item

在评论订阅中，显示某条评论信息后（但关闭该评论的[[标签]]前），执行此动作函数。函数接收的参数：评论ID，日志ID。

do_feed_(feed)

生成订阅信息时执行此动作函数，其中的订阅指的是订阅类型（rss2，atom，rdf等）。显示订阅信息所用优先级应低于10。函数接收的参数：true（评论订阅），或false（日志订阅）。

rdf_header

在rdf订阅中，显示所订阅的博客信息后，还未显示该博客第一篇日志前，执行此动作函数。

rdf_item

在RDF订阅中，显示某篇博客日志信息后（但关闭该日志标签前），执行此动作函数。

rdf_ns

为RDF订阅的根[[XML]]元素执行此动作函数（以添加命名空间）。

rss_head

在[[RSS]]订阅中，显示所订阅的博客信息后，还未显示该博客第一篇日志前，执行此动作函数。

rss_item

在RSS订阅中，显示某篇博客日志信息后（但关闭该日志标签前），执行此动作函数。

rss2_head

在RSS2订阅中，显示所订阅的[[博客]]信息后，还未显示该博客第一篇日志前，执行此动作函数。

rss2_item

在RSS2订阅中，显示某篇博客日志信息后（但关闭该日志标签前），执行此动作函数。

rss2_ns

为RSS2订阅的根[[XML]]元素执行此动作函数（以添加命名空间）。

==模板相关动作钩子函数==
comment_form

在标准WordPress主题中执行此动作函数以插入评论表单。函数接收的参数：日志ID。

do_robots

模板文件选择器认为这是一个来自robots.txt的请求时，执行该动作函数。

do_rebotstxt

在do_robots函数为robots.txt文件显示“Disallow”[[链接]]前，执行此动作函数。

get_footer

加载footer.php模板文件前，模板调用get_footer函数时执行此动作函数。

get_header

加载header.php模板文件前，模板调用get_header函数时执行此动作函数。

switch_theme

更改[http://www.wordpress.la/theme.html 博客主题]时执行此动作函数。函数接收的参数：新主题的名称。

template_redirect

决定用以显示所请求页面的模板文件前执行此动作函数，以便插件改写对模板文件的选择。示例（仅供参考，无实际用途）：将所有请求重定向到当前主题目录下的all.php模板文件。

 function all_on_one () {
    include( TEMPLATEPATH . '/all.php');exit;
 }
 add_action('template_redirect', 'all_on_one');

wp_footer

模板在博客页面的最下方附近调用wp_footer函数时执行该动作函数。

wp_head

模板调用wp_head函数时执行动作函数wp_head。wp_head通常被放在页面模板最上方< head>和 </head>之间。该动作函数不接受参数。

wp_meta

模板文件sidebar.php调用wp_meta函数以允许插件在侧边栏加入内容时，执行此动作函数。

wp_print_scripts

WordPress将已记录的[[JavaScript]]脚本输入页面的页眉部分前，执行此动作函数。

==管理界面相关的动作钩子函数==
activate_(插件文件名)

首次激活某插件时执行此动作函数。参见常用函数-[http://www.wordpress.la/codex-%E5%B8%B8%E7%94%A8%E5%87%BD%E6%95%B0-register_activation_hook%28%29.html register_activation_hook]。

activity_box_end

在控制板界面上的活动框末端执行该动作函数。

add_category_form_pre

添加分类的文本框尚未显示在管理菜单的界面上时，执行此动作函数。

admin_head

在控制板的[[HTML]]版块&lt;head&gt;中执行此动作函数。

admin_head-(page_hook)或admin_head-(plguin_page)

在插件所生成页面的控制板的HTML版块&lt;head&gt;中执行此动作函数。

admin_init

加载管理界面前执行该动作函数。参见wp-admin/admin.php ，wp-admin/admin-post.php ，以及wp-admin/admin-ajax.php 。

admin_footer

在主标签中的控制板末端执行该动作函数。

admin_print_scripts

在HTML的信息头部分执行此动作函数，以使插件将[[JavaScript]]脚本添加到所有管理界面。

admin_print_styles

在HTML的信息头部分执行此动作函数，以使插件将[[CSS]]或样式表单添加到所有管理界面。

admin_print_scripts-(page_hook) 或 admin_print_scripts-(plugin_page) 

执行此动作函数，以便将[[JavaScript]]脚本输入某个由插件生成的管理页面的HTML信息头部分。使用add_management_page(),   add_options_page()等函数将插件菜
单选项添加到管理菜单中时，返回(page_hook)。示例如下：

 function myplugin_menu() {    
   if ( function_exists('add_management_page') ) {      
       $page = add_management_page( 'myplugin', 'myplugin', 9, __FILE__, 'myplugin_admin_page' );      
       add_action( "admin_print_scripts-$page", 'myplugin_admin_head' );    
    } 
check_passwords

创建新用户账号时，执行该动作函数以验证两次输入的密码是否一致。函数接收的参数：登录名数组，首次输入的密码，第二次输入的密码。

dbx_page_advanced

在管理菜单的页面编辑界面上“advanced”版块的最下方执行此动作函数。

dbx_page_sidebar

在管理菜单的页面编辑界面工具条的最下方执行此动作函数。

dbx_post_advanced

在管理菜单的日志编辑界面上“advanced”版块的最下方执行此动作函数。

dbx_post_siderbar

在管理菜单的日志编辑界面工具条的最下方执行此动作函数。WordPress 2.5或更高版本中则执行 [http://www.wordpress.la/codex-%E5%B8%B8%E7%94%A8%E5%87%BD%E6
%95%B0-add_meta_box%28%29.html add_meta_box()]函数。

deactivate_(插件文件名)

禁用插件时执行此动作函数。

delete_user

删除用户时执行此动作函数。函数接收的参数：用户ID。

edit_category_form

添加/编辑分类表显示在界面上后（[[HTML]]表标签结束前），执行此动作函数。

edit_category_form_pre

编辑分类表显示在管理菜单界面前，执行此动作函数。

edit_tag_form

添加/编辑标签表显示在界面上后（HTML表标签结束前），执行此动作函数。

edit_tag_form_pre

编辑标签表显示在管理菜单界面前，执行此动作函数。

edit_form_advanced

在管理菜单中日志编辑框的“advanced”版块前执行此动作函数。

edit_page_form

在管理菜单中页面编辑框的“advanced”版块前执行此动作函数。

edit_user_profile

在管理菜单中用户资料的最后部分执行此动作函数。

load_(page)

加载管理菜单页面时执行此动作函数。该动作函数不能直接添加——添加管理菜单过程参见[http://www.wordpress.la/codex-%E5%AE%9A%E5%88%B6%E6%8F%92%E4%BB%B6%E7%AE%A1%E7%90%86%E8%8F%9C%E5%8D%95.html 定制插件管理菜单]。如果希望直接添加该函数，add_options_page和类似函数返回的值能够给出动作函数名称。

login_form

在登录框的结尾部分前执行此动作函数。

login_head

在登录界面[[HTML]]页眉部分的结尾部分前执行此动作函数。

lost_password

在“通过电子邮件找回密码”显示在登录界面前执行此动作函数。

lostpassward_form

在通过电子邮件找回密码的表格尾部执行此动作函数，使插件能够提供更多字段。

lostpassward_post

用户要求通过电子邮件找回密码时执行此动作函数，使插件能够在找回密码前修改PHP $_POST变量。

manage_link_custom_column

反向链接管理界面中出现未知列名称时执行此动作函数。函数接收的参数：列名称，链接ID。参见[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API%E4%B9%8B
%E5%B8%B8%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8%E5%87%BD%E6%95%B0.html 插件API/常用过滤器函数]中的过滤器函数manage_links_columns，该函数可添加自定义列。

manage_posts_custom_column

日志管理界面中出现未知列名称时执行此动作函数。函数接收的参数：列名称，日志ID。参见[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API%E4%B9%8B%E5
%B8%B8%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8%E5%87%BD%E6%95%B0.html 插件API/常用过滤器函数]中的过滤器函数manage_posts_columns，该函数可添加自定义列。（具体用法和示例参见 [http://scompt.com/archives/2007/10/20/adding-custom-columns-to-the-wordpress-manage-posts-screen Scompt's   tutorial] ）。

manage_pages_custom_column

页面管理界面中出现未知列名称时执行此动作函数。函数接收的参数：列名称，页面ID。参见[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API%E4%B9%8B%E5%B8%B8%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8%E5%87%BD%E6%95%B0.html 插件API/常用过滤器函数]中的过滤器函数manage_pages_columns，该函数可添加自定义列。

password_reset

用户将旧密码更改为新密码前执行此动作函数。

personal_options_update

用户在控制板中更新设置时执行此动作函数。

plugins_loaded

所有插件加载完毕后执行此动作函数。

profile_personal_options

在用户资料编辑iemian的“关于您自己”版块结尾处执行此动作函数。

profile_update

更新用户资料时执行此动作函数。函数结合搜的参数：用户ID。

register_form

在新用户注册表结尾部分前执行此动作函数。

register_post

处理新用户注册请求前执行此动作函数。

restrict_manage_posts

需要编辑的日志列表显示在管理菜单界面前，执行此动作函数。

retrieve_password

检索用户密码以发送密码提醒[[邮件]]时执行此动作函数。函数接收的参数：登录名。

set_current_user

默认函数wp_set_current_user更改用户后，执行此动作函数。注意：wp_set_current_user是一个“插入式”函数，即插件可以改写该函数；参见[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API.html 插件API]。

show_user_profile

在用户资料编辑界面结尾部分执行此动作函数。

simple_edit_form

在控制板的“简单”日志编辑框的结尾部分执行此动作函数（默认情况下，简单编辑框仅用于书签工具——没有“高级”选项）。

update_option_(option_name)

update_option函数更新WordPress选项后，执行该动作函数。函数接收的参数：原选项值，新选项值。用户需要为希望更新的选项添加一个动作函数，例如更新“foo”时用函数update_option_foo来呼应。

upload_files_(tab)

执行该动作函数以显示上传文件管理界面上的某个页面；“tab”是自定义动作函数表的名称。可以用过滤器函数wp_upload_tabs来定义自定义表（参见
[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API%E4%B9%8B%E5%B8%B8%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8%E5%87%BD%E6%95%B0.html 插件API/常用过滤器函数]）。

user_register

首次创建用户资料时执行此动作函数。函数接收的参数：用户ID。

wp_ajax_(action)

在管理菜单中执行此动作函数以运行未知类型的[[AJAX]]。

wp_authenticate

用户登录时，执行该动作函数以验证用户身份。函数接收的参数：用户名和密码数组。

wp_login

用户登录时执行此动作函数。

wp_logout

用户退出登录时执行此动作函数。

==高级动作函数==
本部分介绍的都是与WordPress查询（决定该显示哪一篇日志）、WordPress主循环、激活插件以及WordPress基础代码相关的动作函数。<br>
admin_menu<br>
控制板中的菜单结构显示无误后，执行此动作函数。<br>
admin_notices<br>
管理菜单显示在页面上时执行此动作函数。<br>
blog_privacy_selector<br>
博客默认隐私选项显示在页面上时，执行此动作函数。<br>
check_admin_referer<br>
系统出于安全考虑检查随机数后在默认函数check_admin_referrer中执行check_admin_referer动作钩子，使插件因安全原因而强制WordPress停止运行。注意：check_admin_referrer也是一个“插入式”函数，即插件可以改写该函数；参见[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API.html 插件API]。<br>
check_ajax_referer<br>
系统从cookies中成功验证用户的登录名和密码后，在默认函数   check_ajax_referer（这是在有AJAX请求进入wp-admin/admin-ajax.php脚本时所调用的函数）中执行此动作函数，使插件能够因安全原因强制WordPress停止运行。注意：   check_ajax_referer函数也是一个“插入式”函数，即插件可以改写该函数；参见[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API.html 插件API]。<br>
generate_rewrite_rules<br>
重写规则生成后，执行此动作函数。函数接收的参数：WP_Rewrite类变量列表。注意：在修改重写规则时，使用rewrite_rules_array过滤器函数比使用该动作函数更加方便。<br>
init<br>
WordPress加载完毕但尚未发送页眉信息时执行该动作函数。函数适用于解析$_GET or $_POST 触发器。<br>
loop_end<br>
WordPress主循环最后一篇日志执行完毕后，执行此动作函数。<br>
loop_start<br>
执行WordPress主循环第一篇日志前，执行此动作函数。<br>
parse_query<br>
在[http://www.wordpress.la/codex-%E6%9F%A5%E8%AF%A2%E8%AF%AD%E5%8F%A5%E6%A6%82%E8%A7%88.html 主查询]或[http://www.wordpress.la/codex-%E5%B8%B8%E7%94%A8%E5%87%BD%E6%95%B0-wp_query%28%29.html WP_Query] 的任何实例（如[http://codex.wordpress.org/Template_Tags/query_posts query_posts]，[http://www.wordpress.la/codex-get_posts.html get_posts]或[http://www.wordpress.la/codex-%E5%B8%B8%E7%94%A8%E5%87%BD%E6%95%B0-get_children%28%29.html get_children]）中查询解析结束时，执行此动作函数。函数接收的参数：$wp_query   对象内容列表。<br>
parse_request<br>
在主WordPress函数wp中解析查询请求后，执行该动作函数。函数接收的参数：引用全局变量$wp对象的数组。<br>
pre_get_posts<br>
在get_posts函数开始操作查询前执行此动作函数。函数接收的参数：$wp_query对象的内容列表。<br>
sanitize_comment_cookies <br>
HTTP请求读取cookies后执行此动作函数。<br>
send_headers<br>
在WordPress主函数wp中发送基本[[HTTP]]页眉后执行此动作函数。函数接收的参数：引用全局变量$wp对象的数组。<br>
shutdown<br>
页面内容输出完毕后执行此动作函数。<br>
wp<br>
在WordPress主函数wp中解析查询、页面加载完毕后，执行模板前，执行此动作函数。函数接收的参数：引用全局变量$wp对象的数组。<br>
==延伸阅读==
*[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91.html 插件开发]
*[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API.html 插件API]
*[http://www.wordpress.la/codex-%E6%8F%92%E4%BB%B6API%E4%B9%8B%E5%B8%B8%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8%E5%87%BD%E6%95%B0.html 插件API/常用过滤器函数]
*[http://codex.wordpress.org/User:Skippy Skippy's list]（动作函数和过滤器函数列表）   
*[http://wphooks.flatearth.org WordPress Hooks]
*[http://adambrown.info/p/wp_hooks WordPress Hooks数据库]
*[http://blog.taragana.com/index.php/archive/wordpress-2x-hooks-for-action-comprehensive-list-for-plugin-and-theme-developers/ Angsuman's   list],（WordPress动作函数列表，附说明和源代码位置信息） 

==相关条目==
*[[Drupal]] 
*[[OBLOG]] 
*[[X-Space]] 
*[[SaBlog-X]] 
*[[Bo-Blog]]

[[category:WordPress中文文档|C]]
[[category:WordPress网站开发|C]]
[[category:WordPress开发文档|C]]