Czym są shortcody WordPress? Praktyczny przewodnik

Shortcody WordPress to krótkie fragmenty tekstu opakowane w kwadratowe nawiasy (jak [contact-form] lub [gallery ids="1,2,3"]), które WordPress zastępuje dynamiczną treścią podczas renderowania wpisu lub strony. Zostały wprowadzone w WordPress 2.5 (2008) i przez ponad dekadę były dominującym sposobem, w jaki wtyczki dodawały złożoną zawartość do treści. Od wdrożenia edytora bloków Gutenberg w WordPress 5.0 (2018) shortcody mają następcę: bloki. Ale shortcody nie znikają. Nadal działają, miliony witryn są od nich zależne, a wiele wtyczek nadal dostarcza je wraz z lub zamiast bloków.

Jak wygląda shortcode WordPress?

Podstawowy shortcode to nazwa w kwadratowych nawiasach:

[gallery]

WordPress widzi to w treści wpisu, wyszukuje zarejestrowany handler dla gallery, uruchamia funkcję PHP, i zastępuje tag tym, co handler wyemituje. Odwiedzający widzi galerię; edytor widzi [gallery].

Shortcody mogą przyjmować parametry (zwane atrybutami):

[gallery ids="42,43,44" columns="3" link="file"]

I mogą otaczać treść (zwane shortcodami otaczającymi):

[highlight color="yellow"]Ważny tekst[/highlight]

Handler shortcode otrzymuje atrybuty i wewnętrzną treść, przetwarza je w PHP i zwraca HTML do wstawienia na stronę. Odwiedzający nigdy nie widzi nawiasów; widzą wyrenderowane wyjście.

Jaka jest różnica między shortcodem a blokiem Gutenberg?

Oba produkują dynamiczną treść; różnią się tym, gdzie i jak ta treść jest generowana.

• Shortcody są po stronie serwera. Tag w kwadratowych nawiasach pozostaje w treści wpisu zapisanej w bazie danych. Gdy strona jest żądana, WordPress parsuje treść, znajduje shortcode, uruchamia handler PHP i podstawia wyjście. Widok edytora zawsze pokazuje surową składnię z nawiasami.
• Bloki są przechowywane jako wyrenderowany HTML (z komentarzami metadanych). Gdy zapisujesz wpis w edytorze bloków, wtyczka bloku generuje finalny HTML i zapisuje go w bazie danych. Edytor pokazuje podgląd wyrenderowanego bloku na żywo, a nie tag. Na frontendzie nie uruchamia się PHP, aby wyrenderować większość bloków; HTML jest serwowany bezpośrednio.

Praktyczne konsekwencje:

• Wydajność. Bloki są szybsze na frontendzie, ponieważ nie ma kroku parsowania i zastępowania. Shortcody wyzwalają skanowanie regex każdego wpisu przy każdym renderze.
• Doświadczenie edycji. Bloki pokazują, jak wyrenderowane wyjście będzie wyglądać, gdy edytujesz. Shortcody pokazują tylko tag; podglądasz wynik.
• Przenośność. Jeśli dezaktywujesz wtyczkę dostarczającą blok, zapisany HTML zwykle pozostaje widoczny (zamrożony w wersji ostatniego zapisu). Jeśli dezaktywujesz wtyczkę dostarczającą shortcode, tag w nawiasach pozostaje w treści jako zwykły tekst, co zwykle wygląda na zepsute.
• Ponowne użycie. Shortcody mogą być dodane wszędzie, gdzie działa PHP, w tym w widgetach, szablonach i excerptach. Bloki są zaprojektowane dla obszaru edytora bloków, chociaż "Bloki Wielokrotnego Użytku" i ruch FSE (full-site editing) zamykają tę lukę.

Które wbudowane shortcody WordPress nadal są dostarczane w core?

Rdzeń WordPress historycznie dostarczał garść shortcodów. W 2026 ci ocaleni w codebase:

• [gallery] — Galeria obrazów. Nadal używana przez edytor klasyczny i jako fallback gdy blok Galeria jest konwertowany.
• [caption] — Otacza obraz podpisem. W większości zastąpiona przez blok Obraz, ale nadal emitowana w niektórych workflow.
• [audio] i [video] — Natywny odtwarzacz HTML5 dla samodzielnie hostowanych mediów.
• [embed] — Wymusza osadzenie URL przez handler oEmbed. Rzadko potrzebne, ponieważ WordPress auto-osadza większość URLi.
• [playlist] — Playlisty audio i wideo. Niszowe użycie.

Zdecydowana większość shortcodów na jakiejkolwiek prawdziwej witrynie WordPress pochodzi z wtyczek i motywów, a nie z core.

Jakie rodzaje wtyczek używają shortcodów?

Pięć kategorii obejmuje prawie całe rzeczywiste użycie shortcodów:

• Formularze kontaktowe. Contact Form 7 ([contact-form-7 id="123"]), WPForms, Gravity Forms i Formidable wszystkie udostępniają formularze przez shortcody. Nawet gdy te wtyczki oferują też bloki Gutenberg, shortcode pozostaje wspierany dla wstecznej kompatybilności.
• E-commerce. WooCommerce używa shortcodów dla Koszyka, Checkoutu, Moje Konto i list produktów ([products limit="4"]). Edytor bloków ma teraz równoważne bloki, ale shortcody nadal dominują, ponieważ większość motywów została wokół nich zbudowana.
• Page buildery (w trybie legacy). Stary Visual Composer, WPBakery i podobne produkują masywne zagnieżdżone shortcody, gdy używane w edytorze klasycznym. Wyłączenie page buildera zostawia ścianę tagów [vc_row][vc_column]... jako zwykły tekst we wpisie — znany problem lock-in.
• Tabele cen, slidery, akordeony. Większość wtyczek "widget treści" (Soliloquy, Smart Slider, Easy Pricing Tables) historycznie była dostarczana jako shortcody. Wiele jest nadal aktywnie utrzymywanych, ale dodały bloki.
• Witryny członkowskie i edukacyjne. MemberPress, LearnDash i podobne ograniczają treść za pomocą wrapperów shortcodów jak [restrict role="member"]...[/restrict].

Jak shortcode faktycznie działa pod maską?

Trzy linie kodu wtyczki tworzą shortcode. Ten minimalny przykład rejestruje shortcode, który emituje żółte wyróżnienie:

add_shortcode('highlight', function ($atts, $content = null) {
    $atts = shortcode_atts([
        'color' => 'yellow',
    ], $atts, 'highlight');

    return '<mark style="background:' . esc_attr($atts['color']) . '">' . do_shortcode($content) . '</mark>';
});

Co się dzieje, gdy WordPress renderuje [highlight color="pink"]Witaj[/highlight]:

1. WordPress uruchamia filtr the_content, który zawiera do_shortcode().
2. do_shortcode() używa regex, aby znaleźć tagi shortcode w treści wpisu.
3. Dla każdego dopasowania wywołuje zarejestrowany handler z atrybutami (['color' => 'pink']) i wewnętrzną treścią ('Witaj').
4. Handler zwraca string, który zastępuje tag shortcode w wyjściu.
5. Treść wpisu jest następnie renderowana do przeglądarki z podstawionym tagiem.

Parsowanie regex przy każdym renderze wpisu to koszt wydajności. Na witrynie z tysiącami wpisów, bez cache'owania i z shortcodami w każdym wpisie, to się sumuje. Cache strony (Redis, WP Super Cache) naprawia to, przechowując ostatecznie wyrenderowany HTML i pomijając parsowanie.

Kiedy nadal powinienem używać shortcodów w 2026?

Trzy uzasadnione przypadki:

• Kompatybilność wsteczna. Jeśli twoja witryna już używa shortcodów z Contact Form 7, WooCommerce lub jakiejkolwiek ugruntowanej wtyczki, kontynuuj używanie ich. Masowe konwertowanie starych wpisów na bloki to wielodniowy projekt z niewielką wypłatą.
• Poza edytorem bloków. Widgety (w klasycznych obszarach widgetów), excerpty, pętle niestandardowych typów wpisów, treść page buildera i e-maile wysyłane przez szablony Mailchimp nadal akceptują shortcody, ale nie bloki. Shortcody działają w każdym kontekście, w którym można wywołać do_shortcode().
• Szablony i kod motywu. Umieszczenie echo do_shortcode('[my-form id="3"]'); w szablonie PHP to jednolinijkowy sposób na wstrzyknięcie wyjścia wtyczki. Bloki wymagałyby renderowania bloku po stronie serwera, co jest więcej kodu.

Dla naprawdę nowej funkcjonalności na nowej witrynie preferuj bloki. To kierunek rdzenia WordPress, mają lepsze doświadczenie edycji i unikają narzutu parsowania shortcodów.

Czym jest "shortcode bloat" i dlaczego ma to znaczenie?

Shortcode bloat dzieje się, gdy witryna polega na dziesiątkach shortcodów z nieaktywnych lub dezaktywowanych wtyczek. Następują dwa tryby awarii:

• Wtyczka dezaktywowana, ale tagi pozostają. Dezaktywujesz wtyczkę slidera, aby coś przetestować. Każda strona, która miała [slider id="3"], teraz wyświetla literalny tekst "[slider id="3"]" zamiast slidera. Rozwiązaniem jest ponowna aktywacja wtyczki lub ręczne usunięcie wszystkich tagów shortcode z bazy danych, co jest żmudne.
• Migracja page buildera. Witryna zbudowana w Visual Composer lub WPBakery zawiera zagnieżdżone shortcody jak [vc_row][vc_column width="1/2"][vc_column_text]Witaj[/vc_column_text][/vc_column][/vc_row]. Zmiana motywu lub dezaktywacja buildera ujawnia to wszystko jako zwykły tekst. To jest źródło bólu "nie mogę zmigrować mojej witryny do Gutenberga", które uwięziło tysiące witryn.

Pragmatyczna prewencja: wybieraj wtyczki, do których zobowiązujesz się długoterminowo, i preferuj wtyczki, które obsługują też bloki, abyś mógł migrować stopniowo. Dla witryn zbudowanych przed 2018 oczekuj prawdziwego projektu migracji, a nie czystej zmiany.

Czy mogę stworzyć własny shortcode bez pisania wtyczki?

Tak, trzy sposoby:

1. W functions.php motywu podrzędnego. Dodaj wywołanie add_shortcode(). Shortcode staje się dostępny wszędzie na witrynie. Działa, ale shortcode jest powiązany z tym motywem; zmień motyw, a shortcode znika.
2. W niestandardowym mu-pluginie. Utwórz wp-content/mu-plugins/my-shortcodes.php i umieść tam swoje wywołania add_shortcode(). Przetrwa zmiany motywu i większość aktualizacji. Czystsze rozwiązanie.
3. Przez wtyczkę "Code Snippets". Wtyczki jak Code Snippets lub WPCode pozwalają dodać PHP przez UI admina. Wygodne, jeśli nie możesz edytować plików, ale dodaje zależność na poziomie admina dla kodu, który idealnie żyje w plikach.

Jakie są częste błędy z shortcodami?

• Zapomnienie do_shortcode() na wewnętrznej treści. Jeśli twój shortcode otacza treść (shortcode otaczający), powinieneś wywołać do_shortcode($content) na wewnętrznej części, aby zagnieżdżone shortcody działały. Bez tego [outer][inner][/outer] renderuje tylko zewnętrzny shortcode i pozostawia [inner] jako zwykły tekst.
• Echo wewnątrz handlera. Handlery shortcode muszą zwracać swoje wyjście, nie echoować. Wyechoowany shortcode renderuje się przed treścią, w którą jest osadzony, łamiąc layout strony w subtelne sposoby.
• Zapomnienie esc_attr() na atrybutach. Bez escapowania, wartości atrybutów dostarczone przez użytkownika mogą wyłamać się z HTML i tworzyć podatności XSS. Zawsze escapuj to, co emitujesz.
• Shortcody w widgetach, które ich nie uruchamiają. Niektóre klasyczne typy widgetów (jak podstawowy widget Text przed WordPress 4.9) nie wykonują automatycznie shortcodów. Naprawa: add_filter('widget_text', 'do_shortcode');.
• Tagi wewnątrz innych tagów powodujące zamieszanie w parsowaniu. Atrybut shortcode zawierający znak kwadratowego nawiasu ([shortcode label="Click [here]"]) myli parser. WordPress obsługuje wiele przypadków, ale nie wszystkie; używanie encji HTML ([ i ]) to bezpieczny workaround.
• Dodawanie shortcodów do do_shortcode rekursywnie. Wewnątrz handlera shortcode wywołanie do_shortcode() na treści zawierającej ten sam shortcode tworzy nieskończoną pętlę. WordPress ma zabezpieczenia, ale objawem jest pusta strona lub błąd wyczerpania pamięci.

Jak znaleźć każdy shortcode używany na mojej witrynie?

Trzy szybkie podejścia:

1. Wyszukiwanie w bazie danych. Uruchom zapytanie SQL przeciwko wp_posts: SELECT DISTINCT REGEXP_SUBSTR(post_content, '\\[[a-z_-]+') FROM wp_posts WHERE post_status = 'publish';. Wymienia każdy tag shortcode pojawiający się w opublikowanej treści.
2. WP-CLI. wp shortcode list pokazuje każdy zarejestrowany handler shortcode. Porównaj z listą bazy danych, aby znaleźć shortcody, które są używane, ale nie mają już aktywnego handlera (prawdopodobnie z dezaktywowanej wtyczki).
3. Wtyczki typu "Shortcode Cleaner" lub "Find My Blocks". Skanują treść w poszukiwaniu użycia shortcode i bloków. Przydatne przed dezaktywacją wtyczki, aby zobaczyć, jak szeroko są używane jej shortcody.

Co z bezpieczeństwem?

Same shortcody nie są niebezpieczne; pytanie brzmi, co robi handler z atrybutami. Dwa modele zagrożeń:

• Niezaufany użytkownik przesyła treść zawierającą shortcody. Jeśli współtwórca lub subskrybent może przesyłać wpisy, a shortcode uruchamia kod po stronie serwera (jak [exec command="..."] z wtyczki dev), to jest ścieżka dowolnego wykonania kodu. Rdzeń WordPress domyślnie usuwa shortcody z treści przesłanej przez użytkowników z niskimi uprawnieniami; nie cofaj tej ochrony.
• Atrybuty shortcode są emitowane niebezpiecznie. Źle napisany shortcode może echoować [badge text="..."] prosto na stronę bez escapowania, pozwalając adminowi edytującemu wpis wstrzykiwać tagi skryptu. Trzymaj edycję wpisów tylko dla adminów i zawsze escapuj wartości atrybutów podczas pisania niestandardowych shortcodów.

Co sprawdza InspectWP

Shortcody nie są bezpośrednio częścią raportu bezpieczeństwa lub wydajności InspectWP, ale ich efekty pojawiają się w kilku miejscach. Witryna z shortcodami z dezaktywowanych wtyczek typowo ma znaleziska "zepsutych layoutów" (wyrenderowany tekst zawierający kwadratowe nawiasy). Witryna z ciężkim użyciem shortcode bez cache strony pojawia się jako wolne TTFB. A witryna, na której shortcody Visual Composer lub WPBakery przeciekają do wyrenderowanego HTML (ponieważ page builder jest zepsuty lub dezaktywowany) pojawia się jako błędy renderowania i naruszenia dostępności. Zalecany wzorzec w 2026 to kontynuowanie używania shortcodów z powodów legacy, preferowanie bloków dla nowej treści i okresowy audyt witryny pod kątem shortcodów, których handlery nie są już zarejestrowane.