WordPress 免费样品申请页

一套适用于 WordPress 企业网站的免费样品申请页面，支持产品分类展示、样品多选、表单校验、WordPress AJAX 提交、邮件通知和基础防刷机制。

页面采用原生 HTML、CSS、JavaScript 和 PHP 开发，不依赖第三方前端框架。CSS、JS、产品图片及 WordPress 后端代码均已分离，方便后期替换产品、调整样式和维护表单逻辑。

在线预览

查看免费样品申请页

在线预览使用模拟提交，不会保存或发送表单数据。真实 AJAX 和邮件通知功能需要部署到 WordPress 后测试。

核心功能

• 按“户外地板、共挤地板、墙板、方通”分类展示产品；
• 每个产品分类最多选择 3 款样品；
• 实时显示各分类选择数量和全部已选产品；
• 支持姓名、公司、邮箱、电话、国家、用途、地址和留言；
• 提供前端必填项、邮箱和电话格式校验；
• 通过 WordPress admin-ajax.php 提交申请；
• 同时支持登录用户和未登录访客；
• 向管理员发送完整申请邮件；
• 向申请人发送确认邮件；
• 服务端再次验证产品白名单和每类限选规则；
• 包含 Nonce、蜜罐、提交速度和 IP 哈希频率限制；
• 响应式布局，支持桌面端、平板和手机端；
• 当前版本不创建数据表，不在 WordPress 数据库中保存申请记录。

技术组成

部分	技术
页面结构	HTML5
页面样式	CSS3、响应式布局
前端交互	原生 JavaScript、Fetch API
后端接口	WordPress AJAX、PHP
邮件发送	WordPress wp_mail()、PHPMailer/SMTP
安全处理	Nonce、字段清洗、白名单、蜜罐、频率限制
产品图片	独立 SVG 占位图，可替换为 JPG、PNG 或 WebP

目录结构

free-sample-page/
├─ index.html
├─ README.md
├─ css/
│  └─ free-sample.css
├─ js/
│  └─ free-sample.js
├─ assets/
│  └─ images/
│     └─ products/
│        ├─ ipd01-ic02.svg
│        ├─ ppd01-pc04.svg
│        └─ ...
└─ wordpress-integration/
   ├─ README-WordPress.md
   ├─ functions-free-sample.php
   └─ wordpress-page-content.html

主要文件说明

文件	作用
index.html	独立前端预览入口，未连接 WordPress 时使用模拟提交
css/free-sample.css	页面全部样式，已限定在 .free-sample-app 内
js/free-sample.js	产品数据、选择规则、表单校验和 AJAX 请求
assets/images/products/	产品图片目录
functions-free-sample.php	需要加入子主题 functions.php 的资源加载及后端代码
wordpress-page-content.html	粘贴到 WordPress 页面“自定义 HTML”区块的内容

本地预览

下载源码后，直接使用浏览器打开 index.html 即可查看页面和测试前端交互。

本地模式下提交按钮只执行前端校验，不会发送邮件，也不会保存任何数据。

WordPress 部署

建议使用子主题，避免父主题升级后覆盖相关文件。

1. 上传项目目录

将整个 free-sample-page 文件夹上传到当前子主题根目录：

/wp-content/themes/你的子主题/free-sample-page/

2. 添加 functions.php 代码

1. 备份子主题的 functions.php；
2. 打开 wordpress-integration/functions-free-sample.php；
3. 复制“代码开始”到“代码结束”之间的全部内容；
4. 将代码粘贴到子主题 functions.php 末尾。

如果 functions.php 已经包含 <?php，不要重复添加 PHP 开始标签。

该代码负责：

• 仅在免费样品页加载 CSS 和 JS；
• 向 JavaScript 注入 AJAX 地址和 Nonce；
• 接收并验证表单数据；
• 检查产品编号和每类限选数量；
• 执行防刷检查；
• 发送管理员通知及申请人确认邮件。

3. 创建 WordPress 页面

1. 在 WordPress 后台新建页面；
2. 页面固定链接别名设置为 free-sample；
3. 页面模板优先选择“全宽”或主题提供的空白模板；
4. 添加“自定义 HTML”区块；
5. 将 wordpress-integration/wordpress-page-content.html 的内容完整粘贴进去；
6. 发布页面并清理 WordPress、SiteGround 和 Cloudflare 缓存。

CSS 和 JS 已由 functions.php 自动加载，不要再把 index.html 中的 <link> 和 <script> 标签粘贴到 WordPress 页面。

邮件接收地址

管理员通知邮件默认发送到：

WordPress 后台 → 设置 → 常规 → 管理员电子邮箱地址

如果需要使用单独的样品申请邮箱，可将以下代码添加到子主题 functions.php：

add_filter( 'coowin_free_sample_recipient', function () {
	return 'samples@example.com';
} );

系统默认向申请人发送确认邮件。如不需要，可添加：

add_filter( 'coowin_free_sample_send_confirmation', '__return_false' );

在 functions.php 中配置 SMTP

WordPress 默认通过 wp_mail() 发送邮件。部分主机环境可能出现邮件被拒收、进入垃圾箱或无法送达的问题，建议使用与网站域名一致的企业邮箱配置 SMTP。

将下面代码添加到子主题 functions.php，并根据 SiteGround 邮箱连接信息修改占位内容：

/**
 * 配置 WordPress SMTP 邮件发送。
 * 上线前请替换全部示例值，不要把真实密码提交到 GitHub。
 */
function coowin_configure_smtp( $phpmailer ) {
	$phpmailer->isSMTP();

	// SMTP 服务器地址，例如 mail.example.com。
	$phpmailer->Host = 'mail.example.com';

	// 启用 SMTP 身份验证。
	$phpmailer->SMTPAuth = true;

	// 完整邮箱账号和邮箱密码。
	$phpmailer->Username = 'samples@example.com';
	$phpmailer->Password = 'your-email-password';

	// 常用配置：587 + tls；如果主机要求 465 端口，请改为 ssl。
	$phpmailer->Port       = 587;
	$phpmailer->SMTPSecure = 'tls';

	// 发件邮箱应与 SMTP 登录邮箱保持一致。
	$phpmailer->From     = 'samples@example.com';
	$phpmailer->FromName = get_bloginfo( 'name' );

	$phpmailer->CharSet = 'UTF-8';
}
add_action( 'phpmailer_init', 'coowin_configure_smtp' );

如果 SiteGround 提供的配置为 465 端口，请修改为：

$phpmailer->Port       = 465;
$phpmailer->SMTPSecure = 'ssl';

SMTP 密码安全

上面的代码适合说明配置结构，但不应把真实密码提交到公开仓库。更安全的方式是把账号和密码写入服务器上的 wp-config.php：

define( 'COOWIN_SMTP_USERNAME', 'samples@example.com' );
define( 'COOWIN_SMTP_PASSWORD', 'your-email-password' );

然后将 functions.php 中的账号和密码改为：

$phpmailer->Username = defined( 'COOWIN_SMTP_USERNAME' ) ? COOWIN_SMTP_USERNAME : '';
$phpmailer->Password = defined( 'COOWIN_SMTP_PASSWORD' ) ? COOWIN_SMTP_PASSWORD : '';

wp-config.php 不应上传到 GitHub。公开仓库、README、截图和提交记录中都不能包含真实邮箱密码。

SMTP 失败日志（可选）

调试阶段可临时把邮件错误写入 WordPress 调试日志：

function coowin_log_mail_error( $error ) {
	if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
		error_log( 'WordPress mail error: ' . $error->get_error_message() );
	}
}
add_action( 'wp_mail_failed', 'coowin_log_mail_error' );

测试完成后可删除这段日志代码，或保持 WP_DEBUG 为关闭状态。

修改页面别名

默认页面别名为 free-sample。如果需要使用其他别名，可在子主题 functions.php 中添加：

add_filter( 'coowin_free_sample_page_slug', function () {
	return 'your-page-slug';
} );

修改产品和图片

产品分类及编号集中在：

js/free-sample.js

产品图片位于：

assets/images/products/

默认图片文件名使用产品编号的小写形式，例如：

IPD01-IC02 → ipd01-ic02.svg

替换正式产品图片时，可以保持文件名不变直接覆盖。如果改用 JPG、PNG 或 WebP，需要同时修改 free-sample.js 中生成图片路径的扩展名。

前端产品列表和 functions-free-sample.php 中的服务端产品白名单必须保持一致。新增或删除产品时，需要同时修改这两个位置。

表单处理流程

flowchart TD
    A[选择产品样品] --> B[填写申请信息]
    B --> C[前端格式校验]
    C --> D[WordPress AJAX 提交]
    D --> E[Nonce 与防刷检查]
    E --> F[字段清洗与产品白名单校验]
    F --> G[发送管理员通知邮件]
    G --> H[发送申请人确认邮件]

Loading

安全设计

• 使用 WordPress Nonce 验证请求来源；
• 服务端对所有字段执行清洗和格式检查；
• 服务端维护独立产品白名单；
• 前端和后端同时限制每个分类最多选择 3 款；
• 使用隐藏蜜罐字段拦截基础机器人；
• 限制提交速度；
• 同一 IP 哈希每小时最多成功发起 5 次请求；
• 不保存访客明文 IP；
• 不在数据库中保存申请表单内容；
• CSS 限定在 .free-sample-app 内，减少与 WordPress 主题样式冲突。

上线前测试

1. 在两个以上分类中选择产品；
2. 确认每个分类最多只能选择 3 款；
3. 检查姓名、邮箱、电话和必填项校验；
4. 使用真实可接收邮件的地址提交申请；
5. 检查管理员通知邮件；
6. 检查申请人确认邮件；
7. 检查邮件回复地址是否为申请人邮箱；
8. 分别测试桌面端和手机端；
9. 清理 WordPress、SiteGround 和 Cloudflare 缓存后再次测试；
10. 如果邮件未送达，检查 SMTP 配置、垃圾邮件目录和 SiteGround 邮件日志。

当前限制

• 当前版本以邮件通知为主，不保存后台申请记录；
• 在线预览不运行 WordPress/PHP 后端；
• 真实邮件送达情况需要在实际 WordPress 和 SMTP 环境中测试；
• 不同主题的内容宽度可能不同，建议使用全宽或空白页面模板。

版本信息

当前版本：v1.2.0

本版本已完成前端资源拆分、每个分类最多选择 3 款、WordPress AJAX 接入、服务器端安全校验、管理员邮件通知、申请人确认邮件和 SMTP 配置说明。