云策 WordPress 开发者社区

函数文档

media_upload_gallery_form()

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

概述

media_upload_gallery_form() 是一个 WordPress 函数，用于在媒体上传 iframe 中添加图库表单。它处理表单的生成和提交，包括参数验证和钩子应用。

关键要点

  • 函数接受一个必需参数 $errors（数组），用于处理错误信息。
  • 设置全局变量 $redir_tab 为 'gallery'，并调用 media_upload_header() 输出上传头部。
  • 构建表单动作 URL，通过 apply_filters('media_upload_form_url', $form_action_url, $type) 允许过滤。
  • 根据用户设置动态添加 CSS 类，例如 'html-uploader'。
  • 输出包含多个字段的 HTML 表单，包括隐藏字段、非ce字段和提交按钮。
  • 使用相关函数如 submit_button()、get_media_items() 和 wp_nonce_field() 增强功能。
  • 定义于 WordPress 核心，自版本 2.5.0 引入。

代码示例

function media_upload_gallery_form( $errors ) {
    global $redir_tab, $type;

    $redir_tab = 'gallery';
    media_upload_header();

    $post_id         = (int) $_REQUEST['post_id'];
    $form_action_url = admin_url( "media-upload.php?type=$type&tab;=gallery&post;_id=$post_id" );
    /** This filter is documented in wp-admin/includes/media.php */
    $form_action_url = apply_filters( 'media_upload_form_url', $form_action_url, $type );
    $form_class      = 'media-upload-form validate';

    if ( get_user_setting( 'uploader' ) ) {
        $form_class .= ' html-uploader';
    }

    // HTML 表单输出代码省略...
}

注意事项

  • 确保在调用此函数前已正确处理 $errors 参数，以避免表单错误显示问题。
  • 表单 URL 可通过 'media_upload_form_url' 过滤器自定义，便于开发者调整上传流程。
  • 函数依赖于全局变量和请求参数，如 $_REQUEST['post_id']，需确保环境设置正确。
📄 原文内容

Adds gallery form to upload iframe.

Parameters

$errorsarrayrequired

Source

function media_upload_gallery_form( $errors ) {

	global $redir_tab, $type;


	$redir_tab = 'gallery';

	media_upload_header();


	$post_id         = (int) $_REQUEST['post_id'];

	$form_action_url = admin_url( "media-upload.php?type=$type&tab;=gallery&post;_id=$post_id" );

	/** This filter is documented in wp-admin/includes/media.php */

	$form_action_url = apply_filters( 'media_upload_form_url', $form_action_url, $type );

	$form_class      = 'media-upload-form validate';


	if ( get_user_setting( 'uploader' ) ) {

		$form_class .= ' html-uploader';

	}


	?>

	<script type="text/javascript">

	jQuery(function($){

		var preloaded = $(".media-item.preloaded");

		if ( preloaded.length > 0 ) {

			preloaded.each(function(){prepareMediaItem({id:this.id.replace(/[^0-9]/g, '')},'');});

			updateMediaForm();

		}

	});

	</script>

	<div id="sort-buttons" class="hide-if-no-js">

	<span>


	<a href="#" id="showall"></a>

	<a href="#" id="hideall" style="display:none;"></a>

	</span>


	<a href="#" id="asc"></a> |

	<a href="#" id="desc"></a> |

	<a href="#" id="clear"></a>

	</div>

	<form enctype="multipart/form-data" method="post" action="<?php echo esc_url( $form_action_url ); ?>" class="<?php echo $form_class; ?>" id="gallery-form">


	<table class="widefat">

	<thead><tr>

	<th></th>

	<th class="order-head"></th>

	<th class="actions-head"></th>

	</tr></thead>

	</table>

	<div id="media-items">


	</div>


	<p class="ml-submit">

		 'save-all',

				'style' => 'display: none;',

			)

		);

		?>

	<input type="hidden" name="post_id" id="post_id" value="<?php echo (int) $post_id; ?>" />

	<input type="hidden" name="type" value="<?php echo esc_attr( $GLOBALS['type'] ); ?>" />

	<input type="hidden" name="tab" value="<?php echo esc_attr( $GLOBALS['tab'] ); ?>" />

	</p>


	<div id="gallery-settings" style="display:none;">

	<div class="title"></div>

	<table id="basic" class="describe"><tbody>

		<tr>

		<th scope="row" class="label">

			<label>

			<span class="alignleft"></span>

			</label>

		</th>

		<td class="field">

			<input type="radio" name="linkto" id="linkto-file" value="file" />

			<label for="linkto-file" class="radio"></label>


			<input type="radio" checked="checked" name="linkto" id="linkto-post" value="post" />

			<label for="linkto-post" class="radio"></label>

		</td>

		</tr>


		<tr>

		<th scope="row" class="label">

			<label>

			<span class="alignleft"></span>

			</label>

		</th>

		<td class="field">

			<select id="orderby" name="orderby">

				<option value="menu_order" selected="selected"></option>

				<option value="title"></option>

				<option value="post_date"></option>

				<option value="rand"></option>

			</select>

		</td>

		</tr>


		<tr>

		<th scope="row" class="label">

			<label>

			<span class="alignleft"></span>

			</label>

		</th>

		<td class="field">

			<input type="radio" checked="checked" name="order" id="order-asc" value="asc" />

			<label for="order-asc" class="radio"></label>


			<input type="radio" name="order" id="order-desc" value="desc" />

			<label for="order-desc" class="radio"></label>

		</td>

		</tr>


		<tr>

		<th scope="row" class="label">

			<label>

			<span class="alignleft"></span>

			</label>

		</th>

		<td class="field">

			<select id="columns" name="columns">

				<option value="1">1</option>

				<option value="2">2</option>

				<option value="3" selected="selected">3</option>

				<option value="4">4</option>

				<option value="5">5</option>

				<option value="6">6</option>

				<option value="7">7</option>

				<option value="8">8</option>

				<option value="9">9</option>

			</select>

		</td>

		</tr>

	</tbody></table>


	<p class="ml-submit">

	<input type="button" class="button" style="display:none;" onMouseDown="wpgallery.update();" name="insert-gallery" id="insert-gallery" value="<?php esc_attr_e( 'Insert gallery' ); ?>" />

	<input type="button" class="button" style="display:none;" onMouseDown="wpgallery.update();" name="update-gallery" id="update-gallery" value="<?php esc_attr_e( 'Update gallery settings' ); ?>" />

	</p>

	</div>

	</form>

	</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#L2554">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/media.php#L2554-L2701">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/media_upload_form_url/"><span class="hook-func">apply_filters</span>( ‘media_upload_form_url’,  <nobr><span class="arg-type">string</span> <span class="arg-name">$form_action_url</span></nobr>,  <nobr><span class="arg-type">string</span> <span class="arg-name">$type</span></nobr> )</a></dt><dd><p>Filters the media upload form action URL.</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).




media_upload_header()wp-admin/includes/media.php


Outputs the legacy media upload header.




get_media_items()wp-admin/includes/media.php


Retrieves HTML for media items of post gallery.




_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_nonce_field()wp-includes/functions.php


Retrieves or display nonce hidden field for forms.




get_user_setting()wp-includes/option.php


Retrieves user interface setting value based on setting name.




_e()wp-includes/l10n.php


Displays translated text.




__()wp-includes/l10n.php


Retrieves the translation of $text.




esc_url()wp-includes/formatting.php


Checks and cleans a URL.




esc_attr()wp-includes/formatting.php


Escaping for HTML attributes.




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


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




apply_filters()wp-includes/plugin.php


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




add_filter()wp-includes/plugin.php


Adds a callback function to a filter hook.







Show 9 moreShow less

Changelog

Version Description
2.5.0 Introduced.