WordPress插件开发：钩子手册

编辑文章

公共加载阶段

WordPress 核心初始化

钩子名称 类型 执行时机 常用用途
muplugins_loaded action MU插件加载完成后 最早可用的钩子，用于早期初始化
registered_taxonomy action 分类法注册时 分类法注册后的处理
registered_post_type action 文章类型注册时 文章类型注册后的处理
plugins_loaded action 所有插件加载完成后 插件初始化、加载翻译文件
sanitize_comment_cookies action 评论cookie清理后 评论相关初始化
setup_theme action 主题加载前 主题相关早期设置
after_setup_theme action 主题设置完成后 主题功能支持声明
load_textdomain action 文本域加载时 翻译文件加载
init action WordPress初始化完成 注册文章类型、分类法等
widgets_init action 小部件初始化时 注册小部件和侧边栏
register_sidebar action 侧边栏注册时 侧边栏注册后的处理

查询解析阶段

钩子名称 类型 执行时机 常用用途
parse_request action 解析请求后 自定义请求处理
send_headers action 发送HTTP头部前 修改HTTP头部
parse_query action 查询解析后 修改查询参数
pre_get_posts action 获取文章前 修改主查询参数
posts_selection action 文章选择后 查询结果处理

前端页面钩子

所有页面通用

头部区域

钩子名称 类型 执行时机 常用用途
wp_enqueue_scripts action 排队脚本时 注册和排队前端脚本样式
wp_head action <head>标签内 输出头部代码
wp_body_open action <body>标签开始后 输出body开始内容
wp_robots filter 生成robots元标签时 控制robots元标签

内容循环前

钩子名称 类型 执行时机 常用用途
template_redirect action 模板加载前 重定向或权限检查
get_header action 获取头部模板时 头部模板加载前
wp_print_styles action 打印样式时 样式输出前
wp_print_scripts action 打印脚本时 脚本输出前

首页（Home Page）

钩子名称 类型 执行时机 常用用途
home_template filter 选择首页模板时 修改首页模板
homepage action 首页特定钩子 首页特定功能
loop_start action 循环开始时 循环开始时的处理
the_post action 设置当前文章数据时 每篇文章前的处理

文章页（Single Post）

钩子名称 类型 执行时机 常用用途
single_template filter 选择文章模板时 修改文章模板
the_post action 文章数据设置后 文章特定处理
the_content filter 输出内容时 过滤文章内容
the_excerpt filter 输出摘要时 过滤文章摘要
get_the_excerpt filter 获取摘要时 修改摘要内容
post_thumbnail_html filter 输出特色图像时 修改特色图像HTML

页面（Page）

钩子名称 类型 执行时机 常用用途
page_template filter 选择页面模板时 修改页面模板
page_link filter 生成页面链接时 修改页面链接

分类/标签页（Archive）

钩子名称 类型 执行时机 常用用途
archive_template filter 选择归档模板时 修改归档模板
category_template filter 选择分类模板时 修改分类模板
tag_template filter 选择标签模板时 修改标签模板
term_description filter 输出分类描述时 修改分类描述
get_the_archive_title filter 获取归档标题时 修改归档标题
get_the_archive_description filter 获取归档描述时 修改归档描述

搜索页（Search）

钩子名称 类型 执行时机 常用用途
search_template filter 选择搜索模板时 修改搜索模板
pre_get_search_form action 搜索表单前 搜索表单前处理
get_search_form action 获取搜索表单时 自定义搜索表单

404页面

钩子名称 类型 执行时机 常用用途
404_template filter 选择404模板时 修改404模板

附件页面

钩子名称 类型 执行时机 常用用途
attachment_template filter 选择附件模板时 修改附件模板

评论相关钩子

评论显示

钩子名称 类型 执行时机 常用用途
comments_template filter 加载评论模板时 修改评论模板
comment_form_before action 评论表单前 评论表单前内容
comment_form_after action 评论表单后 评论表单后内容
comment_form_default_fields filter 默认评论字段 修改评论表单字段
comment_form_defaults filter 评论表单默认值 修改评论表单设置
comment_text filter 输出评论内容时 过滤评论内容
get_comment_author_link filter 获取评论作者链接时 修改作者链接

评论提交

钩子名称 类型 执行时机 常用用途
pre_comment_on_post action 提交评论前 评论提交前验证
comment_post action 评论保存后 评论保存后处理
preprocess_comment filter 处理评论前 评论数据预处理

侧边栏和小部件

侧边栏

钩子名称 类型 执行时机 常用用途
dynamic_sidebar_before action 动态侧边栏前 侧边栏前处理
dynamic_sidebar_after action 动态侧边栏后 侧边栏后处理
is_active_sidebar filter 检查侧边栏激活状态时 修改侧边栏激活状态

小部件

钩子名称 类型 执行时机 常用用途
widget_title filter 小部件标题输出时 修改小部件标题
widget_text filter 文本小部件内容输出时 修改文本小部件内容
widget_custom_html_content filter 自定义HTML小部件内容时 修改HTML小部件内容

公共页脚区域

页脚加载

钩子名称 类型 执行时机 常用用途
get_footer action 获取页脚模板时 页脚加载前处理
wp_footer action 页脚输出时 输出页脚脚本和内容
admin_bar_menu action 管理工具栏渲染时 修改管理工具栏
wp_print_footer_scripts action 打印页脚脚本时 页脚脚本输出前

循环结束

钩子名称 类型 执行时机 常用用途
loop_end action 循环结束时 循环结束后的处理

后台管理页面钩子

后台初始化

钩子名称 类型 执行时机 常用用途
admin_init action 后台初始化时 后台设置、权限检查
admin_menu action 构建后台菜单时 添加管理菜单
admin_enqueue_scripts action 排队后台脚本时 注册后台脚本样式
admin_head action 后台头部输出时 后台头部内容
admin_footer action 后台页脚输出时 后台页脚内容
admin_notices action 显示后台通知时 输出管理通知
admin_bar_menu action 管理工具栏渲染时 修改后台工具栏

文章/页面编辑

钩子名称 类型 执行时机 常用用途
add_meta_boxes action 添加元框时 添加自定义元框
save_post action 保存文章时 保存文章时的处理
publish_post action 发布文章时 文章发布时的处理
transition_post_status action 文章状态转换时 状态变化处理
edit_form_advanced action 高级编辑表单显示时 文章编辑页面
edit_page_form action 页面编辑表单显示时 页面编辑页面
wp_insert_post_data filter 插入文章数据前 修改保存前的数据

登录/注销相关钩子

登录页面

钩子名称 类型 执行时机 常用用途
login_init action 登录页面初始化时 登录页面处理
login_enqueue_scripts action 登录页面排队脚本时 登录页面脚本样式
login_head action 登录页面头部输出时 登录页面头部内容
login_form action 登录表单显示时 登录表单修改
login_footer action 登录页面页脚输出时 登录页面页脚内容
wp_login action 用户登录时 登录成功后的处理
wp_logout action 用户注销时 注销后的处理

REST API 钩子

API 初始化

钩子名称 类型 执行时机 常用用途
rest_api_init action REST API初始化时 注册API路由和字段
rest_pre_dispatch filter API调度前 修改API请求
rest_authentication_errors filter API认证错误时 自定义API认证

API 端点

钩子名称 类型 执行时机 常用用途
rest_prepare_{$post_type} filter 准备文章数据时 修改API响应
rest_insert_{$post_type} action 插入文章数据时 API创建文章时的处理

AJAX 钩子

AJAX 处理

钩子名称 类型 执行时机 常用用途
wp_ajax_{$action} action 已登录用户AJAX请求 处理登录用户AJAX
wp_ajax_nopriv_{$action} action 未登录用户AJAX请求 处理未登录用户AJAX
wp_ajax_admin_bar_render action 管理工具栏AJAX渲染 工具栏AJAX处理

主题定制器钩子

定制器界面

钩子名称 类型 执行时机 常用用途
customize_register action 定制器注册时 添加定制器部分和控件
customize_preview_init action 定制器预览初始化时 预览脚本初始化
customize_controls_enqueue_scripts action 定制器控件脚本排队时 定制器控件脚本样式

插件和主题更新

更新过程

钩子名称 类型 执行时机 常用用途
upgrader_process_complete action 更新完成时 更新后处理
upgrader_pre_install action 安装前 安装前检查
upgrader_post_install action 安装后 安装后处理
auto_updater_complete action 自动更新完成时 自动更新后处理

数据库和缓存

数据保存

钩子名称 类型 执行时机 常用用途
updated_option action 选项更新后 选项更新后处理
added_option action 选项添加后 新选项添加后处理
delete_option action 删除选项前 选项删除前的处理
set_transient action 设置瞬态数据时 瞬态数据设置时处理
delete_transient action 删除瞬态数据时 瞬态数据删除时处理

多站点网络

网络管理

钩子名称 类型 执行时机 常用用途
wpmu_new_blog action 新建站点时 新站点创建后的处理
delete_blog action 删除站点时 站点删除时的处理
network_admin_menu action 网络管理菜单构建时 网络管理菜单添加

执行结束阶段

清理和关闭

钩子名称 类型 执行时机 常用用途
shutdown action WordPress执行结束时 最后执行的动作
wp_die_ajax_handler filter AJAX错误处理时 自定义AJAX错误处理
wp_die_handler filter 错误处理时 自定义错误处理

重要说明

典型的前端页面执行流程

muplugins_loaded → plugins_loaded → after_setup_theme → init → wp_loaded → parse_request → send_headers → parse_query → pre_get_posts → wp → template_redirect → get_header → wp_head → wp_body_open → loop_start → the_post → the_content → loop_end → get_sidebar → get_footer → wp_footer → shutdown

典型的后台执行流程

muplugins_loaded → plugins_loaded → after_setup_theme → init → admin_init → admin_menu → current_screen → load-(page) → admin_enqueue_scripts → admin_head → in_admin_header → admin_notices → (具体页面处理) → admin_footer → shutdown