add_query_arg() - WordPress 函数参考中文文档

返回介绍

add_query_arg()

发布于 2017-09-10 字数16920 浏览 1157 评论 0

add_query_arg()

Retrieves a modified URL query string.


描述

You can rebuild the URL and append query variables to the URL query by using this function. There are two ways to use this function; either a single key and value, or an associative array.

Using a single key and value:

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

Using an associative array:

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

Omitting the URL from either use results in the current URL being used (the value of $_SERVER['REQUEST_URI']).

Values are expected to be encoded appropriately with urlencode() or rawurlencode().

Setting any query variable’s value to boolean false removes the key (see remove_query_arg()).

Important: The return value of add_query_arg() is not escaped by default. Output should be late-escaped with esc_url() or similar to help prevent vulnerability to cross-site scripting (XSS) attacks.


参数

$key

(string|array)
(Required)
Either a query variable key, or an associative array of query variables.

$value

(string)
(Optional)
Either a query variable value, or a URL to act upon.

$url

(string)
(Optional)
A URL to act upon.


返回值

(string) New URL query string (unescaped).


源代码

File: wp-includes/functions.php

function add_query_arg() {
	$args = func_get_args();
	if ( is_array( $args[0] ) ) {
		if ( count( $args ) < 2 || false === $args[1] )
			$uri = $_SERVER['REQUEST_URI'];
		else
			$uri = $args[1];
	} else {
		if ( count( $args ) < 3 || false === $args[2] )
			$uri = $_SERVER['REQUEST_URI'];
		else
			$uri = $args[2];
	}

	if ( $frag = strstr( $uri, '#' ) )
		$uri = substr( $uri, 0, -strlen( $frag ) );
	else
		$frag = '';

	if ( 0 === stripos( $uri, 'http://' ) ) {
		$protocol = 'http://';
		$uri = substr( $uri, 7 );
	} elseif ( 0 === stripos( $uri, 'https://' ) ) {
		$protocol = 'https://';
		$uri = substr( $uri, 8 );
	} else {
		$protocol = '';
	}

	if ( strpos( $uri, '?' ) !== false ) {
		list( $base, $query ) = explode( '?', $uri, 2 );
		$base .= '?';
	} elseif ( $protocol || strpos( $uri, '=' ) === false ) {
		$base = $uri . '?';
		$query = '';
	} else {
		$base = '';
		$query = $uri;
	}

	wp_parse_str( $query, $qs );
	$qs = urlencode_deep( $qs ); // this re-URL-encodes things that were already in the query string
	if ( is_array( $args[0] ) ) {
		foreach ( $args[0] as $k => $v ) {
			$qs[ $k ] = $v;
		}
	} else {
		$qs[ $args[0] ] = $args[1];
	}

	foreach ( $qs as $k => $v ) {
		if ( $v === false )
			unset( $qs[$k] );
	}

	$ret = build_query( $qs );
	$ret = trim( $ret, '?' );
	$ret = preg_replace( '#=(&|$)#', '$1', $ret );
	$ret = $protocol . $base . $ret . $frag;
	$ret = rtrim( $ret, '?' );
	return $ret;
}

更新日志

Version 描述
1.5.0 Introduced.

More Information

Usage


// 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 
);

相关函数

Uses

  • wp-includes/formatting.php:
    wp_parse_str()
  • wp-includes/formatting.php:
    urlencode_deep()
  • wp-includes/functions.php:
    build_query()

Used By

  • wp-includes/widgets/class-wp-widget-media-video.php:
    WP_Widget_Media_Video::render_media()
  • wp-includes/class-wp-customize-manager.php:
    WP_Customize_Manager::add_state_query_params()
  • wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php:
    WP_REST_Users_Controller::get_items()
  • wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php:
    WP_REST_Post_Statuses_Controller::prepare_item_for_response()
  • wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php:
    WP_REST_Terms_Controller::prepare_links()
  • wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php:
    WP_REST_Terms_Controller::get_items()
  • wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php:
    WP_REST_Posts_Controller::prepare_links()
  • wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php:
    WP_REST_Posts_Controller::get_items()
  • wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php:
    WP_REST_Comments_Controller::prepare_links()
  • wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php:
    WP_REST_Comments_Controller::get_items()
  • wp-includes/link-template.php:
    wp_get_canonical_url()
  • wp-admin/includes/ms.php:
    network_edit_site_nav()
  • wp-admin/includes/ajax-actions.php:
    wp_ajax_search_install_plugins()
  • wp-admin/includes/ajax-actions.php:
    wp_ajax_search_plugins()
  • wp-admin/includes/ajax-actions.php:
    wp_ajax_install_theme()
  • wp-admin/includes/ajax-actions.php:
    wp_ajax_install_plugin()
  • wp-includes/rest-api.php:
    get_rest_url()
  • wp-includes/embed.php:
    get_post_embed_url()
  • wp-includes/embed.php:
    get_oembed_endpoint_url()
  • wp-includes/class-wp-customize-manager.php:
    WP_Customize_Manager::customize_pane_settings()
  • wp-includes/link-template.php:
    get_preview_post_link()
  • wp-admin/includes/class-wp-posts-list-table.php:
    WP_Posts_List_Table::get_edit_link()
  • wp-includes/admin-bar.php:
    wp_admin_bar_customize_menu()
  • wp-admin/includes/class-wp-ms-themes-list-table.php:
    WP_MS_Themes_List_Table::column_name()
  • wp-admin/includes/class-wp-terms-list-table.php:
    WP_Terms_List_Table::handle_row_actions()
  • wp-admin/includes/class-wp-ms-users-list-table.php:
    WP_MS_Users_List_Table::handle_row_actions()
  • wp-admin/includes/class-wp-ms-users-list-table.php:
    WP_MS_Users_List_Table::column_username()
  • wp-admin/includes/class-wp-media-list-table.php:
    WP_Media_List_Table::column_author()
  • wp-admin/includes/class-wp-media-list-table.php:
    WP_Media_List_Table::column_parent()
  • wp-admin/includes/class-wp-media-list-table.php:
    WP_Media_List_Table::column_default()
  • wp-includes/customize/class-wp-customize-theme-control.php:
    WP_Customize_Theme_Control::content_template()
  • wp-includes/link-template.php:
    get_avatar_data()
  • wp-admin/includes/theme.php:
    customize_themes_print_templates()
  • wp-admin/includes/media.php:
    wp_media_attach_action()
  • wp-admin/includes/theme.php:
    wp_prepare_themes_for_js()
  • wp-admin/includes/theme.php:
    get_theme_update_available()
  • wp-admin/includes/class-wp-plugins-list-table.php:
    WP_Plugins_List_Table::get_views()
  • wp-admin/includes/class-wp-plugins-list-table.php:
    WP_Plugins_List_Table::__construct()
  • wp-admin/includes/class-theme-upgrader-skin.php:
    Theme_Upgrader_Skin::after()
  • wp-admin/includes/class-theme-installer-skin.php:
    Theme_Installer_Skin::after()
  • wp-admin/includes/class-wp-list-table.php:
    WP_List_Table::view_switcher()
  • wp-admin/includes/class-wp-list-table.php:
    WP_List_Table::comments_bubble()
  • wp-admin/includes/class-wp-list-table.php:
    WP_List_Table::pagination()
  • wp-admin/includes/class-wp-list-table.php:
    WP_List_Table::print_column_headers()
  • wp-admin/includes/class-wp-list-table.php:
    WP_List_Table::set_pagination_args()
  • wp-admin/includes/class-wp-ms-themes-list-table.php:
    WP_MS_Themes_List_Table::get_views()
  • wp-admin/includes/misc.php:
    set_screen_options()
  • wp-admin/includes/class-wp-theme-install-list-table.php:
    WP_Theme_Install_List_Table::install_theme_info()
  • wp-admin/includes/class-wp-theme-install-list-table.php:
    WP_Theme_Install_List_Table::single_row()
  • wp-admin/includes/update.php:
    wp_theme_update_row()
  • wp-admin/includes/plugin-install.php:
    install_plugin_information()
  • wp-admin/includes/dashboard.php:
    wp_dashboard_browser_nag()
  • wp-admin/includes/dashboard.php:
    wp_add_dashboard_widget()
  • wp-admin/includes/plugin.php:
    menu_page_url()
  • wp-admin/includes/plugin.php:
    activate_plugin()
  • wp-admin/includes/plugin.php:
    activate_plugins()
  • wp-admin/includes/class-wp-plugin-install-list-table.php:
    WP_Plugin_Install_List_Table::display_rows()
  • wp-admin/includes/class-wp-users-list-table.php:
    WP_Users_List_Table::single_row()
  • wp-admin/includes/class-wp-users-list-table.php:
    WP_Users_List_Table::get_views()
  • wp-admin/includes/media.php:
    media_upload_library_form()
  • wp-admin/includes/media.php:
    the_media_upload_tabs()
  • wp-admin/includes/media.php:
    get_upload_iframe_src()
  • wp-admin/includes/post.php:
    _admin_notice_post_locked()
  • wp-admin/includes/ajax-actions.php:
    wp_ajax_query_themes()
  • wp-admin/includes/revision.php:
    wp_prepare_revisions_for_js()
  • wp-admin/includes/class-wp-comments-list-table.php:
    WP_Comments_List_Table::column_author()
  • wp-admin/includes/class-wp-comments-list-table.php:
    WP_Comments_List_Table::get_views()
  • wp-admin/includes/class-wp-terms-list-table.php:
    WP_Terms_List_Table::column_name()
  • wp-admin/includes/class-wp-terms-list-table.php:
    WP_Terms_List_Table::column_posts()
  • wp-admin/includes/class-walker-nav-menu-edit.php:
    Walker_Nav_Menu_Edit::start_el()
  • wp-admin/includes/nav-menu.php:
    wp_nav_menu_item_post_type_meta_box()
  • wp-admin/includes/nav-menu.php:
    wp_nav_menu_item_taxonomy_meta_box()
  • wp-admin/includes/widgets.php:
    wp_widget_control()
  • wp-admin/includes/import.php:
    wp_get_popular_importers()
  • wp-admin/custom-header.php:
    Custom_Image_Header::step_1()
  • wp-admin/custom-header.php:
    Custom_Image_Header::step_2()
  • wp-admin/includes/post.php:
    redirect_post()
  • wp-admin/menu-header.php:
    _wp_menu_output()
  • wp-includes/class.wp-styles.php:
    WP_Styles::_css_href()
  • wp-includes/cron.php:
    spawn_cron()
  • wp-includes/general-template.php:
    paginate_links()
  • wp-includes/general-template.php:
    wp_admin_css_uri()
  • wp-includes/general-template.php:
    wp_get_archives()
  • wp-includes/general-template.php:
    wp_logout_url()
  • wp-includes/general-template.php:
    wp_login_url()
  • wp-includes/general-template.php:
    wp_lostpassword_url()
  • wp-includes/deprecated.php:
    wp_get_links()
  • wp-includes/deprecated.php:
    dropdown_cats()
  • wp-includes/functions.php:
    wp_auth_check_html()
  • wp-includes/functions.php:
    wp_nonce_url()
  • wp-includes/functions.php:
    remove_query_arg()
  • wp-includes/link-template.php:
    get_comments_pagenum_link()
  • wp-includes/link-template.php:
    paginate_comments_links()
  • wp-includes/link-template.php:
    get_pagenum_link()
  • wp-includes/link-template.php:
    get_edit_user_link()
  • wp-includes/link-template.php:
    get_search_comments_feed_link()
  • wp-includes/link-template.php:
    get_post_type_archive_feed_link()
  • wp-includes/link-template.php:
    get_delete_post_link()
  • wp-includes/link-template.php:
    get_edit_term_link()
  • wp-includes/link-template.php:
    get_search_feed_link()
  • wp-includes/link-template.php:
    get_post_comments_feed_link()
  • wp-includes/link-template.php:
    get_post_permalink()
  • wp-includes/class-oembed.php:
    WP_oEmbed::fetch()
  • wp-includes/class-oembed.php:
    WP_oEmbed::_fetch_with_format()
  • wp-includes/post-template.php:
    _wp_link_page()
  • wp-includes/media.php:
    wp_enqueue_media()
  • wp-includes/media.php:
    wp_video_shortcode()
  • wp-includes/media.php:
    wp_audio_shortcode()
  • wp-includes/class-wp-rewrite.php:
    WP_Rewrite::add_rule()
  • wp-includes/canonical.php:
    redirect_canonical()
  • wp-includes/post-formats.php:
    _post_format_link()
  • wp-includes/class.wp-scripts.php:
    WP_Scripts::do_item()
  • wp-includes/comment-template.php:
    get_comment_reply_link()
  • wp-includes/comment-template.php:
    get_comment_link()
  • wp-includes/script-loader.php:
    wp_style_loader_src()
  • wp-includes/media-template.php:
    wp_print_media_templates()
  • Show 111 more used by
    Hide more used by


User Contributed Notes

  1. Skip to note content

    You must log in to vote on the helpfulness of this noteVote results for this note: 17You must log in to vote on the helpfulness of this note

    Contributed by Codex

    Assuming we’re at the WordPress URL “http://blog.example.com/client/?s=word”… Note the use of esc_url() before outputting the link. This is necessary because this function does not escape URLs and if output without escaping, would make the page vulnerable to XSS scripting.

    
    // This would output '/client/?s=word&foo=bar'
    echo esc_url( add_query_arg( 'foo', 'bar' ) );
    
    // This would output '/client/?s=word&foo=bar&baz=tiny'
    $arr_params = array( 'foo' => 'bar', 'baz' => 'tiny' );
    echo esc_url( add_query_arg( $arr_params ) );
    
  2. Since get_permalink() returns a full URL, you could use that when you want to add variables to a post’s page.

    
    /*
     * This would output whatever the URL to post ID 9 is, with 'hello=there'
     * appended with either ? or &, depending on what's needed.
     */
    echo esc_url( add_query_arg( 'hello', 'there', get_permalink( 9 ) ) );
    

    More often than not you’ll probably find yourself creating URLs using the following method within the page you’re currently on. In these cases you can use the URL you want to affect as the last parameter. The use of esc_url() is not required here, because the value is known to be safe.

    
    // This would output 'http://blog.example.com/2009/04/16/?hello=world'
    echo esc_url( add_query_arg( 'hello', 'world', 'http://blog.example.com/2009/04/16/' ) );
    

    Removing values and setting via an associative array:

    
    $query = 'http://example.com/link?foo=bar';
    $new_query = add_query_arg( array(
    	'foo' => false,
    	'baz' => 'qux'
    ), $query );
    print( $new_query );
    // http://example.com/link?baz=qux
    

    To safely redirect user to a custom page inside plugins.php

    
    // Redirect to Welcome Page.
    // Redirects to your-domain.com/wp-admin/plugin.php?page=your_plugin_page.
    wp_safe_redirect( add_query_arg( array( 'page' => 'your_plugin_page' ), admin_url( 'plugins.php' ) ) );
    

    A way to get the current total url using add_query_arg

    home_url( add_query_arg( null, null ));

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!