media_upload_library_form()

💡 云策文档标注

概述

media_upload_library_form() 函数用于输出 WordPress 媒体库的传统上传表单，主要用于处理媒体文件的管理和筛选。该函数包含参数处理、表单构建、分页和类型过滤等功能，适用于开发者自定义媒体上传界面。

关键要点

函数接受一个 $errors 参数数组，用于处理上传错误。
生成媒体库表单，包括表单动作 URL、类名设置，并应用 media_upload_form_url 过滤器。
实现媒体类型筛选，通过 post_mime_types 和 wp_edit_attachments_query() 动态生成类型链接列表。
支持分页功能，使用 paginate_links() 显示媒体项的分页导航。
包含日期筛选器，从数据库中检索附件月份数据，供用户按时间筛选媒体。
表单包含搜索框、非ce字段和提交按钮，确保安全性和用户交互。
使用多个 WordPress 核心函数和 Hook，如 apply_filters、wp_nonce_field 和 selected() 等。

代码示例

// 示例调用 media_upload_library_form() 函数
media_upload_library_form( $errors );

注意事项

此函数输出的是传统媒体上传表单，可能与现代 WordPress 界面不兼容，建议在需要向后兼容时使用。
函数内部依赖全局变量如 $wpdb 和 $wp_query，调用时需确保这些变量已正确初始化。
表单 URL 可通过 media_upload_form_url 过滤器自定义，方便开发者调整行为。
媒体类型链接列表可通过 media_upload_mime_type_links 过滤器进行修改，以添加或移除特定类型。
分页逻辑基于每页 10 个媒体项，开发者可通过修改 $q['posts_per_page'] 调整数量。

📄 原文内容

Outputs the legacy media upload form for the media library.

Parameters

$errorsarrayrequired

Source

function media_upload_library_form( $errors ) {

	global $wpdb, $wp_query, $wp_locale, $type, $tab, $post_mime_types;
	media_upload_header();
	$post_id = isset( $_REQUEST['post_id'] ) ? (int) $_REQUEST['post_id'] : 0;
	$form_action_url = admin_url( "media-upload.php?type=$type&tab;=library&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';

	}
	$q                   = $_GET;

	$q['posts_per_page'] = 10;

	$q['paged']          = isset( $q['paged'] ) ? (int) $q['paged'] : 0;

	if ( $q['paged'] < 1 ) {

		$q['paged'] = 1;

	}

	$q['offset'] = ( $q['paged'] - 1 ) * 10;

	if ( $q['offset'] < 1 ) {

		$q['offset'] = 0;

	}
	list($post_mime_types, $avail_post_mime_types) = wp_edit_attachments_query( $q );
	?>

	<form id="filter" method="get">

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

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

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

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

	<input type="hidden" name="context" value="<?php echo isset( $_GET['context'] ) ? esc_attr( $_GET['context'] ) : ''; ?>" />
	<p id="media-search" class="search-box">

		<label class="screen-reader-text" for="media-search-input">
		</label>

		<input type="search" id="media-search-input" name="s" value="<?php the_search_query(); ?>" />
	</p>
	<ul class="subsubsub">

		 $reals ) {

			foreach ( $reals as $real ) {

				if ( isset( $num_posts[ $_type ] ) ) {

					$num_posts[ $_type ] += $_num_posts[ $real ];

				} else {

					$num_posts[ $_type ] = $_num_posts[ $real ];

				}

			}

		}

		// If available type specified by media button clicked, filter by that type.

		if ( empty( $_GET['post_mime_type'] ) && ! empty( $num_posts[ $type ] ) ) {

			$_GET['post_mime_type']                        = $type;

			list($post_mime_types, $avail_post_mime_types) = wp_edit_attachments_query();

		}

		if ( empty( $_GET['post_mime_type'] ) || 'all' === $_GET['post_mime_type'] ) {

			$class = ' class="current"';

		} else {

			$class = '';

		}

		$type_links[] = '<li><a href="' . esc_url(

			add_query_arg(

				array(

					'post_mime_type' => 'all',

					'paged'          => false,

					'm'              => false,

				)

			)

		) . '"' . $class . '>' . __( 'All Types' ) . '</a>';

		foreach ( $post_mime_types as $mime_type => $label ) {

			$class = '';
			if ( ! wp_match_mime_types( $mime_type, $avail_post_mime_types ) ) {

				continue;

			}
			if ( isset( $_GET['post_mime_type'] ) && wp_match_mime_types( $mime_type, $_GET['post_mime_type'] ) ) {

				$class = ' class="current"';

			}
			$type_links[] = '<li><a href="' . esc_url(

				add_query_arg(

					array(

						'post_mime_type' => $mime_type,

						'paged'          => false,

					)

				)

			) . '"' . $class . '>' . sprintf( translate_nooped_plural( $label[2], $num_posts[ $mime_type ] ), '<span id="' . $mime_type . '-counter">' . number_format_i18n( $num_posts[ $mime_type ] ) . '</span>' ) . '</a>';

		}

		/**

		 * Filters the media upload mime type list items.

		 *

		 * Returned values should begin with an `<li>` tag.

		 *

		 * @since 3.1.0

		 *

		 * @param string[] $type_links An array of list items containing mime type link HTML.

		 */

		echo implode( ' | </li>', apply_filters( 'media_upload_mime_type_links', $type_links ) ) . '</li>';

		unset( $type_links );

		?>

	</ul>
	<div class="tablenav">
		 add_query_arg( 'paged', '%#%' ),

				'format'    => '',

				'prev_text' => __( '«' ),

				'next_text' => __( '»' ),

				'total'     => (int) ceil( $wp_query->found_posts / 10 ),

				'current'   => $q['paged'],

			)

		);
		if ( $page_links ) {

			echo "<div class='tablenav-pages'>$page_links</div>";

		}

		?>
	<div class="alignleft actions">

		get_results(

			"SELECT DISTINCT YEAR( post_date ) AS year, MONTH( post_date ) AS month

			FROM $wpdb->posts

			WHERE post_type = 'attachment'

			ORDER BY post_date DESC"

		);
		$month_count    = count( $months );

		$selected_month = isset( $_GET['m'] ) ? (int) $_GET['m'] : 0;
		if ( $month_count && ( 1 !== $month_count || 0 !== (int) $months[0]->month ) ) {

			?>

			<select name='m'>

				<option<?php selected( $selected_month, 0 ); ?> value='0'></option>

			year ) {

					continue;

				}
				$month = zeroise( $arc_row->month, 2 );

				$year  = $arc_row->year;
				printf(

					"<option %s value='%s'>%s</option>n",

					selected( $selected_month, $year . $month, false ),

					esc_attr( $year . $month ),

					/* translators: 1: Month name, 2: 4-digit year. */

					esc_html( sprintf( __( '%1$s %2$d' ), $wp_locale->get_month( $month ), $year ) )

				);

			}

			?>

			</select>
	</div>
	<br class="clear" />

	</div>

	</form>
	<form enctype="multipart/form-data" method="post" action="<?php echo esc_url( $form_action_url ); ?>" class="<?php echo $form_class; ?>" id="library-form">
	<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="media-items">
	</div>

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

	</p>

	</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#L2717">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/media.php#L2717-L2919">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><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/media_upload_mime_type_links/"><span class="hook-func">apply_filters</span>( ‘media_upload_mime_type_links’,  <nobr><span class="arg-type">string[]</span> <span class="arg-name">$type_links</span></nobr> )</a></dt><dd><p>Filters the media upload mime type list items.</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.



wp_edit_attachments_query()wp-admin/includes/post.php

Executes a query for attachments. An array of WP_Query arguments can be passed in, which will override the arguments set by this function.



translate_nooped_plural()wp-includes/l10n.php

Translates and returns the singular or plural form of a string that’s been registered with _n_noop()  or _nx_noop() .



zeroise()wp-includes/formatting.php

Add leading zeros when necessary.



selected()wp-includes/general-template.php

Outputs the HTML selected attribute.



the_search_query()wp-includes/general-template.php

Displays the contents of the search query variable.



paginate_links()wp-includes/general-template.php

Retrieves paginated links for archive post pages.



wp_nonce_field()wp-includes/functions.php

Retrieves or display nonce hidden field for forms.



WP_Locale::get_month()wp-includes/class-wp-locale.php

Retrieves the full translated month by month number.



get_user_setting()wp-includes/option.php

Retrieves user interface setting value based on setting name.



wp_match_mime_types()wp-includes/post.php

Checks a MIME-Type against a list.



wp_count_attachments()wp-includes/post.php

Counts number of attachments for the mime type(s).



_e()wp-includes/l10n.php

Displays translated text.



__()wp-includes/l10n.php

Retrieves the translation of $text.



esc_attr()wp-includes/formatting.php

Escaping for HTML attributes.



esc_url()wp-includes/formatting.php

Checks and cleans a URL.



esc_html()wp-includes/formatting.php

Escaping for HTML blocks.



add_query_arg()wp-includes/functions.php

Retrieves a modified URL query string.



number_format_i18n()wp-includes/functions.php

Converts float number to format based on the locale.



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.



wpdb::get_results()wp-includes/class-wpdb.php

Retrieves an entire SQL result set from the database (i.e., many rows).





Show 20 moreShow less

Changelog

Version	Description
2.5.0	Introduced.

云策 WordPress 开发者社区

函数文档

media_upload_library_form()

概述

关键要点

代码示例

注意事项

Parameters

Source

Changelog