Миниатюры в WordPress. Как добавить поддержку миниатюр в WordPress и настроить их отображение
Миниатюры в WordPress, которые также часто называют featured image или изображением записи, — это один из базовых элементов оформления современной темы. Именно они чаще всего выводятся в списках статей, карточках записей, категориях, архивах, на главной странице сайта, в блоках похожих материалов и в социальных превью. Если тема работает с миниатюрами неправильно, интерфейс быстро начинает выглядеть неаккуратно: карточки имеют разную высоту, изображения растягиваются или вообще не выводятся.
В этой статье подробно разберём, как включить поддержку миниатюр в WordPress, как настроить собственные размеры изображений, как правильно выводить featured image в шаблонах и как весь этот механизм устроен внутри ядра. Отдельно рассмотрим, где WordPress хранит связь между записью и изображением в базе данных, какие метаданные создаются при загрузке файла и почему после изменения размеров недостаточно просто поправить код в
functions.php.
Важно понимать: миниатюра записи в WordPress — это не просто “любая прикреплённая картинка”, а конкретный attachment, который назначается записи как featured image.
Зачем теме нужна поддержка миниатюр
Когда тема WordPress объявляет поддержку миниатюр, она сообщает ядру, что для записей, страниц или кастомных типов записей нужно показывать в админке блок выбора featured image, а шаблоны смогут получать это изображение через стандартные функции WordPress. Обычно миниатюры используются в следующих местах:
- на страницах архива блога;
- в карточках статей на главной;
- в слайдерах и hero-блоках;
- на страницах категорий и тегов;
- в кастомных типах записей, например “Книги”, “Товары”, “Новости”, “Портфолио”.
Базовое подключение выполняется через
add_theme_support('post-thumbnails'). Лучше всего делать это на хуке
after_setup_theme, чтобы тема корректно зарегистрировала свою функциональность ещё на этапе инициализации.
<?php
add_action('after_setup_theme', function () {
add_theme_support('post-thumbnails');
});
Это минимальная стартовая конфигурация. После добавления такого кода в админке WordPress появится возможность назначать миниатюру записи, а в шаблонах можно будет использовать стандартные функции вроде
has_post_thumbnail(),
get_post_thumbnail_id() и
the_post_thumbnail().
Как ограничить поддержку только для нужных типов записей
В реальном проекте не всегда нужно включать featured image для всех сущностей. Например, для обычных постов и кастомного типа
book это полезно, а для некоторых служебных страниц — нет. В этом случае лучше явно перечислить те post type, которые действительно должны поддерживать миниатюры.
<?php
add_action('after_setup_theme', function () {
add_theme_support('post-thumbnails', ['post', 'page', 'book']);
});
Такой подход особенно удобен в кастомных темах с большим количеством нестандартных сущностей. Это упрощает поддержку проекта и сразу даёт понять, где именно featured image реально используется.
Настройка базового и дополнительных размеров изображений
Само подключение поддержки миниатюр — это только первый шаг. Далее нужно определить, в каких размерах изображения будут использоваться в теме. Для этого WordPress предоставляет два основных инструмента:
set_post_thumbnail_size() для базового размера featured image и
add_image_size() для любых дополнительных кастомных размеров.
<?php
add_action('after_setup_theme', function () {
add_theme_support('post-thumbnails');
// Базовый размер для the_post_thumbnail()
set_post_thumbnail_size(320, 220, true);
// Дополнительные размеры для разных зон шаблона
add_image_size('card-thumb', 420, 280, true);
add_image_size('hero-thumb', 1280, 720, true);
add_image_size('sidebar-thumb', 120, 120, true);
});
Третий параметр
true означает жёсткое кадрирование. Это полезно для карточек, где требуется одинаковая геометрия у всех превью. Если указать
false, WordPress будет стараться сохранить пропорции изображения, и тогда высота разных карточек может отличаться.
На практике лучше сразу продумать, какие размеры действительно нужны в теме. Например, для каталога книг может понадобиться вертикальное изображение обложки, а для блога — горизонтальное превью. Один универсальный размер почти всегда проигрывает набору нескольких целевых размеров.
Обрати внимание: если новые размеры были добавлены уже после того, как изображения раньше загружались в медиабиблиотеку, WordPress не создаст эти файлы автоматически задним числом. Для старых вложений обычно требуется регенерация миниатюр.
Вывод миниатюры в цикле WordPress
Самый частый сценарий — показать изображение в архиве или на главной странице блога. Здесь важно не просто вызвать
the_post_thumbnail(), но и проверить, существует ли featured image, чтобы не получить пустую зону или сломанную вёрстку.
<article class="post-card">
<a class="post-card__image" href="<?php the_permalink(); ?>">
<?php if (has_post_thumbnail()) : ?>
<?php the_post_thumbnail('card-thumb', ['class' => 'img-responsive']); ?>
<?php else : ?>
<img src="<?php echo esc_url(get_template_directory_uri() . '/assets/img/no-image.jpg'); ?>" alt="<?php the_title_attribute(); ?>" class="img-responsive">
<?php endif; ?>
</a>
<h2 class="post-card__title">
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
</h2>
<div class="post-card__excerpt">
<?php the_excerpt(); ?>
</div>
</article>
Здесь сразу видно правильную практику: есть проверка наличия миниатюры, предусмотрена fallback-картинка, а само изображение выводится уже в заранее подготовленном размере
card-thumb. Это заметно лучше, чем тянуть full-size и уменьшать его только через CSS.
Вывод миниатюры на странице записи
На странице отдельного материала логика может быть немного другой. Здесь обычно нужен больший размер, дополнительные HTML-атрибуты и отдельный контейнер для стилизации. Удобно передавать массив атрибутов прямо вторым параметром в функцию.
<?php if (has_post_thumbnail()) : ?>
<div class="post-cover">
<?php
the_post_thumbnail('hero-thumb', [
'class' => 'img-responsive center-block',
'loading' => 'lazy',
'alt' => get_the_title(),
]);
?>
</div>
<?php endif; ?>
Такой вариант особенно удобен для контентных сайтов, где featured image стоит над заголовком или сразу после него. Если же миниатюра нужна только для архивов и превью, на странице полного материала её можно вообще не выводить — всё зависит от логики темы.
Как миниатюры работают внутри ядра WordPress
Теперь самое интересное — внутренняя механика. Когда ты загружаешь изображение в медиабиблиотеку, WordPress создаёт отдельную запись типа
attachment. То есть картинка — это не просто файл на диске, а полноценная запись в таблице
wp_posts со своим ID, MIME-типом, датой создания и другими служебными данными.
Когда это изображение назначается как featured image для статьи, WordPress записывает в таблицу
wp_postmeta в метаполе
_thumbnail_id ID attachment-записи. Именно поэтому одна и та же картинка теоретически может использоваться как миниатюра для разных материалов, а также как обычное вложение.
Далее вступает в работу генерация метаданных. При загрузке WordPress анализирует исходный файл, вычисляет размеры, создаёт набор промежуточных копий и сохраняет служебную информацию в метаполе attachment’а. Именно там лежат пути к промежуточным файлам, их ширина, высота, MIME-тип и дополнительный image meta. Когда тема запрашивает, например,
card-thumb, ядро не “обрезает на лету” оригинал, а получает уже готовую версию нужного размера.
<?php
$post_id = get_the_ID();
$thumbnail_id = get_post_thumbnail_id($post_id);
$meta = wp_get_attachment_metadata($thumbnail_id);
echo '<pre>';
print_r([
'post_id' => $post_id,
'thumbnail_id' => $thumbnail_id,
'meta' => $meta,
]);
echo '</pre>';
Такой отладочный фрагмент хорошо показывает связь между постом, его миниатюрой и attachment metadata. В массиве
$meta ты увидишь исходный файл и секцию
sizes, где перечислены все созданные версии изображения.
Если описать всю цепочку максимально просто, она выглядит так:
- ты загружаешь файл в медиабиблиотеку;
- WordPress создаёт attachment как отдельную запись;
- ядро генерирует дополнительные размеры изображения;
- метаданные этих размеров сохраняются у attachment;
- для конкретной записи в
_thumbnail_id сохраняется ID attachment;
- шаблон через
the_post_thumbnail() получает правильное изображение нужного размера.
Почему миниатюра иногда не выводится
Есть несколько типичных причин. Первая — тема не вызвала
add_theme_support('post-thumbnails'). Вторая — для записи фактически не назначено featured image. Третья — в шаблоне используется неправильный size или кастомный размер, который не был сгенерирован для старых файлов. Четвёртая — вёрстка или CSS скрывают изображение, хотя HTML уже присутствует на странице.
Ещё одна распространённая ошибка — тянуть полный размер картинки в архивный список и надеяться, что браузер или стили “как-нибудь подгонят”. Это лишняя нагрузка на страницу, хуже показатели производительности и больше трафика, особенно если на странице выводится много записей.
CSS для аккуратного отображения миниатюр
Даже если PHP-часть настроена правильно, конечный результат сильно зависит от стилей. Для ровных карточек блога обычно достаточно сделать фиксированный контейнер, скрыть всё лишнее и заставить изображение заполнять область без деформации.
.post-card__image {
display: block;
overflow: hidden;
margin-bottom: 15px;
background: #f5f5f5;
}
.post-card__image img {
display: block;
width: 100%;
height: 280px;
object-fit: cover;
}
.post-cover {
margin: 0 0 25px;
}
.post-cover img {
display: block;
width: 100%;
height: auto;
}
Если сайт должен работать в среде, где
object-fit использовать нежелательно, можно пойти другим путём: применять пропорциональные контейнеры, background-image или жёсткие серверные кропы нужного формата. Но для большинства современных проектов такого CSS вполне достаточно.
Как кастомизировать HTML миниатюры через фильтр
Иногда стандартного HTML от
the_post_thumbnail() недостаточно. Например, нужно автоматически добавить собственный класс, обёртку, data-атрибуты или особое поведение для lazy-loading. В таких случаях выручает фильтр HTML миниатюры.
<?php
add_filter('post_thumbnail_html', function ($html, $post_id, $thumbnail_id, $size, $attr) {
if (is_admin()) {
return $html;
}
return '<div class="entry-thumbnail">' . $html . '</div>';
}, 10, 5);
Это уже тот уровень, где миниатюры становятся не просто “картинкой в шаблоне”, а частью архитектуры темы. Такой подход удобен тем, что позволяет централизованно контролировать вывод и не размазывать мелкие правки по множеству файлов.
Итог
Поддержка миниатюр в WordPress состоит из нескольких слоёв: регистрация функции в теме, создание нужных image sizes, правильный вывод в шаблонах и понимание того, как featured image хранится в базе и обрабатывается ядром. Если настроить это аккуратно, тема будет выглядеть стабильнее, работать быстрее и останется предсказуемой для дальнейшей поддержки.
Лучшая практика — не ограничиваться одним вызовом
the_post_thumbnail(), а продумать систему размеров, fallback-изображение, CSS для карточек и отладку через
get_post_thumbnail_id() и
wp_get_attachment_metadata(). Именно такой подход позволяет получить не просто “картинку в записи”, а полноценную, технически грамотную работу с миниатюрами в WordPress.