云策 WordPress 开发者社区

函数文档

wp_iframe()

查看官方原文 ↗
💡 云策文档标注

概述

wp_iframe() 函数用于输出一个 iframe，以显示媒体上传页面，主要用于旧版（3.5.0 之前）的媒体上传弹出窗口。它接受一个回调函数来生成内容，并支持可选参数。

关键要点

  • 函数签名：wp_iframe( $content_func, ...$args )，其中 $content_func 是必需的回调函数，$args 是可选的额外参数。
  • 主要用于媒体上传处理，如 wp_media_upload_handler()、media_upload_gallery() 和 media_upload_library() 等函数调用。
  • 涉及多个 Hook，如 admin_enqueue_scripts、admin_head 和特定于媒体上传的 Hook，用于脚本和样式的管理。
  • 从 WordPress 2.5.0 版本引入，5.3.0 版本正式化了 ...$args 参数。

代码示例

// 添加新标签到媒体上传 iframe
add_filter( 'media_upload_tabs', 'wpdocs_my_upload_tab' );
function wpdocs_my_upload_tab( $tabs ) {
	$tabs['mytabname'] = __( 'My Tab Name', 'textdomain' );
	return $tabs;
}

// 使用 wp_iframe 调用新标签
add_action( 'media_upload_mytabname', 'wpdocs_add_my_new_form' );
function wpdocs_add_my_new_form() {
	wp_iframe( 'wpdocs_my_new_form' );
}

// 标签内容
function wpdocs_my_new_form() {
	echo '' . __( 'Example HTML content goes here.', 'textdomain' ) . '';
}
📄 原文内容

Outputs the iframe to display the media upload page.

Parameters

$content_funccallablerequired
Function that outputs the content.
$argsmixedoptional
Optional additional parameters to pass to the callback function when it’s called.

Source

function wp_iframe( $content_func, ...$args ) {
	global $body_id;

	_wp_admin_html_begin();
	?>
	<title> ›  — </title>
	
	<script type="text/javascript">
	addLoadEvent = function(func){if(typeof jQuery!=='undefined')jQuery(function(){func();});else if(typeof wpOnload!=='function'){wpOnload=func;}else{var oldonload=wpOnload;wpOnload=function(){oldonload();func();}}};
	var ajaxurl = '<?php echo esc_js( admin_url( 'admin-ajax.php', 'relative' ) ); ?>', pagenow = 'media-upload-popup', adminpage = 'media-upload-popup',
	isRtl = <?php echo (int) is_rtl(); ?>;
	</script>
	
	</head>
	<body<?php echo $body_id_attr; ?> class="wp-core-ui no-js">
	<script type="text/javascript">
	document.body.className = document.body.className.replace('no-js', 'js');
	</script>
	
	<script type="text/javascript">if(typeof wpOnload==='function')wpOnload();</script>
	</body>
	</html>
	</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-admin/includes/media.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/media.php#L535">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/media.php#L535-L630">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/admin_enqueue_scripts/"><span class="hook-func">do_action</span>( ‘admin_enqueue_scripts’,  <nobr><span class="arg-type">string</span> <span class="arg-name">$hook_suffix</span></nobr> )</a></dt><dd><p>Fires when enqueuing scripts for all admin pages.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_head/"><span class="hook-func">do_action</span>( ‘admin_head’ )</a></dt><dd><p>Fires in head section for all admin pages.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_head-media-upload-popup/"><span class="hook-func">do_action</span>( ‘admin_head-media-upload-popup’ )</a></dt><dd><p>Fires when scripts enqueued for the admin header for the legacy (pre-3.5.0) media upload popup are printed.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_head_content_func/"><span class="hook-func">do_action</span>( “admin_head_{$content_func}” )</a></dt><dd><p>Fires in the admin header for each specific form tab in the legacy (pre-3.5.0) media upload popup.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_print_footer_scripts/"><span class="hook-func">do_action</span>( ‘admin_print_footer_scripts’ )</a></dt><dd><p>Prints any scripts and data queued for the footer.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_print_scripts/"><span class="hook-func">do_action</span>( ‘admin_print_scripts’ )</a></dt><dd><p>Fires when scripts are printed for all admin pages.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_print_scripts-media-upload-popup/"><span class="hook-func">do_action</span>( ‘admin_print_scripts-media-upload-popup’ )</a></dt><dd><p>Fires when admin scripts enqueued for the legacy (pre-3.5.0) media upload popup are printed.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_print_styles/"><span class="hook-func">do_action</span>( ‘admin_print_styles’ )</a></dt><dd><p>Fires when styles are printed for all admin pages.</p>
</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/admin_print_styles-media-upload-popup/"><span class="hook-func">do_action</span>( ‘admin_print_styles-media-upload-popup’ )</a></dt><dd><p>Fires when admin styles enqueued for the legacy (pre-3.5.0) media upload popup are printed.</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_admin_html_begin/">_wp_admin_html_begin()</a><code>wp-admin/includes/template.php</code></td><td><p>Prints out the beginning of the admin HTML header.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/esc_js/">esc_js()</a><code>wp-includes/formatting.php</code></td><td><p>Escapes single quotes, <code>"</code>, <code></code>, <code>&</code>, and fixes line endings.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/bloginfo/">bloginfo()</a><code>wp-includes/general-template.php</code></td><td><p>Displays information about the current site.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/is_rtl/">is_rtl()</a><code>wp-includes/l10n.php</code></td><td><p>Determines whether the current locale is right-to-left (RTL).</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/wp_enqueue_style/">wp_enqueue_style()</a><code>wp-includes/functions.wp-styles.php</code></td><td><p>Enqueues a CSS stylesheet.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/_e/">_e()</a><code>wp-includes/l10n.php</code></td><td><p>Displays translated text.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/admin_url/">admin_url()</a><code>wp-includes/link-template.php</code></td><td><p>Retrieves the URL to the admin area for the current site.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/do_action/">do_action()</a><code>wp-includes/plugin.php</code></td><td><p>Calls the callback functions that have been added to an action hook.</p>
</td></tr></tbody></table></figure><a class="wp-block-wporg-code-table-show-more" href="#">Show 3 more</a><a class="wp-block-wporg-code-table-show-less" href="#">Show less</a></section>  <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="used-by"><figure class="wp-block-table "><table><thead><tr><th scope="col">Used by</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/wp_media_upload_handler/">wp_media_upload_handler()</a><code>wp-admin/includes/media.php</code></td><td><p>Handles the process of uploading media.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/media_upload_gallery/">media_upload_gallery()</a><code>wp-admin/includes/media.php</code></td><td><p>Retrieves the legacy media uploader form in an iframe.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/media_upload_library/">media_upload_library()</a><code>wp-admin/includes/media.php</code></td><td><p>Retrieves the legacy media library form in an iframe.</p>
</td></tr></tbody></table></figure></section> </section>
		<section class="wp-block-wporg-code-reference-changelog"><h2 id="changelog" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#changelog">Changelog</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table"><figure class="wp-block-table "><table><thead><tr><th scope="col">Version</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/since/5.3.0/">5.3.0</a></td><td><span class="since-description">Formalized the existing and already documented <code>...$args</code> parameter              by adding it to the function signature.</span></td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/since/2.5.0/">2.5.0</a></td><td>Introduced.</td></tr></tbody></table></figure></section> </section>
		<section class="wp-block-wporg-code-reference-comments" data-nosnippet="true"><h2 id="user-contributed-notes" class="is-toc-heading wp-block-heading" tabindex="-1" ><a href="#user-contributed-notes">User Contributed Notes</a></h2> <ol class="comment-list">			<li id="comment-1505" data-comment-id="1505" class="comment byuser comment-author-codex odd alt thread-odd thread-alt depth-1 bad-note">
			<article id="div-comment-1505" class="comment-body">

							<a href="#comment-content-1505" class="screen-reader-text">Skip to note 2 content</a>
				<header class="comment-meta">
					<div class="comment-author vcard">
						<span class="comment-author-attribution">
						<a href="https://profiles.wordpress.org/codex/" rel="external nofollow" class="url">Codex</a>						</span>
						<a class="comment-date" href="https://developer.wordpress.org/reference/functions/wp_iframe/#comment-1505">
							<time datetime="2016-03-26T04:56:27+00:00">
							10 years ago							</time>
						</a>

																													</div>
					<div class="user-note-voting" data-nonce="b6f85eed54" data-can-vote="false"><a class="user-note-voting-up" title="You must log in to vote on the helpfulness of this note" data-id="1505" data-vote="up" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_iframe%2F%23comment-1505"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a><span class="user-note-voting-count " title="0% like this"><span class="screen-reader-text">Vote results for this note: </span>-2</span><a class="user-note-voting-down" title="You must log in to vote on the helpfulness of this note" data-id="1505" data-vote="down" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_iframe%2F%23comment-1505"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a></div>				</header>
				<!-- .comment-metadata -->
			
				<div class="wporg-has-embedded-code comment-content" id="comment-content-1505">
				<p><strong>Demonstrate how to add new tab in the media upload iframe</strong></p>
<pre class="wp-block-code"><code lang="php" class="language-php line-numbers">// Add the tab.
add_filter( 'media_upload_tabs', 'wpdocs_my_upload_tab' );
function wpdocs_my_upload_tab( $tabs ) {
	$tabs['mytabname'] = __( 'My Tab Name', 'textdomain' );
	return $tabs;
}

// Call the new tab with wp_iframe.
add_action( 'media_upload_mytabname', 'wpdocs_add_my_new_form' );
function wpdocs_add_my_new_form() {
	wp_iframe( 'wpdocs_my_new_form' );
}

// The tab content.
function wpdocs_my_new_form() {
	echo '<p>' . __( 'Example HTML content goes here.', 'textdomain' ) . '</p>';
}