Miniatury w WordPressie. Jak włączyć obsługę miniatur w WordPressie i skonfigurować ich wyświetlanie
Miniatury w WordPressie, nazywane też featured image albo obrazkiem wyróżniającym, są jednym z podstawowych elementów nowoczesnego motywu. To właśnie one najczęściej pojawiają się na liście wpisów, w kartach artykułów, w archiwach, na stronie głównej, w sekcji podobnych materiałów oraz w podglądach udostępnień. Jeżeli motyw nie obsługuje miniatur poprawnie, układ strony szybko traci spójność: karty mają różną wysokość, obrazy rozciągają się albo nie wyświetlają się wcale.
W tym poradniku krok po kroku omówimy, jak włączyć obsługę miniatur w WordPressie, jak zdefiniować własne rozmiary obrazów, jak poprawnie wyświetlać featured image w plikach szablonu oraz jak cały ten mechanizm działa od strony rdzenia systemu. Dodatkowo pokażemy, gdzie WordPress zapisuje powiązanie między wpisem a obrazem w bazie danych i dlaczego po zmianie rozmiarów sam zapis w
functions.php nie zawsze wystarcza.
Warto wiedzieć: miniatura wpisu w WordPressie nie jest „dowolnym załączonym obrazem”, tylko konkretnym attachmentem przypisanym do posta jako featured image.
Po co motywowi obsługa miniatur
Kiedy motyw deklaruje obsługę miniatur, informuje rdzeń WordPressa, że dla wpisów, stron albo własnych typów treści powinien pojawić się w panelu edycji moduł wyboru featured image, a szablony mogą korzystać ze standardowych funkcji do pobrania i wyświetlenia tego obrazu. Najczęściej wykorzystuje się to w takich miejscach jak:
- archiwa bloga;
- karty artykułów na stronie głównej;
- slidery i sekcje hero;
- strony kategorii i tagów;
- własne typy wpisów, np. „Książki”, „Produkty”, „Aktualności” lub „Portfolio”.
Podstawowa aktywacja odbywa się za pomocą
add_theme_support('post-thumbnails'). Najlepiej wykonać to na hooku
after_setup_theme, aby motyw zarejestrował tę funkcjonalność na odpowiednim etapie inicjalizacji.
<?php
add_action('after_setup_theme', function () {
add_theme_support('post-thumbnails');
});
To minimalna konfiguracja startowa. Po dodaniu takiego kodu w panelu WordPressa pojawi się możliwość ustawienia obrazka wyróżniającego, a w plikach motywu będzie można używać funkcji takich jak
has_post_thumbnail(),
get_post_thumbnail_id() oraz
the_post_thumbnail().
Jak ograniczyć obsługę tylko do wybranych typów wpisów
W praktycznym projekcie nie zawsze chcemy włączać miniatury dla wszystkich treści. Czasem wystarczą zwykłe wpisy oraz własny typ
book, a dla stron technicznych taka funkcja nie jest potrzebna. Wtedy lepiej od razu jawnie określić, dla jakich post type miniatury mają działać.
<?php
add_action('after_setup_theme', function () {
add_theme_support('post-thumbnails', ['post', 'page', 'book']);
});
To rozwiązanie jest szczególnie przydatne w rozbudowanych motywach z większą liczbą niestandardowych treści. Dzięki temu łatwiej kontrolować interfejs edytora i utrzymać porządek w kodzie.
Konfiguracja podstawowego i dodatkowych rozmiarów
Samo włączenie obsługi miniatur to dopiero początek. Kolejnym krokiem jest określenie, w jakich rozmiarach obrazy będą wykorzystywane w motywie. WordPress oferuje tutaj dwa podstawowe narzędzia:
set_post_thumbnail_size() dla domyślnego rozmiaru featured image oraz
add_image_size() dla własnych dodatkowych wariantów.
<?php
add_action('after_setup_theme', function () {
add_theme_support('post-thumbnails');
// Domyślny rozmiar dla the_post_thumbnail()
set_post_thumbnail_size(320, 220, true);
// Dodatkowe rozmiary dla różnych sekcji motywu
add_image_size('card-thumb', 420, 280, true);
add_image_size('hero-thumb', 1280, 720, true);
add_image_size('sidebar-thumb', 120, 120, true);
});
Trzeci parametr ustawiony na
true oznacza twarde kadrowanie. Jest to bardzo wygodne w kartach artykułów i siatkach wpisów, gdzie wszystkie miniatury powinny mieć identyczne proporcje. Jeśli ustawisz
false, WordPress zachowa proporcje obrazu, ale wysokość miniaturek może się różnić.
Warto od razu zaplanować, jakie rozmiary są potrzebne w konkretnych miejscach motywu. Dla katalogu książek może być potrzebny wąski pionowy obraz okładki, a dla bloga poziome zdjęcie do listy wpisów. Jeden uniwersalny rozmiar zwykle nie daje najlepszego efektu.
Uwaga: jeśli dodasz nowe rozmiary po wcześniejszym wgraniu obrazów, WordPress nie wygeneruje brakujących miniaturek automatycznie dla starych plików. W takich przypadkach zwykle trzeba odtworzyć miniatury.
Wyświetlanie miniatury w pętli WordPressa
Najczęstszy scenariusz to pokazanie obrazka w archiwum wpisów albo na stronie głównej bloga. W takim miejscu nie wystarczy samo
the_post_thumbnail(). Dobrą praktyką jest sprawdzenie, czy wpis faktycznie ma ustawioną miniaturę, oraz przygotowanie obrazu zastępczego.
<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>
W tym przykładzie obraz jest pobierany już w przygotowanym rozmiarze
card-thumb, a nie w pełnym rozmiarze. To znacznie lepsze rozwiązanie pod względem wydajności niż ładowanie oryginału i zmniejszanie go wyłącznie za pomocą CSS.
Wyświetlanie featured image na stronie pojedynczego wpisu
Na stronie pojedynczego artykułu często potrzebny jest większy rozmiar, dodatkowe atrybuty HTML albo osobny kontener do stylowania. W takiej sytuacji wygodnie jest przekazać atrybuty jako tablicę bezpośrednio do funkcji.
<?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; ?>
Taki wariant dobrze sprawdza się w motywach contentowych, gdzie obraz wyróżniający pełni funkcję mocnego otwarcia artykułu. Jeżeli jednak featured image ma być używane tylko w archiwach i podglądach, na widoku pojedynczego wpisu można go w ogóle nie wyświetlać.
Jak miniatury działają wewnątrz rdzenia WordPressa
Od strony technicznej mechanizm jest bardzo ciekawy. Po wgraniu pliku do biblioteki mediów WordPress tworzy osobny wpis typu
attachment. Oznacza to, że obraz nie jest tylko plikiem na dysku, ale również rekordem w tabeli
wp_posts z własnym ID, typem MIME, datą dodania i innymi informacjami.
Gdy przypiszesz ten obraz jako featured image do wpisu, WordPress zapisze w tabeli
wp_postmeta wartość
_thumbnail_id, czyli identyfikator attachmentu. Właśnie ten klucz łączy zwykły wpis z konkretnym obrazem wyróżniającym.
Następnie WordPress generuje metadane obrazka. W trakcie uploadu analizuje plik, tworzy pośrednie rozmiary i zapisuje metainformacje attachmentu. W tych danych znajdują się między innymi nazwy wygenerowanych plików, ich szerokość, wysokość oraz dodatkowe informacje o obrazie. Dzięki temu, gdy motyw prosi o
card-thumb albo
hero-thumb, rdzeń sięga po gotową wersję o odpowiednim rozmiarze, zamiast przetwarzać oryginał przy każdym odświeżeniu strony.
<?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>';
Ten prosty fragment debugujący pozwala zobaczyć cały mechanizm: ID wpisu, ID miniatury oraz metadata attachmentu. W tablicy
$meta znajdziesz sekcję
sizes, w której zapisane są wszystkie wygenerowane rozmiary obrazka.
Cały proces można opisać tak:
- wgrywasz obraz do biblioteki mediów;
- WordPress tworzy attachment jako osobny rekord;
- rdzeń generuje dodatkowe rozmiary obrazu;
- metadane rozmiarów są zapisywane przy attachmentcie;
- w polu
_thumbnail_id wpisu zapisywane jest ID attachmentu;
- szablon przez
the_post_thumbnail() pobiera właściwą wersję obrazka.
Dlaczego miniatura czasem się nie wyświetla
Najczęstsze przyczyny są dość przewidywalne. Motyw mógł nie włączyć obsługi przez
add_theme_support('post-thumbnails'). Wpis może nie mieć przypisanego featured image. W szablonie mógł zostać użyty rozmiar, który nie istnieje albo nie został wygenerowany dla starszych plików. Czasem problem w ogóle nie leży po stronie PHP, tylko w CSS, który ukrywa obraz lub psuje układ kontenera.
Bardzo częstym błędem jest też ładowanie pełnego rozmiaru obrazu w archiwum wpisów i liczenie na to, że przeglądarka „sama sobie poradzi”. To niepotrzebnie obciąża stronę, pogarsza wydajność i zwiększa transfer.
CSS dla estetycznego wyświetlania miniatur
Nawet jeśli część PHP jest poprawna, końcowy efekt zależy jeszcze od stylów. W równych kartach artykułów zazwyczaj wystarczy zadbać o stały kontener, ukryć nadmiar i sprawić, by obraz wypełniał obszar bez zniekształceń.
.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;
}
Jeżeli w projekcie trzeba unikać
object-fit, można zastosować inne rozwiązanie: proporcjonalne kontenery, twarde kadrowanie po stronie serwera albo obraz w tle. W większości nowoczesnych motywów powyższy wariant jest jednak wystarczający.
Jak zmieniać HTML miniatury przez filtr
Zdarza się, że domyślny HTML zwracany przez
the_post_thumbnail() nie wystarcza. Może być potrzebne dodanie własnej klasy, wrappera albo atrybutów data. Wtedy warto skorzystać z filtra odpowiedzialnego za finalny HTML miniatury.
<?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);
To bardzo wygodna technika, jeśli chcesz scentralizować sposób renderowania obrazków wyróżniających i nie powtarzać drobnych zmian w wielu plikach motywu.
Podsumowanie
Obsługa miniatur w WordPressie składa się z kilku warstw: aktywacji funkcji w motywie, zdefiniowania odpowiednich rozmiarów, poprawnego wyświetlania w szablonach oraz zrozumienia, jak featured image jest zapisywane w bazie i obsługiwane przez rdzeń. Dobrze przygotowany system miniaturek poprawia wygląd motywu, wydajność i późniejszą utrzymywalność projektu.
Najlepsza praktyka to nie kończyć pracy na samym
the_post_thumbnail(), ale zaplanować zestaw rozmiarów, dodać fallback obrazka, zadbać o CSS kart oraz w razie potrzeby debugować wszystko przez
get_post_thumbnail_id() i
wp_get_attachment_metadata(). Dzięki temu miniatury przestają być tylko dodatkiem wizualnym i stają się dobrze zaprojektowanym elementem architektury WordPressa.