Pobieranie produktów WooCommerce z użyciem WP_Query: przykłady i pułapki

WP_Query nadaje się do niestandardowej listy, gdy widok korzysta z modelu wpisów WordPressa i nie ma zastępować katalogu sklepu. Produkt WooCommerce jest typem wpisu `product`, ale archiwum sklepu obsługuje też własne reguły widoczności, filtrowania i paginacji.

Dokumentacja WooCommerce zaleca `wc_get_products()` lub `WC_Product_Query` do pobierania produktów w kodzie motywów i rozszerzeń. Własne zapytanie `WP_Query` może wymagać zmian, gdy sposób przechowywania danych produktów zostanie zmodyfikowany.

Tabela pokazuje, kiedy użyć poszczególnych interfejsów. Wybór zależy od tego, czy potrzebujesz wpisów WordPressa, czy obiektów produktów zgodnych z API WooCommerce.

WP_Query sprawdza się w kontrolowanym widoku, a API WooCommerce jest właściwym wyborem dla nowego kodu, który pobiera katalog.

Podstawowe zapytanie pobiera produkty przez `post_type` ustawione na `product`, ogranicza status do `publish` i ustawia limit wyników. Pętla wywołuje `the_post()`, a po jej zakończeniu przywraca kontekst strony.

$args = array(
    'post_type'      => 'product',
    'post_status'    => 'publish',
    'posts_per_page' => 12,
    'paged'          => max( 1, get_query_var( 'paged' ) ),
);

$products_query = new WP_Query( $args );

if ( $products_query->have_posts() ) {
    while ( $products_query->have_posts() ) {
        $products_query->the_post();

        $product = wc_get_product( get_the_ID() );
        if ( ! $product ) {
            continue;
        }

        echo '<h2>' . esc_html( $product->get_name() ) . '</h2>';
    }
}

wp_reset_postdata();

`wc_get_product()` może nie zwrócić obiektu, dlatego kod sprawdza wynik przed odczytaniem danych. `esc_html()` zabezpiecza tekst w HTML, a `wp_reset_postdata()` przywraca globalny kontekst głównego zapytania. Jeśli lista ma zastąpić lub uzupełnić katalog sklepu, sklepy internetowe na WooCommerce możemy zaprojektować z uwzględnieniem katalogu, filtrów i sposobu wyświetlania produktów.

Kategorię i tag produktu filtruje się przez `tax_query`, a wybrane metadane przez `meta_query`. Filtrowanie ceny oraz stanu magazynowego wymaga sprawdzenia sposobu przechowywania danych i konfiguracji sklepu.

Tabela pokazuje, jak dobrać warunek i co może ograniczyć wynik zapytania. Przy dużym katalogu zmierz koszt zapytania po metadanych na kopii sklepu z danymi podobnymi do produkcyjnych.

Przykład filtrowania kategorii po slugu:

$args = array(
    'post_type'      => 'product',
    'post_status'    => 'publish',
    'posts_per_page' => 12,
    'tax_query'      => array(
        array(
            'taxonomy' => 'product_cat',
            'field'    => 'slug',
            'terms'    => 'akcesoria',
        ),
    ),
);

$products_query = new WP_Query( $args );

Nie kopiuj warunku ceny ani dostępności bez sprawdzenia wersji WooCommerce i konfiguracji katalogu. Dokumentacja WordPressa opisuje `tax_query` jako sposób filtrowania po taksonomiach, a `meta_query` jako warunek dla metadanych wpisów.

Dane produktu odczytuj przez metody obiektu `WC_Product`, który zwraca `wc_get_product()`. Obiekt udostępnia nazwę, cenę, adres produktu i dostępność, a metody WooCommerce uwzględniają typ produktu.

$product = wc_get_product( get_the_ID() );

if ( $product ) {
    $name      = $product->get_name();
    $price     = $product->get_price_html();
    $url       = $product->get_permalink();
    $available = $product->is_in_stock();

    echo '<a href="' . esc_url( $url ) . '">';
    echo esc_html( $name );
    echo '</a>';
    echo wp_kses_post( $price );
    echo $available ? 'Produkt dostępny' : 'Produkt niedostępny';
}

Adres przekazuj przez `esc_url()`, tekst przez `esc_html()`, a HTML ceny przez `wp_kses_post()`, ponieważ format ceny może zawierać znaczniki. Nie zakładaj, że każdy wynik ma cenę lub jest dostępny. Dla produktu wariantowego ustal, czy widok ma pokazać produkt nadrzędny, czy konkretne warianty.

Paginację własnego zapytania obsługuje argument `paged`, a po pętli przywraca się kontekst funkcją `wp_reset_postdata()`. Wartość `paged` powinna odpowiadać numerowi strony dla danego widoku.

Na archiwum sklepu nie duplikuj głównego zapytania tylko po to, by wyświetlić produkty. Dodatkowa pętla może mieć oddzielną paginację, ale wtedy trzeba utrzymać spójne adresy stron oraz liczbę stron wyników. Najpierw sprawdź, czy główne archiwum nie dostarcza już właściwych produktów.

`wp_reset_postdata()` przywraca kontekst wpisu po dodatkowej pętli. Bez resetu tytuł, link lub inny tag szablonu może pobrać dane ostatniego produktu zamiast bieżącej strony.

Użyj `WC_Product_Query` albo `wc_get_products()`, gdy nowy kod motywu lub rozszerzenia ma pobierać katalog przez API WooCommerce. Dokumentacja WooCommerce wskazuje te interfejsy jako odporniejsze na zmiany sposobu przechowywania danych.

$products = wc_get_products( array(
    'status'   => 'publish',
    'limit'    => 12,
    'category' => array( 'akcesoria' ),
    'return'   => 'objects',
) );

foreach ( $products as $product ) {
    echo esc_html( $product->get_name() );
}

`wc_get_products()` jest skrótem do pobierania wyników przez `WC_Product_Query`. Argumenty obejmują między innymi limit, kategorię, tag, status i typ zwracanych danych. Przed wdrożeniem sprawdź dokumentację używanej wersji WooCommerce, ponieważ dostępne kryteria mogą się różnić między wersjami.

Ograniczenie liczby wyników i unikanie kosztownych filtrów metadanych zmniejsza ryzyko wolnych zapytań. Duży katalog testuj na stagingu, czyli kopii sklepu przeznaczonej do sprawdzania zmian przed wdrożeniem.

Zalecamy sprawdzić następujące elementy:
- ustaw limit wyników i paginację zamiast pobierać cały katalog;
- nie uruchamiaj drugiego zapytania katalogowego, jeśli główne archiwum już dostarcza potrzebne produkty;
- ogranicz `meta_query`, zwłaszcza dla pól bez indeksu;
- używaj metod `WC_Product` do wyświetlania ceny i dostępności;
- sprawdź produkty proste, wariantowe i ukryte z katalogu;
- po aktualizacji WooCommerce przetestuj własne rozszerzenie na kopii sklepu.

Jeśli potrzebujesz architektury sklepu uwzględniającej własne widoki katalogu i logikę zapytań, projekt i wdrożenie sklepu WooCommerce możemy dopasować do struktury produktów oraz procesów sprzedaży.

Diagnostykę pustych lub niepełnych wyników zacznij od statusu, kategorii, widoczności katalogowej i numeru strony. Produkt może mieć status opublikowany, a mimo to nie być widoczny w katalogu lub w danym języku sklepu.

1. Sprawdź `post_type` i `post_status`, a następnie potwierdź status testowego produktu.
2. Usuń na chwilę `tax_query` i `meta_query`, aby ustalić, czy wynik odcina warunek.
3. Zweryfikuj slug kategorii, przypisanie produktu i widoczność katalogową.
4. Ustaw małą wartość `posts_per_page` i sprawdź `paged` na kolejnej stronie.
5. Przetestuj osobno produkt prosty i wariantowy, a wyniki porównaj z panelem sklepu.
6. Jeśli sklep działa w kilku językach, sprawdź konfigurację wtyczki wielojęzycznej.

Z naszych wdrożeń wynika, że dodawanie warunków pojedynczo szybciej wskazuje przyczynę pustych wyników niż jednoczesna zmiana wielu argumentów. Przy filtrowaniu katalogu sprawdź także zasady filtrowania produktów WooCommerce, aby własne zapytanie nie omijało logiki sklepu. Szerszy opis typów i wariantów zawiera przewodnik o produktach WooCommerce i ich konfiguracji.

• Ile produktów wyświetlać na stronie sklepu WooCommerce?
• WooCommerce filter shortcode: jak osadzić filtr produktów w sklepie
• Jak wyświetlić podkategorie nad listą produktów w WooCommerce
• Jak wyświetlić kolekcję produktów na stronie głównej sklepu WooCommerce