EP232. “自定义 query var：URL 参数驱动条件内容”

补上课程前面（传统搜索章节）留下的一个伏笔：怎么实现一个「无 JavaScript 也能工作」的自定义 URL 参数机制。默认情况下，WordPress 只认识它自己内置的一小撮 URL 参数（比如 s 表示搜索、page 表示分页），任何自己发明的参数名（比如 ?skyColor=blue）都会被直接忽略——想让 WordPress「注意到」这个参数、并能在 PHP 里读取它的值，需要用 query_vars 这个过滤器把参数名手动注册进去，之后就能用 get_query_var() 读取。这一讲用一个简单例子（URL 带 skyColor=blue&grassColor=green 时显示一句彩蛋文字）演示完整流程，并说明这类参数配合一个 method="get" 的 HTML 表单，就能做出「不用任何 JS、纯 URL 驱动」的交互功能，还天然具备「结果页面可以直接复制链接分享」的优点。

涉及文件

• wp-content/themes/fictional-university/functions.php （修改）
• wp-content/themes/fictional-university/page.php （修改）

代码实现

functions.php：注册两个自定义 query var：

function universityQueryVars($vars) {
  $vars[] = 'skyColor';
  $vars[] = 'grassColor';
  return $vars;
}

add_filter('query_vars', 'universityQueryVars');

page.php：读取 query var、做条件判断，并提供一个 method="get" 的表单方便测试：

<div class="generic-content">
  <?php the_content();

    $skyColorValue = sanitize_text_field(get_query_var('skyColor'));
    $grassColorValue = sanitize_text_field(get_query_var('grassColor'));

    if ($skyColorValue == 'blue' AND $grassColorValue == 'green') {
      echo '<p>The sky is blue today and the grass is green. Life is good.</p>';
    }

  ?>
   
   <form method="get">
    <input name="skyColor" placeholder="Sky color">
    <input name="grassColor" placeholder="Grass color">
    <button>Submit</button>
   </form>
   
</div>

关键改动点：

• 为什么需要手动注册：WordPress 出于性能和安全考虑，默认只识别自己内置的一小撮 URL 参数——任何自定义参数名（比如访问 /about-us?skyColor=blue）不会自动生效，get_query_var() 读到的会是空值，必须先通过 query_vars 这个过滤器「登记」这个参数名，WordPress 才会真正留意它
• add_filter('query_vars', $回调函数)：回调函数接收一个数组参数（$vars，当前所有已注册的 query var 名字列表），在函数体内往这个数组里追加自己的新参数名（$vars[] = 'skyColor'），最后 return $vars——这是标准的 WordPress 过滤器写法：拿到默认值、做修改、返回修改后的结果
• get_query_var('参数名')——读取当前 URL 里这个参数的值：这个函数在任何模板文件里都能直接调用,不需要自己解析 $_GET
• 读取后立刻用 sanitize_text_field() 清理：即使这个值只是用来做简单的字符串比较（不会被直接输出或存进数据库），依然养成「先清理再使用」的习惯，避免疏忽大意在其他场景引入风险
• 多个自定义 query var 的注册方式完全一样：只需要在同一个过滤器函数里继续 $vars[] = '另一个参数名'，这一讲演示了同时注册 skyColor/grassColor 两个参数、并在条件判断里用 AND 同时满足两个条件才显示提示文字
• method="get" 的 HTML 表单——不需要任何 JavaScript 就能把这套机制变成真正的交互功能：用户填写表单、点击提交后，浏览器会自动把每个 <input> 的 name 属性和填写的值拼成 ?skyColor=xxx&grassColor=xxx 这样的查询字符串附加在 URL 后面并跳转——这正好是自定义 query var 期望的格式，不需要写任何 JS 去手动拼接 URL
• method="get" vs method="post" 的关键取舍：get 方式提交后，参数会体现在地址栏的 URL 里，好处是访客能直接复制这个完整 URL 分享给别人，对方打开后会看到同样的筛选结果；如果改成 post，功能本身依然生效（get_query_var() 底层其实是分别处理 GET 和已注册的 query var,可以正常读到值），但地址栏会保持干净、不会带上这些参数,导致没办法通过分享链接的方式重现同一个结果——这个选择取决于「要不要支持分享带筛选条件的链接」这个产品需求，只要提交的数据不涉及隐私敏感信息,作者更偏好用 get
• 这套机制的应用范围远不止课程举的这个简单例子：作者提示可以拿这些 URL 参数的值去驱动一个自定义 WP_Query——比如按某个自定义字段筛选文章、按某种关联关系筛选内容,这才是自定义 query var 真正常见的实际用途（这门课在插件/数据库章节已经学过怎么写这类自定义查询,这里只是补上「查询条件从哪里来」这一环）

Hook / Function 速查

常见坑

• 直接用 get_query_var() 读取一个从未通过 query_vars 过滤器注册过的参数名——始终读到空值，即使 URL 里明明带着这个参数
• 读取到的 query var 值不经过 sanitize_text_field() 之类的清理就直接使用——即使当前只是做字符串比较，也应该养成统一清理的习惯
• 需要「结果页面可分享」的场景却用了 method="post"——功能本身不受影响，但地址栏不会带上参数，别人拿到的链接无法重现同样的筛选结果

[截图：页面表单填入 skyColor=blue、grassColor=green 并提交后，地址栏带上对应查询字符串、正文出现"The sky is blue today and the grass is green. Life is good."彩蛋文字的效果]

延伸 / 后续讲座会用到

下一讲（也是整门课的最后一个技术挑战）是关于职业发展方向的建议，跟 query var 这个具体技术点没有直接关联。

Sources

Udemy：

• Become a WordPress Developer: Unlocking Power With Code — Section 31, EP232