Мініатюри в WordPress. Як додати підтримку мініатюр у WordPress і налаштувати їх відображення
Мініатюри в WordPress, які також часто називають featured image або зображенням запису, — це один із базових елементів оформлення сучасної теми. Саме вони найчастіше відображаються у списках статей, картках записів, категоріях, архівах, на головній сторінці сайту, у блоці схожих матеріалів та в соціальних прев’ю. Якщо тема не вміє працювати з мініатюрами правильно, інтерфейс виглядає незавершеним: анонси “стрибають”, картки мають різну висоту, а зображення або розтягуються, або взагалі не показуються.
У цій статті детально розберемо, як увімкнути підтримку мініатюр у WordPress, як налаштувати власні розміри, як правильно виводити featured image у шаблонах і як усе це працює всередині ядра. Окремо пройдемося по тому, де WordPress зберігає зв’язок між записом і зображенням у базі даних, які метадані створюються під час завантаження картинки та чому після зміни розмірів не завжди достатньо просто змінити код у
functions.php.
Що важливо: мініатюра запису в WordPress — це не просто “будь-яке прикріплене зображення”, а конкретний attachment, який прив’язується до поста як featured image.
Навіщо темі підтримка мініатюр
Коли WordPress-тема декларує підтримку мініатюр, вона повідомляє ядру, що для записів, сторінок або кастомних типів записів потрібно показувати в адмінці блок вибору featured image і дозволяти шаблонам отримувати це зображення через стандартні функції ядра. Найчастіше це використовується для:
- архівних сторінок блогу;
- карток статей на головній;
- слайдерів і hero-блоків;
- сторінок категорій і тегів;
- кастомних post type, наприклад “Книги”, “Товари”, “Новини”, “Портфоліо”.
Базове підключення робиться через
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']);
});
Такий підхід особливо корисний у кастомних темах, де є багато нестандартних сутностей і потрібно чітко контролювати поведінку редактора. Крім того, це спрощує підтримку коду: відкривши файл теми, одразу видно, які типи записів реально працюють із мініатюрами.
Налаштування базового та додаткових розмірів
Сам факт підключення підтримки мініатюр — це лише половина задачі. Далі потрібно визначити, у яких саме розмірах зображення будуть використовуватись у темі. Для цього 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 намагатиметься зберегти пропорції, і тоді висота в різних картках може відрізнятися.
На практиці краще одразу подумати, де саме і які розміри потрібні. Наприклад, для каталогу книг може знадобитися вузьке вертикальне зображення обкладинки, а для блогу — горизонтальне прев’ю. Один універсальний розмір майже завжди програє набору кількох цільових image sizes.
Важливо: якщо ти додав нові розміри після того, як зображення вже були завантажені раніше, 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 стоїть над заголовком або одразу після нього. Якщо ж мініатюра потрібна тільки для архівів і соцмереж, у full view її можна взагалі не показувати — усе залежить від логіки теми.
Як працюють мініатюри в ядрі 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-запис;
- ядро генерує додаткові image sizes;
- метадані цих розмірів зберігаються для attachment;
- для конкретного поста в
_thumbnail_id записується ID attachment;
- шаблон через
the_post_thumbnail() отримує правильне зображення потрібного розміру.
Чому інколи мініатюра не показується
Є кілька типових причин. Перша — тема не викликала
add_theme_support('post-thumbnails'). Друга — для запису реально не призначено featured image. Третя — у шаблоні використано неправильний size або кастомний розмір, який не був згенерований для старих файлів. Четверта — верстка або CSS ховають зображення, хоча HTML уже присутній на сторінці.
Ще одна поширена помилка — тягнути повний розмір картинки в архівний список і сподіватися, що браузер або стилі “якось підженуть”. Це зайве навантаження на сторінку, гірший LCP і більше трафіку, особливо якщо на сторінці десятки записів.
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.