_wp_post_thumbnail_html()

💡 云策文档标注

概述

_wp_post_thumbnail_html() 函数用于生成文章缩略图（特色图像）元框的 HTML 标记。它根据是否设置了缩略图，动态生成包含设置、编辑或移除链接的界面，并支持通过过滤器进行自定义。

关键要点

函数返回文章缩略图元框的 HTML 字符串，用于 WordPress 后台管理界面。
接受两个可选参数：$thumbnail_id（缩略图附件 ID）和 $post（文章 ID 或对象），默认使用全局 $post。
当未设置缩略图时，生成设置特色图像的链接；当已设置时，显示缩略图图像、编辑提示和移除链接。
使用 wp_get_additional_image_sizes() 获取额外图像尺寸，并支持通过 admin_post_thumbnail_size 过滤器调整显示尺寸。
输出内容可通过 admin_post_thumbnail_html 过滤器进行修改，允许开发者自定义 HTML 标记。
函数内部调用了多个核心函数，如 wp_get_attachment_image()、get_upload_iframe_src() 和 esc_url() 等，确保安全性和功能性。

代码示例

function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
    $_wp_additional_image_sizes = wp_get_additional_image_sizes();
    $post = get_post( $post );
    $post_type_object = get_post_type_object( $post->post_type );
    $set_thumbnail_link = '%s';
    $upload_iframe_src = get_upload_iframe_src( 'image', $post->ID );
    $content = sprintf(
        $set_thumbnail_link,
        esc_url( $upload_iframe_src ),
        '',
        esc_html( $post_type_object->labels->set_featured_image )
    );
    if ( $thumbnail_id && get_post( $thumbnail_id ) ) {
        $size = isset( $_wp_additional_image_sizes['post-thumbnail'] ) ? 'post-thumbnail' : array( 266, 266 );
        $size = apply_filters( 'admin_post_thumbnail_size', $size, $thumbnail_id, $post );
        $thumbnail_html = wp_get_attachment_image( $thumbnail_id, $size );
        if ( ! empty( $thumbnail_html ) ) {
            $content = sprintf(
                $set_thumbnail_link,
                esc_url( $upload_iframe_src ),
                ' aria-describedby="set-post-thumbnail-desc"',
                $thumbnail_html
            );
            $content .= '' . __( 'Click the image to edit or update' ) . '';
            $content .= '' . esc_html( $post_type_object->labels->remove_featured_image ) . '';
        }
    }
    $content .= '';
    return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id );
}

注意事项

函数主要用于后台管理界面，生成元框内容，不直接用于前端显示。
当主题支持 'post-thumbnail' 时，会注册特殊的图像尺寸，与媒体设置中的 'thumbnail' 尺寸不同。
使用过滤器时，注意参数顺序和类型，如 admin_post_thumbnail_size 接受字符串或数组作为尺寸参数。
函数依赖于 Thickbox JavaScript 库来提供上传界面，确保相关脚本已加载。

📄 原文内容

Returns HTML for the post thumbnail meta box.

Parameters

$thumbnail_idint|nulloptional: Thumbnail attachment ID.

Default:null
$postint|WP_Post|nulloptional: The post ID or object associated with the thumbnail. Defaults to global $post.

Default:null

Return

string The post thumbnail HTML.

Source

function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
	$_wp_additional_image_sizes = wp_get_additional_image_sizes();

	$post               = get_post( $post );
	$post_type_object   = get_post_type_object( $post->post_type );
	$set_thumbnail_link = '<p class="hide-if-no-js"><a href="%s" id="set-post-thumbnail"%s class="thickbox">%s</a></p>';
	$upload_iframe_src  = get_upload_iframe_src( 'image', $post->ID );

	$content = sprintf(
		$set_thumbnail_link,
		esc_url( $upload_iframe_src ),
		'', // Empty when there's no featured image set, `aria-describedby` attribute otherwise.
		esc_html( $post_type_object->labels->set_featured_image )
	);

	if ( $thumbnail_id && get_post( $thumbnail_id ) ) {
		$size = isset( $_wp_additional_image_sizes['post-thumbnail'] ) ? 'post-thumbnail' : array( 266, 266 );

		/**
		 * Filters the size used to display the post thumbnail image in the 'Featured image' meta box.
		 *
		 * Note: When a theme adds 'post-thumbnail' support, a special 'post-thumbnail'
		 * image size is registered, which differs from the 'thumbnail' image size
		 * managed via the Settings > Media screen.
		 *
		 * @since 4.4.0
		 *
		 * @param string|int[] $size         Requested image size. Can be any registered image size name, or
		 *                                   an array of width and height values in pixels (in that order).
		 * @param int          $thumbnail_id Post thumbnail attachment ID.
		 * @param WP_Post      $post         The post object associated with the thumbnail.
		 */
		$size = apply_filters( 'admin_post_thumbnail_size', $size, $thumbnail_id, $post );

		$thumbnail_html = wp_get_attachment_image( $thumbnail_id, $size );

		if ( ! empty( $thumbnail_html ) ) {
			$content  = sprintf(
				$set_thumbnail_link,
				esc_url( $upload_iframe_src ),
				' aria-describedby="set-post-thumbnail-desc"',
				$thumbnail_html
			);
			$content .= '<p class="hide-if-no-js howto" id="set-post-thumbnail-desc">' . __( 'Click the image to edit or update' ) . '</p>';
			$content .= '<p class="hide-if-no-js"><a href="#" id="remove-post-thumbnail">' . esc_html( $post_type_object->labels->remove_featured_image ) . '</a></p>';
		}
	}

	$content .= '<input type="hidden" id="_thumbnail_id" name="_thumbnail_id" value="' . esc_attr( $thumbnail_id ? $thumbnail_id : '-1' ) . '" />';

	/**
	 * Filters the admin post thumbnail HTML markup to return.
	 *
	 * @since 2.9.0
	 * @since 3.5.0 Added the `$post_id` parameter.
	 * @since 4.6.0 Added the `$thumbnail_id` parameter.
	 *
	 * @param string   $content      Admin post thumbnail HTML markup.
	 * @param int      $post_id      Post ID.
	 * @param int|null $thumbnail_id Thumbnail attachment ID, or null if there isn't one.
	 */
	return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘admin_post_thumbnail_html’, string $content, int $post_id, int|null $thumbnail_id ): Filters the admin post thumbnail HTML markup to return.
apply_filters( ‘admin_post_thumbnail_size’, string|int[] $size, int $thumbnail_id, WP_Post $post ): Filters the size used to display the post thumbnail image in the ‘Featured image’ meta box.

Uses	Description
wp_get_additional_image_sizes()`wp-includes/media.php`	Retrieves additional image sizes.
get_upload_iframe_src()`wp-admin/includes/media.php`	Retrieves the upload iframe source URL.
wp_get_attachment_image()`wp-includes/media.php`	Gets an HTML img element representing an image attachment.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_url()`wp-includes/formatting.php`	Checks and cleans a URL.
esc_html()`wp-includes/formatting.php`	Escaping for HTML blocks.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.
get_post_type_object()`wp-includes/post.php`	Retrieves a post type object by name.

Show 7 more Show less

Used by	Description
wp_ajax_get_post_thumbnail_html()`wp-admin/includes/ajax-actions.php`	Handles retrieving HTML for the featured image via AJAX.
wp_ajax_set_post_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image via AJAX.
post_thumbnail_meta_box()`wp-admin/includes/meta-boxes.php`	Displays post thumbnail meta box.

Changelog

Version	Description
2.9.0	Introduced.

User Contributed Notes

Skip to note 2 content

Sakib MD Nazmush

2 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

The _wp_post_thumbnail_html function is responsible for generating HTML markup for post thumbnails, often known as featured images. Let’s get into the specifics of what this function can do:

wp_get_additional_image_sizes() retrieves additional image sizes and puts them in $_wp_additional_image_sizes. This provides flexibility in dealing with different image dimensions.

This get_post($post) function gets information about the current post and the post type object using get_post_type_object($post->post_type). This provides the structure for explaining the featured image within the context of the selected post type.

$set_thumbnail_link function creates a link that is in charge of setting the post thumbnail. This link is contained within a paragraph and contains an ID, URL, and caption for modifying the featured image. It is intended to work in combination with the Thickbox JavaScript library to provide a user-friendly interface.

When a post has a thumbnail attached, the wp_get_attachment_image() function comes into play by providing the necessary HTML code. A key benefit of this function is its ability to let developers adjust the size of the displayed image within the admin interface using suitable filters.

When a thumbnail is present, the $_wp_additional_image_sizes function goes the extra mile by appending descriptive components to the output. These include helpful directives for editing or upgrading the image, as well as a convenient removal link for the featured image. This enriches the overall user experience.

In order to smooth the submission process of thumbnail-related data with each post, the function expertly creates a hidden input field. This field expertly stores the thumbnail ID, guaranteeing its connection to the proper post.

Developers can easily customize the generated HTML markup to meet their specific needs by using the Admin_post_thumbnail_html filter, providing a high level of flexibility and personalization.

Lastly, this function can be seen as the unsung hero working tirelessly in the background, carefully managing post thumbnails to guarantee their aesthetic appeal, adaptability to different post formats, and ultimately creating a superior experience for both users and developers.

Log in to add feedback

云策 WordPress 开发者社区

函数文档

_wp_post_thumbnail_html()

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Hooks

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Hooks

Related

Changelog

User Contributed Notes