云策 WordPress 开发者社区

钩子文档

admin_post_thumbnail_html

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

概述

admin_post_thumbnail_html 是一个 WordPress 过滤器，用于修改后台文章特色图片的 HTML 标记。它允许开发者自定义特色图片区域的显示内容，例如添加帮助文本或调整布局。

关键要点

  • 过滤器名称：admin_post_thumbnail_html
  • 参数：$content（HTML 标记字符串）、$post_id（文章 ID）、$thumbnail_id（缩略图附件 ID，可为 null）
  • 用途：过滤后台特色图片的 HTML 输出，常用于添加自定义文本或修改显示
  • 引入版本：WordPress 2.9.0，后续版本增加了 $post_id 和 $thumbnail_id 参数
  • 注意事项：在 Gutenberg 编辑器中可能不兼容，需关注相关讨论

代码示例

function filter_featured_image_admin_text( $content, $post_id, $thumbnail_id ){
    $help_text = '<p>' . __( 'Please use an image that is 1170 pixels wide x 658 pixels tall.', 'my_domain' ) . '</p>';
    return $help_text . $content;
}
add_filter( 'admin_post_thumbnail_html', 'filter_featured_image_admin_text', 10, 3 );

注意事项

  • 此过滤器在传统编辑器中有效，但在 Gutenberg 编辑器中可能不工作，有相关 GitHub 问题讨论
  • 使用时需确保函数参数匹配（三个参数），并正确设置 add_filter 的优先级和参数数量
📄 原文内容

Filters the admin post thumbnail HTML markup to return.

Parameters

$contentstring
Admin post thumbnail HTML markup.
$post_idint
Post ID.
$thumbnail_idint|null
Thumbnail attachment ID, or null if there isn’t one.

Source

return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id );

View all references View on Trac View on GitHub

Used by Description
_wp_post_thumbnail_html()wp-admin/includes/post.php

Returns HTML for the post thumbnail meta box.

Changelog

Version Description
4.6.0 Added the $thumbnail_id parameter.
3.5.0 Added the $post_id parameter.
2.9.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Jonathan Goldford


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

    Below is an example of how to use this filter to provide some additional text to admins on what size image to use for their featured images. If an image is currently in place, this text will show above it. If not, the help text will show just above the “Set featured image” link.

    function filter_featured_image_admin_text( $content, $post_id, $thumbnail_id ){
    $help_text = '<p>' . __( 'Please use an image that is 1170 pixels wide x 658 pixels tall.', 'my_domain' ) . '</p>';
    return $help_text . $content;
}
add_filter( 'admin_post_thumbnail_html', 'filter_featured_image_admin_text', 10, 3 );