本教程详细阐述如何在 wordpress 后台为自定义文章类型扩展搜索功能，使其能够同时识别和匹配不同语言的数字表示（如波斯语和英语数字）。通过利用 `pre_get_posts` 钩子，我们能够动态修改查询参数，实现搜索词的“or”逻辑组合，从而显著提升后台搜索的灵活性和用户体验，尤其适用于处理多语言或国际化内容的网站。
在 WordPress 中，自定义文章类型（Custom Post Types）极大地扩展了内容管理的能力。然而，默认的后台搜索功能有时无法满足特定需求，尤其是在处理多语言数据或需要特殊字符匹配时。例如，当您的网站内容包含波斯语数字（۰-۹）和英语数字（0-9），并且用户可能使用任一形式进行搜索时，默认的搜索机制可能无法同时匹配这两种表示，导致搜索结果不完整。本教程将指导您如何通过 pre_get_posts 钩子来增强 WordPress 后台的搜索查询，实现对自定义文章类型中多语言数字的混合匹配。
pre_get_posts 钩子：查询修改的核心
pre_get_posts 是 WordPress 中一个非常强大的动作钩子，它允许我们在主查询（WP_Query 对象）执行之前对其进行修改。这意味着我们可以调整任何查询的参数，包括搜索词、文章类型、分类、标签、元数据等，从而完全控制 WordPress 如何检索和显示内容。利用此钩子，我们可以拦截后台的搜索请求，并注入自定义的搜索逻辑。
实现多语言数字混合搜索
要实现对波斯语和英语数字的混合搜索，我们需要在 pre_get_posts 钩子中执行以下步骤：
- 限定查询范围：确保我们的修改只影响特定的自定义文章类型，并且只在后台进行搜索时生效。
- 获取与净化搜索词：获取用户输入的原始搜索词，并进行安全处理。
- 数字转换逻辑：将原始搜索词分别转换为波斯语数字形式和英语数字形式。
- 构建“OR”逻辑搜索词：将转换后的两种数字形式组合成一个特殊的搜索字符串，以便 WP_Query 能够同时匹配它们。
- 更新查询参数：使用新的组合搜索字符串更新 WP_Query 对象的 s 参数。
1. 限定查询范围
首先，我们需要在钩子函数内部检查当前请求是否来自 WordPress 后台，并且是否针对我们想要修改的自定义文章类型。
if (is_admin() && in_array($query->get('post_type'), array('your_custom_post_type_slug'))) {
// ... 在此处添加我们的搜索逻辑
}将 'your_custom_post_type_slug' 替换为您实际的自定义文章类型 slug。in_array() 的使用允许您轻松地支持多个自定义文章类型。
2. 获取与净化搜索词
通过 $query->query_vars['s'] 可以获取到当前的搜索词。为了安全起见，我们应该使用 sanitize_text_field() 函数对它进行净化。
$search_term = sanitize_text_field($query->query_vars['s']);
3. 数字转换逻辑
接下来，我们需要定义波斯语和英语数字的映射关系，并实现将搜索词中的数字在这两种形式之间相互转换的逻辑。
$persian = ['۰', '۱', '۲', '۳', '۴', '۵', '۶', '۷', '۸', '۹']; $num = range(0, 9); // 将搜索词中的英语数字转换为波斯语数字 $persianNumbersOnly = str_replace($num, $persian, $search_term); // 将搜索词中的波斯语数字转换为英语数字 $englishNumbersOnly = str_replace($persian, $num, $search_term);
这段代码会创建两个版本的搜索词：一个主要包含波斯语数字（如果原始搜索词中包含英语数字，会被转换为波斯语），另一个主要包含英语数字（如果原始搜索词中包含波斯语数字，会被转换为英语）。
4. 构建“OR”逻辑搜索词
WP_Query 的 s 参数（搜索词）有一个鲜为人知但非常有用的特性：如果搜索字符串中包含 + 号，WP_Query 会将其解析为多个独立的搜索关键词，并以“OR”的关系进行匹配。这正是我们实现多语言数字混合搜索的关键。
我们将转换后的波斯语和英语数字版本的搜索词用 + 号连接起来。
$combined_search_term = strval($englishNumbersOnly) . '+' . strval($persianNumbersOnly);
strval() 函数在此处并非严格必要，但可以确保连接的是字符串类型，避免潜在的类型错误或警告。
5. 更新查询参数
最后，我们使用 $query->set() 方法将新的组合搜索词设置回 WP_Query 对象的 s 参数。
$query->set('s', $combined_search_term);完整示例代码
将以上所有步骤整合到您的主题 functions.php 文件或自定义插件中：
get('post_type'), $target_post_types)) {
// 获取原始搜索词并进行安全净化
$search_term = sanitize_text_field($query->query_vars['s']);
// 定义波斯语数字和英语数字的映射
$persian = ['۰', '۱', '۲', '۳', '۴', '۵', '۶', '۷', '۸', '۹'];
$num = range(0, 9); // 英语数字 0-9
// 将搜索词中的英语数字转换为波斯语数字形式
$persianNumbersOnly = str_replace($num, $persian, $search_term);
// 将搜索词中的波斯语数字转换为英语数字形式
$englishNumbersOnly = str_replace($persian, $num, $search_term);
// 使用 '+' 号将两种数字形式的搜索词组合起来，实现 'OR' 逻辑
// WP_Query 会将 '+' 号分隔的关键词视为独立的搜索项进行匹配
$combined_search_term = strval($englishNumbersOnly) . '+' . strval($persianNumbersOnly);
// 更新 WP_Query 的 's' 参数为组合后的搜索词
$query->set('s', $combined_search_term);
}
}
// 将函数挂载到 'pre_get_posts' 钩子
add_action('pre_get_posts', 'custom_admin_search_for_numbers');请务必将 'custom_post_type' 替换为您实际的自定义文章类型 slug。
注意事项与最佳实践
- 精确控制查询范围：使用 is_admin() 和 in_array($query->get('post_type'), $target_post_types) 是非常重要的，它确保您的修改只影响后台的特定自定义文章类型搜索，避免意外影响其他查询。
- 安全性：始终使用 sanitize_text_field() 等 WordPress 提供的净化函数来处理用户输入，防止 XSS 攻击或其他安全漏洞。
- 可扩展性：通过将目标文章类型放入数组中，您可以轻松地为多个自定义文章类型应用相同的搜索逻辑，只需在 $target_post_types 数组中添加相应的 slug 即可。
- $query->set() 的使用：相对于直接修改 $query->query_vars 数组，使用 $query->set() 方法是更推荐的做法，它提供了更健壮和可预测的方式来修改查询参数。
- + 号的语义：理解 + 号在 s 参数中的特殊作用是实现此功能的核心。它允许您在不编写复杂 WP_Query 过滤器的情况下，实现简单的“OR”逻辑。
- 测试的重要性：在部署到生产环境之前，务必在开发环境中充分测试此功能，确保它按预期工作，并且不会引入任何副作用。
总结
通过上述方法，我们成功地增强了 WordPress 后台自定义文章类型的搜索功能，使其能够智能地处理多语言数字的混合查询。这种技术不仅提升了管理员在处理国际化内容时的效率和体验，也展示了 pre_get_posts 钩子在自定义 WordPress 查询方面的强大灵活性。掌握这一技巧，您将能够为您的 WordPress 网站构建更加强大和用户友好的搜索功能。
