media_upload_form()

💡 云策文档标注

概述

media_upload_form() 函数用于输出 WordPress 的旧版媒体上传表单，主要用于处理文件上传的界面和逻辑。它检查设备上传能力，设置上传参数，并集成 Plupload 库以实现多文件上传功能。

关键要点

函数输出旧版媒体上传表单，适用于需要自定义上传界面的场景。
参数 $errors 可选，用于传递错误信息数组，默认值为 null。
函数首先检查设备是否支持上传，若不支持则显示提示信息并返回。
设置上传 URL、post_id、类型和标签等参数，并计算最大上传大小。
使用 Plupload 初始化配置，包括按钮、容器、文件大小限制和 POST 参数。
针对移动设备（如 iOS 7.x）有特殊处理，禁用多文件选择以避免视频上传问题。
通过过滤器 wp_prevent_unsupported_mime_type_uploads 检查是否支持 WebP 和 AVIF 格式的编辑。
提供多个 Hook，如 upload_post_params 和 plupload_init，允许开发者自定义上传参数和 Plupload 设置。
函数包含相关操作和过滤器，如 pre-upload-ui 和 post-upload-ui，用于在界面加载前后执行自定义代码。

代码示例

// 基本用法：输出媒体上传表单
media_upload_form();

// 传递错误信息
$errors = array( 'upload_error' => '文件上传失败' );
media_upload_form( $errors );

注意事项

此函数输出的是旧版上传表单，自 WordPress 3.5.0 起推荐使用新的媒体管理器，但在特定插件或主题中可能仍需使用。
上传表单依赖于全局变量 $type 和 $tab，需确保在调用前已正确设置。
在移动设备上，特别是 iOS 7.x，多文件上传可能被禁用，需注意兼容性问题。
通过过滤器可以自定义上传行为，例如调整 Plupload 设置或添加额外的验证逻辑。

📄 原文内容

Outputs the legacy media upload form.

Parameters

$errorsarrayoptional: Default:null

Source

function media_upload_form( $errors = null ) {

	global $type, $tab;
	if ( ! _device_can_upload() ) {

		echo '<p>' . sprintf(

			/* translators: %s: https://apps.wordpress.org/ */

			__( 'The web browser on your device cannot be used to upload files. You may be able to use the <a href="%s">native app for your device</a> instead.' ),

			'https://apps.wordpress.org/'

		) . '</p>';

		return;

	}
	$upload_action_url = admin_url( 'async-upload.php' );

	$post_id           = isset( $_REQUEST['post_id'] ) ? (int) $_REQUEST['post_id'] : 0;

	$_type             = isset( $type ) ? $type : '';

	$_tab              = isset( $tab ) ? $tab : '';
	$max_upload_size = wp_max_upload_size();

	if ( ! $max_upload_size ) {

		$max_upload_size = 0;

	}
	?>

	<div id="media-upload-notice">
	</div>

	<div id="media-upload-error">

	get_error_message();

	}
	?>

	</div>

	 $post_id,

		'_wpnonce' => wp_create_nonce( 'media-form' ),

		'type'     => $_type,

		'tab'      => $_tab,

		'short'    => '1',

	);
	/**

	 * Filters the media upload post parameters.

	 *

	 * @since 3.1.0 As 'swfupload_post_params'

	 * @since 3.3.0

	 *

	 * @param array $post_params An array of media upload parameters used by Plupload.

	 */

	$post_params = apply_filters( 'upload_post_params', $post_params );
	/*

	* Since 4.9 the `runtimes` setting is hardcoded in our version of Plupload to `html5,html4`,

	* and the `flash_swf_url` and `silverlight_xap_url` are not used.

	*/

	$plupload_init = array(

		'browse_button'    => 'plupload-browse-button',

		'container'        => 'plupload-upload-ui',

		'drop_element'     => 'drag-drop-area',

		'file_data_name'   => 'async-upload',

		'url'              => $upload_action_url,

		'filters'          => array( 'max_file_size' => $max_upload_size . 'b' ),

		'multipart_params' => $post_params,

	);
	/*

	 * Currently only iOS Safari supports multiple files uploading,

	 * but iOS 7.x has a bug that prevents uploading of videos when enabled.

	 * See #29602.

	 */

	if (

		wp_is_mobile() &&

		str_contains( $_SERVER['HTTP_USER_AGENT'], 'OS 7_' ) &&

		str_contains( $_SERVER['HTTP_USER_AGENT'], 'like Mac OS X' )

	) {

		$plupload_init['multi_selection'] = false;

	}
	/** This filter is documented in wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php */

	$prevent_unsupported_uploads = apply_filters( 'wp_prevent_unsupported_mime_type_uploads', true, null );
	if ( $prevent_unsupported_uploads ) {

		// Check if WebP images can be edited.

		if ( ! wp_image_editor_supports( array( 'mime_type' => 'image/webp' ) ) ) {

			$plupload_init['webp_upload_error'] = true;

		}
		// Check if AVIF images can be edited.

		if ( ! wp_image_editor_supports( array( 'mime_type' => 'image/avif' ) ) ) {

			$plupload_init['avif_upload_error'] = true;

		}

	}
	/**

	 * Filters the default Plupload settings.

	 *

	 * @since 3.3.0

	 *

	 * @param array $plupload_init An array of default settings used by Plupload.

	 */

	$plupload_init = apply_filters( 'plupload_init', $plupload_init );
	?>

	<script type="text/javascript">

	<?php

	// Verify size is an int. If not return default value.

	$large_size_h = absint( get_option( 'large_size_h' ) );
	if ( ! $large_size_h ) {

		$large_size_h = 1024;

	}
	$large_size_w = absint( get_option( 'large_size_w' ) );
	if ( ! $large_size_w ) {

		$large_size_w = 1024;

	}
	?>

	var resize_height = <?php echo $large_size_h; ?>, resize_width = <?php echo $large_size_w; ?>,

	wpUploaderInit = <?php echo wp_json_encode( $plupload_init, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ); ?>;

	</script>
	<div id="plupload-upload-ui" class="hide-if-no-js">
	<div id="drag-drop-area">

		<div class="drag-drop-inside">

		<p class="drag-drop-info"></p>

		<p></p>

		<p class="drag-drop-buttons"><input id="plupload-browse-button" type="button" value="<?php esc_attr_e( 'Select Files' ); ?>" class="button" /></p>

		</div>

	</div>
	</div>
	<div id="html-upload-ui" class="hide-if-js">
	<p id="async-upload-wrap">

		<label class="screen-reader-text" for="async-upload">
		</label>

		<input type="file" name="async-upload" id="async-upload" />
		<a href="#" onclick="try{top.tb_remove();}catch(e){}; return false;"></a>

	</p>

	<div class="clear"></div>
	</div>
<p class="max-upload-size">
</p>

	</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#L2092">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/media.php#L2092-L2320">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/plupload_init/"><span class="hook-func">apply_filters</span>( ‘plupload_init’,  <nobr><span class="arg-type">array</span> <span class="arg-name">$plupload_init</span></nobr> )</a></dt><dd><p>Filters the default Plupload settings.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/post-html-upload-ui/"><span class="hook-func">do_action</span>( ‘post-html-upload-ui’ )</a></dt><dd><p>Fires after the upload button in the media upload interface.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/post-plupload-upload-ui/"><span class="hook-func">do_action</span>( ‘post-plupload-upload-ui’ )</a></dt><dd><p>Fires after the upload interface loads.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/post-upload-ui/"><span class="hook-func">do_action</span>( ‘post-upload-ui’ )</a></dt><dd><p>Fires on the post upload UI screen.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/pre-html-upload-ui/"><span class="hook-func">do_action</span>( ‘pre-html-upload-ui’ )</a></dt><dd><p>Fires before the upload button in the media upload interface.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/pre-plupload-upload-ui/"><span class="hook-func">do_action</span>( ‘pre-plupload-upload-ui’ )</a></dt><dd><p>Fires before the upload interface loads.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/pre-upload-ui/"><span class="hook-func">do_action</span>( ‘pre-upload-ui’ )</a></dt><dd><p>Fires just before the legacy (pre-3.5.0) upload interface is loaded.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/upload_post_params/"><span class="hook-func">apply_filters</span>( ‘upload_post_params’,  <nobr><span class="arg-type">array</span> <span class="arg-name">$post_params</span></nobr> )</a></dt><dd><p>Filters the media upload post parameters.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/upload_ui_over_quota/"><span class="hook-func">do_action</span>( ‘upload_ui_over_quota’ )</a></dt><dd><p>Fires when an upload will exceed the defined upload space quota for a network site.</p>

</dd><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/wp_prevent_unsupported_mime_type_uploads/"><span class="hook-func">apply_filters</span>( ‘wp_prevent_unsupported_mime_type_uploads’,  <nobr><span class="arg-type">bool</span> <span class="arg-name">$check_mime</span></nobr>,  <nobr><span class="arg-type">string|null</span> <span class="arg-name">$mime_type</span></nobr> )</a></dt><dd><p>Filter whether the server should prevent uploads for image types it doesn’t support. Default true.</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/submit_button/">submit_button()</a><code>wp-admin/includes/template.php

Echoes a submit button, with provided text and appropriate class(es).



_ex()wp-includes/l10n.php

Displays translated string with gettext context.



esc_attr_e()wp-includes/l10n.php

Displays translated text that has been escaped for safe use in an attribute.



wp_is_mobile()wp-includes/vars.php

Test if the current browser runs on a mobile device (smart phone, tablet, etc.).



_device_can_upload()wp-includes/functions.php

Tests if the current device has the capability to upload files.



size_format()wp-includes/functions.php

Converts a number of bytes to the largest unit the bytes will fit into.



wp_max_upload_size()wp-includes/media.php

Determines the maximum upload size allowed in php.ini.



wp_image_editor_supports()wp-includes/media.php

Tests whether there is an editor that supports a given mime type or methods.



is_upload_space_available()wp-includes/ms-functions.php

Determines if there is any upload space left in the current blog’s quota.



wp_json_encode()wp-includes/functions.php

Encodes a variable into JSON, with some confidence checks.



__()wp-includes/l10n.php

Retrieves the translation of $text.



_e()wp-includes/l10n.php

Displays translated text.



_x()wp-includes/l10n.php

Retrieves translated string with gettext context.



esc_html()wp-includes/formatting.php

Escaping for HTML blocks.



wp_create_nonce()wp-includes/pluggable.php

Creates a cryptographic token tied to a specific action, user, user session, and window of time.



is_multisite()wp-includes/load.php

Determines whether Multisite is enabled.



absint()wp-includes/load.php

Converts a value to non-negative integer.



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

Retrieves the URL to the admin area for the current site.



do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.



apply_filters()wp-includes/plugin.php

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



get_option()wp-includes/option.php

Retrieves an option value based on an option name.



is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.





Show 17 moreShow less

Used by	Description
media_upload_type_form()`wp-admin/includes/media.php`	Outputs the legacy media upload form for a given media type.

Changelog

Version	Description
2.5.0	Introduced.

云策 WordPress 开发者社区

函数文档

media_upload_form()

概述

关键要点

代码示例

注意事项

Parameters

Source

Changelog