本文介绍在 contact form 7 提交后，如何通过 php 预处理服务器响应并注入自定义字段，再在前端 js 中读取该字段实现条件重定向，从而突破默认仅支持静态跳转的限制。
本文介绍在 contact form 7 提交后，如何通过 php 预处理服务器响应并注入自定义字段，再在前端 js 中读取该字段实现条件重定向，从而突破默认仅支持静态跳转的限制。
Contact Form 7（CF7）本身不提供基于动态 API 响应的条件跳转能力——其内置的「Redirect URL」仅支持固定链接，而 wpcf7mailsent JS 事件中无法直接访问后端返回的完整 JSON 响应体（如 API 调用结果）。但通过 CF7 提供的扩展机制，我们可以在服务端预埋结构化数据，并在客户端安全读取，实现精准路由控制。
✅ 核心方案：add_result_props() 注入响应元数据
CF7 的 wpcf7_before_send_mail 钩子允许你在邮件发送前操作 $submission 对象。关键在于使用 add_result_props() 方法向最终响应中添加自定义属性（这些属性会序列化进 AJAX 返回的 result 对象中），例如：
// functions.php 或插件文件中
add_action('wpcf7_before_send_mail', 'cf7_handle_api_logic_and_inject_redirect');
function cf7_handle_api_logic_and_inject_redirect($contact_form) {
$submission = WPCF7_Submission::get_instance();
if (!$submission) return;
// 模拟调用外部 API（请替换为你的实际逻辑）
$api_response = wp_remote_post('https://your-api.com/validate', [
'body' => ['form_data' => $submission->get_posted_data()],
'timeout' => 15,
]);
if (is_wp_error($api_response)) {
$submission->set_status('validation_failed');
return;
}
$body = json_decode(wp_remote_retrieve_body($api_response), true);
// 根据 API 返回决定跳转目标（支持多条件）
$redirect_url = '';
if (!empty($body['status']) && $body['status'] === 'approved') {
$redirect_url = home_url('/success/');
} elseif (!empty($body['redirect_key'])) {
$redirect_url = esc_url(home_url('/redirect/' . $body['redirect_key']));
} else {
$redirect_url = home_url('/error/');
}
// 将跳转地址和其他上下文注入响应对象（关键！）
$submission->add_result_props([
'redirect_url' => $redirect_url,
'api_status' => $body['status'] ?? 'unknown',
'debug_info' => $body // 可选：仅开发时启用
]);
}⚠️ 注意事项：
- add_result_props() 必须在 wpcf7_before_send_mail 中调用，且 $submission 实例必须存在；
- 所有值需确保已过滤（如 esc_url() 处理 URL），避免 XSS 风险；
- 若需传递敏感信息，请勿在此处暴露，应改用 session 或 token 化方式。
✅ 前端 JS：在 wpcf7mailsent 中读取并跳转
CF7 会在 wpcf7mailsent 事件的 event.detail 中附带完整的响应对象（含你注入的属性），无需额外 AJAX 请求：
document.addEventListener('wpcf7mailsent', function(event) {
const formData = event.detail;
// 安全读取注入的 redirect_url（带 fallback）
const redirectUrl = formData.apiResponse?.redirect_url
|| formData.redirect_url
|| '';
if (redirectUrl && typeof window !== 'undefined') {
// 推荐使用 replace() 避免用户可回退到表单页
window.location.replace(redirectUrl);
}
}, false);? 提示：CF7 v5.8+ 的 event.detail 结构中，自定义属性位于 apiResponse 下（旧版本可能直接挂顶层）；建议始终做空值校验，保障脚本健壮性。
✅ 进阶建议
- 错误处理：可在 PHP 中调用 $submission->set_status('failed') 并设置 add_result_props(['error_code' => 'api_timeout'])，前端据此显示定制提示；
- 调试技巧：临时在 JS 中 console.log(event.detail) 查看实际响应结构；
- SEO 友好：对重要跳转页（如 success/error），确保其内容语义清晰、有明确 H1 和描述，避免被误判为软 404。
通过 add_result_props() 桥接 PHP 逻辑与前端行为，你不仅能实现 API 驱动的重定向，还可扩展为动态消息提示、A/B 测试分流、CRM 同步状态反馈等场景——真正让 CF7 表单具备现代 Web 应用的交互能力。
