wp_admin_canonical_url()

💡 云策文档标注

概述

wp_admin_canonical_url() 函数用于移除 WordPress 管理界面 URL 中的一次性查询参数，并生成规范链接。它通过过滤和清理 URL，确保管理页面的 URL 规范化和一致性。

关键要点

移除一次性查询参数：使用 wp_removable_query_args() 获取可移除的参数列表，并通过 remove_query_arg() 从当前 URL 中移除这些参数。
生成规范链接：处理后的 URL 作为规范链接输出到管理头部，并可通过 wp_admin_canonical_url 过滤器进行自定义。
依赖核心函数：涉及 set_url_scheme() 确保 URL 使用绝对路径，以及 esc_url() 进行 URL 清理。

代码示例

function wp_admin_canonical_url() {
	$removable_query_args = wp_removable_query_args();

	if ( empty( $removable_query_args ) ) {
		return;
	}

	// Ensure we're using an absolute URL.
	$current_url  = set_url_scheme( 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );
	$filtered_url = remove_query_arg( $removable_query_args, $current_url );

	/**
	 * Filters the admin canonical URL value.
	 *
	 * @since 6.5.0
	 *
	 * @param string $filtered_url The admin canonical URL value.
	 */
	$filtered_url = apply_filters( 'wp_admin_canonical_url', $filtered_url );
	?>
	" />
}

注意事项

该函数自 WordPress 4.2.0 版本引入，主要用于管理后台，确保 URL 的规范性和安全性。
使用 wp_admin_canonical_url 过滤器可以修改生成的规范链接，适用于自定义管理界面需求。
相关函数包括 wp_removable_query_args()、remove_query_arg()、set_url_scheme()、esc_url() 和 apply_filters()，开发者应熟悉这些函数以正确使用。

📄 原文内容

Removes single-use URL parameters and create canonical link based on new URL.

Description

Removes specific query string parameters from a URL, create the canonical link, put it in the admin header, and change the current URL to match.

Source

function wp_admin_canonical_url() {

	$removable_query_args = wp_removable_query_args();
	if ( empty( $removable_query_args ) ) {

		return;

	}
	// Ensure we're using an absolute URL.

	$current_url  = set_url_scheme( 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );

	$filtered_url = remove_query_arg( $removable_query_args, $current_url );
	/**

	 * Filters the admin canonical URL value.

	 *

	 * @since 6.5.0

	 *

	 * @param string $filtered_url The admin canonical URL value.

	 */

	$filtered_url = apply_filters( 'wp_admin_canonical_url', $filtered_url );

	?>

	<link id="wp-admin-canonical" rel="canonical" href="<?php echo esc_url( $filtered_url ); ?>" />

	<script>

		if ( window.history.replaceState ) {

			window.history.replaceState( null, null, document.getElementById( 'wp-admin-canonical' ).href + window.location.hash );

		}

	</script>

	</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-admin/includes/misc.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/misc.php#L1386">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/misc.php#L1386-L1413">View on GitHub</a></p></section>

		<section class="wp-block-wporg-code-reference-hooks"><h2 id="hooks" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#hooks">Hooks</a></h2> <dl><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/wp_admin_canonical_url/"><span class="hook-func">apply_filters</span>( ‘wp_admin_canonical_url’,  <nobr><span class="arg-type">string</span> <span class="arg-name">$filtered_url</span></nobr> )</a></dt><dd><p>Filters the admin canonical URL value.</p>

</dd></dl></section>

		<section class="wp-block-wporg-code-reference-related" data-nosnippet="true"><h2 id="related" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#related">Related</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="uses"><figure class="wp-block-table "><table><thead><tr><th scope="col">Uses</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/wp_removable_query_args/">wp_removable_query_args()</a><code>wp-includes/functions.php

Returns an array of single-use query variable names that can be removed from a URL.



remove_query_arg()wp-includes/functions.php

Removes an item or items from a query string.



set_url_scheme()wp-includes/link-template.php

Sets the scheme for a URL.



esc_url()wp-includes/formatting.php

Checks and cleans a URL.



apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.





Show 2 moreShow less

Changelog

Version	Description
4.2.0	Introduced.

云策 WordPress 开发者社区

函数文档