云策 WordPress 开发者社区

函数文档

set_post_thumbnail()

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

概述

set_post_thumbnail() 函数用于为指定文章设置缩略图（特色图像）。它接受文章ID或文章对象以及缩略图ID作为参数，通过更新或删除_postmeta表中的_thumbnail_id元数据来实现功能。

关键要点

  • 参数：$post（必需，文章ID或WP_Post对象），$thumbnail_id（必需，缩略图附件ID）
  • 返回值：成功时返回元数据ID（首次设置）或true（更新成功），失败或值未变时返回false
  • 内部逻辑：验证文章和缩略图存在后，调用update_post_meta()或delete_post_meta()操作_thumbnail_id元字段
  • 相关函数：包括wp_get_attachment_image()、update_post_meta()、delete_post_meta()、absint()、get_post()等
  • 使用场景：被WP_REST_Posts_Controller、AJAX处理函数、wp_insert_post()等核心功能调用

代码示例

// 示例：将上传的图像文件设置为文章缩略图
$upload_file = wp_upload_bits($filename, null, @file_get_contents($file));
if (!$upload_file['error']) {
    $wp_filetype = wp_check_filetype($filename, null);
    $attachment = array(
        'post_mime_type' => $wp_filetype['type'],
        'post_parent'    => $post_id,
        'post_title'     => preg_replace('/.[^.]+$/', '', $filename),
        'post_content'   => '',
        'post_status'    => 'inherit'
    );
    $attachment_id = wp_insert_attachment($attachment, $upload_file['file'], $post_id);
    if (!is_wp_error($attachment_id)) {
        require_once(ABSPATH . "wp-admin" . '/includes/image.php');
        $attachment_data = wp_generate_attachment_metadata($attachment_id, $upload_file['file']);
        wp_update_attachment_metadata($attachment_id, $attachment_data);
        set_post_thumbnail($post_id, $attachment_id);
    }
}

注意事项

  • 返回值说明：成功时可能返回元数据ID或true，具体取决于是否为首次设置；失败或值未变时返回false
  • 重复调用：如果缩略图已设置为相同附件ID，函数会返回false，因为update_post_meta()在值未改变时返回false
  • 验证：函数内部会检查文章和缩略图是否存在，以及缩略图是否有效图像
📄 原文内容

Sets the post thumbnail (featured image) for the given post.

Parameters

$postint|WP_Postrequired
Post ID or post object where thumbnail should be attached.
$thumbnail_idintrequired
Thumbnail to attach.

Return

int|bool Post meta ID if the key didn’t exist (ie. this is the first time that a thumbnail has been saved for the post), true on successful update, false on failure or if the value passed is the same as the one that is already in the database.

Source

function set_post_thumbnail( $post, $thumbnail_id ) {
	$post         = get_post( $post );
	$thumbnail_id = absint( $thumbnail_id );
	if ( $post && $thumbnail_id && get_post( $thumbnail_id ) ) {
		if ( wp_get_attachment_image( $thumbnail_id, 'thumbnail' ) ) {
			return update_post_meta( $post->ID, '_thumbnail_id', $thumbnail_id );
		} else {
			return delete_post_meta( $post->ID, '_thumbnail_id' );
		}
	}
	return false;
}

View all references View on Trac View on GitHub

Uses Description
wp_get_attachment_image()wp-includes/media.php

Gets an HTML img element representing an image attachment.
update_post_meta()wp-includes/post.php

Updates a post meta field based on the given post ID.
delete_post_meta()wp-includes/post.php

Deletes a post meta field for the given post ID.
absint()wp-includes/load.php

Converts a value to non-negative integer.
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.

Show 2 moreShow less

Used by Description
WP_REST_Posts_Controller::handle_featured_media()wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Determines the featured media based on a request param.
wp_ajax_set_attachment_thumbnail()wp-admin/includes/ajax-actions.php

Handles setting the featured image for an attachment via AJAX.
wp_ajax_set_post_thumbnail()wp-admin/includes/ajax-actions.php

Handles setting the featured image via AJAX.
wp_insert_post()wp-includes/post.php

Inserts or update a post.
wp_xmlrpc_server::mw_editPost()wp-includes/class-wp-xmlrpc-server.php

Edits a post.
wp_xmlrpc_server::mw_newPost()wp-includes/class-wp-xmlrpc-server.php

Creates a new post.
wp_xmlrpc_server::_insert_post()wp-includes/class-wp-xmlrpc-server.php

Helper method for wp_newPost() and wp_editPost(), containing shared logic.

Show 2 moreShow less

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Aurovrata Venet


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

    To programmatically setup an uploaded image file as a thumbnail, you can use the following code…

    /*
 * $file is the path to your uploaded file (for example as set in the $_FILE posted file array)
 * $filename is the name of the file
 * first we need to upload the file into the wp upload folder.
 */
$upload_file = wp_upload_bits( $filename, null, @file_get_contents( $file ) );
i
f ( ! $upload_file['error'] ) {
  // if succesfull insert the new file into the media library (create a new attachment post type).
  $wp_filetype = wp_check_filetype($filename, null );

  $attachment = array(
    'post_mime_type' => $wp_filetype['type'],
	'post_parent'    => $post_id,
	'post_title'     => preg_replace( '/.[^.]+$/', '', $filename ),
	'post_content'   => '',
	'post_status'    => 'inherit'
  );

  $attachment_id = wp_insert_attachment( $attachment, $upload_file['file'], $post_id );

  if ( ! is_wp_error( $attachment_id ) ) {
     // if attachment post was successfully created, insert it as a thumbnail to the post $post_id.
     require_once(ABSPATH . "wp-admin" . '/includes/image.php');

     $attachment_data = wp_generate_attachment_metadata( $attachment_id, $upload_file['file'] );

     wp_update_attachment_metadata( $attachment_id,  $attachment_data );
     set_post_thumbnail( $post_id, $attachment_id );
   }
}