WordPress中add_query_arg函数笔记及应用示例

add_query_arg（ $args ）：字符串

检索修改后的 URL 查询字符串。

描述

您可以使用此函数重新生成 URL 并将查询变量追加到 URL 查询。
有两种方法可以使用此功能;单个键和值，或关联数组。

使用单个键和值：

wp-includes/functions.php

add_query_arg( 'key', 'value', 'http://example.com' );

使用关联数组：

wp-includes/functions.php

add_query_arg( array(
    'key1' => 'value1',
    'key2' => 'value2',
), 'http://example.com' );

从任一用途中省略 URL 会导致当前 URL 被使用（值）。$_SERVER['REQUEST_URI']

值应使用 urlencode（）或 rawurlencode（）进行适当编码。

将任何查询变量的值设置为布尔值 false 会删除键（参见 remove_query_arg（））。

重要提示：默认情况下，add_query_arg（）的返回值不会转义。输出应使用 esc_url（）或类似方式进行延迟转义，以帮助防止跨站点脚本（XSS）攻击的漏洞。

参数

$key字符串|数组必填

查询变量键或查询变量的关联数组。$value字符串自选

查询变量值或要作的 URL。$url字符串自选

要执行作的 URL。

字符串新的 URL 查询字符串（未转义）。

用法

wp-includes/functions.php

// Parameters as separate arguments
add_query_arg( $param1, $param2, $old_query_or_uri );

// Parameters as array of key => value pairs
add_query_arg(
array(
'key1' => 'value1',
'key2' => 'value2',
...
),
$old_query_or_uri
);

在WordPress多站点环境中，add_query_arg 函数的基本用法与单站点相同，但在跨站点操作生成链接时，你需要特别留意站点的上下文。

函数核心用法

add_query_arg 主要用于向现有URL添加查询参数，其好处是能自动处理参数拼接格式。

基本使用方式如下：

添加单个参数： // 向当前页面URL添加参数 $new_url = add_query_arg( 'category', 'news', get_permalink() ); // 结果示例：https://example.com/hello-world/?category=news 你也可以指定具体URL： $new_url = add_query_arg( 'id', 123, 'http://www.zzvips.com' ); // 结果：http://www.zzvips.com/?id=123
使用数组添加多个参数：
php $args = array( 'category' => 'news', 'orderby' => 'date' ); $new_url = add_query_arg( $args, get_permalink() ); // 结果示例：https://example.com/hello-world/?category=news&orderby=date

多站点中的应用场景

在多站点网络中，你常常需要为当前子站点、主站或其他特定子站点的页面生成带参数的链接。

为当前子站点生成链接：方法与单站点相同，直接使用 add_query_arg 即可，函数会自动基于当前子站点的URL构造链接。
为其他站点（主站或特定子站）生成链接：关键在于先获取目标站点的正确基础URL，然后使用 add_query_arg 添加参数。

💡 多站点使用示例

以下是在多站点网络中为不同对象生成链接的示例。

1. 为当前子站点页面添加参数

假设你在站点ID为3的子站点上，想为其一篇固定链接为 http://sub.example.com/sample-post/ 的文章添加参数：

// 获取当前子站点文章的永久链接
$post_url = get_permalink();
// 添加参数
$new_url = add_query_arg( 'ref', 'promo_2024', $post_url );
echo $new_url;

输出结果示例：
http://sub.example.com/sample-post/?ref=promo_2024

2. 为网络主站或其他子站点页面生成带参链接

关键在于使用 get_site_url() 函数并指定目标站点的ID。

// 获取站点ID为1（通常是主站）的URL
$main_site_url = get_site_url(1);
// 为主站的某个页面（如 'special-page'）添加参数
$page_url = $main_site_url . '/special-page/';
$link_with_args = add_query_arg( array( 'source' => 'network_subsite', 'campaign' => 'summer' ), $page_url );
echo $link_with_args;

输出结果示例：
http://main-example.com/special-page/?source=network_subsite&campaign=summer

3. 结合跨站点查询生成链接

如果你使用 switch_to_blog() 切换到另一个子站点获取数据，并希望基于获取的数据为该子站点的内容生成链接，可以在切换后使用 get_permalink() 或 get_site_url()。

// 切换到ID为5的子站点
switch_to_blog(5);

// 获取该子站点的一篇文章
$post_id = 101; // 假设的文章ID
$post_permalink = get_permalink($post_id);

// 为该文章的URL添加参数
$affiliate_link = add_query_arg( 'affid', 'subsite5partner', $post_permalink );

// 切换回原始站点
restore_current_blog();

// 输出链接
echo $affiliate_link;

输出结果示例：
http://site5.example.com/awesome-product/?affid=subsite5partner

子目录多站点中的使用示例

1. 为当前子站点添加参数

// 假设当前在子站点 'shop' 中
$current_url = get_site_url(); // 返回: https://example.com/shop
$new_url = add_query_arg( 'sale', 'summer', $current_url );
echo $new_url;

结果示例：
https://example.com/shop/?sale=summer

2. 为当前子站点的文章/页面添加参数

// 在子站点 'blog' 中
$post_url = get_permalink(); // 假设文章URL: https://example.com/blog/my-article/
$new_url = add_query_arg( array(
    'ref' => 'social',
    'utm_source' => 'facebook'
), $post_url );
echo $new_url;

结果示例：
https://example.com/blog/my-article/?ref=social&utm_source=facebook

3. 为主站点生成带参链接

// 获取主站URL（站点ID为1）
$main_site_url = get_site_url(1);
// 为主站页面添加参数
$main_page_url = add_query_arg( 'from', 'subsite', $main_site_url );
echo $main_page_url;

结果示例：
https://example.com/?from=subsite

4. 为其他特定子站点生成链接

// 为站点ID为3的子站点（假设路径为 /news）生成链接
$news_site_url = get_site_url(3);
$news_with_params = add_query_arg( 'category', 'sports', $news_site_url );
echo $news_with_params;

结果示例：
https://example.com/news/?category=sports

5. 跨子站点内容链接

// 切换到另一个子站点获取内容
switch_to_blog(2); // 假设这是 /store 子站点

// 获取产品页面URL
$product_url = get_permalink(45); // 产品ID 45
$affiliate_url = add_query_arg( 'affiliate_id', 'partner123', $product_url );

// 切换回来
restore_current_blog();

echo $affiliate_url;

结果示例：
https://example.com/store/product-name/?affiliate_id=partner123

子目录多站点实际应用场景

场景1：子站点间的导航链接

// 在子站点A中创建指向子站点B的带参链接
$site_b_url = get_site_url(4); // 子站点B
$promo_link = add_query_arg( 'discount', 'WELCOME20', $site_b_url );
// 结果: https://example.com/store/?discount=WELCOME20

场景2：子站点到主站的推荐链接

$main_site = get_site_url(1);
$recommend_url = add_query_arg( array(
    'recommended_by' => get_current_blog_id(),
    'campaign' => 'cross_promotion'
), $main_site );
// 结果: https://example.com/?recommended_by=2&campaign=cross_promotion

场景3：子站点内部过滤

// 在子站点文章列表页面添加过滤参数
$current_url = get_site_url() . '/articles/';
$filtered_url = add_query_arg( array(
    'category' => 'technology',
    'sort' => 'newest',
    'page' => 2
), $current_url );
// 结果: https://example.com/blog/articles/?category=technology&sort=newest&page=2

子目录多站点注意事项

路径处理：

子目录站点的URL会自动包含子目录路径
add_query_arg 会正确地将参数添加到子目录URL后面

永久链接兼容：

   // 如果使用漂亮永久链接
   $url = get_site_url() . '/my-page/';
   $result = add_query_arg( 'param', 'value', $url );
   // 结果: https://example.com/subsite/my-page/?param=value

   // 如果使用默认链接结构
   $url = get_site_url() . '/?p=123';
   $result = add_query_arg( 'param', 'value', $url );
   // 结果: https://example.com/subsite/?p=123&param=value

相对路径问题：

   // 错误方式 - 可能产生错误路径
   $bad_url = add_query_arg( 'test', 'value', '/subsite/page/' );

   // 正确方式 - 使用完整URL
   $good_url = add_query_arg( 'test', 'value', get_site_url() . '/page/' );

网络管理链接：

   // 为网络管理员生成链接
   $network_admin_url = network_admin_url( 'admin.php' );
   $admin_with_params = add_query_arg( array(
       'page' => 'network-settings',
       'tab' => 'general'
   ), $network_admin_url );

子目录多站点实用技巧

确保URL正确性

// 使用 home_url() 或 site_url() 而不是硬编码
$correct_url = add_query_arg( 'key', 'value', home_url( '/custom-path/' ) );

// 对于管理页面
$admin_url = add_query_arg( 'action', 'edit', admin_url( 'post.php' ) );

处理多语言子站点

// 假设子站点 /en/ 是英文版本
$en_site_url = get_site_url(3); // 英文子站点
$en_product_url = add_query_arg( 'lang', 'en', $en_site_url . '/product/' );

在子目录多站点中，add_query_arg 的使用逻辑与单站点基本相同，关键在于确保你操作的是正确的站点URL上下文。通过结合 get_site_url($blog_id) 来获取特定站点的URL，你可以在整个网络中的任何站点间创建准确的带参链接。

重要注意事项

上下文是关键：在多站点中，get_permalink()、get_site_url() 这类函数返回的是当前切换到的站点的URL。确保在正确的站点上下文内获取基础URL。
参数移除：如果需要从URL中移除某个参数，可以将该参数的值在数组中设为 false。
URL编码：add_query_arg 会自动对参数值进行URL编码。
性能考量：频繁切换站点 (switch_to_blog) 可能会影响性能，请确保在需要时才使用，并及时使用 restore_current_blog() 恢复。

希望这些解释和示例能帮助你在WordPress多站点项目中灵活应用 add_query_arg。如果你有更具体的应用场景，例如在特定的插件或主题中如何使用，欢迎继续交流！

WordPress函数笔记

函数

WordPress中add_query_arg函数笔记及应用示例

描述

参数

返回

用法

函数核心用法

多站点中的应用场景

💡 多站点使用示例

1. 为当前子站点页面添加参数

2. 为网络主站或其他子站点页面生成带参链接

3. 结合跨站点查询生成链接

子目录多站点中的使用示例

1. 为当前子站点添加参数

2. 为当前子站点的文章/页面添加参数

3. 为主站点生成带参链接

4. 为其他特定子站点生成链接

5. 跨子站点内容链接

子目录多站点实际应用场景

场景1：子站点间的导航链接

场景2：子站点到主站的推荐链接

场景3：子站点内部过滤

子目录多站点注意事项

子目录多站点实用技巧

确保URL正确性

处理多语言子站点

重要注意事项