WooCommerce: как использовать метод prepare_items для кастомизации списка заказов в админке

Что такое метод prepare_items в WooCommerce и зачем он нужен

Метод prepare_items используется в классах, расширяющих WP_List_Table, для подготовки данных и настроек таблицы в админке WordPress. В WooCommerce список заказов в админке реализован через собственный класс, который наследует WP_List_Table. Кастомизация этого списка позволяет добавить новые колонки, изменить вывод данных или добавить фильтры.

По умолчанию WooCommerce не предоставляет публичных хуков для изменения prepare_items, поэтому для кастомизации нужно создавать свой класс-наследник или использовать хуки для добавления колонок и изменения данных.

Диагностика задачи: почему стандартный список заказов не подходит

Частая задача — добавить в таблицу заказов нестандартные колонки, например, пользовательские поля, метаданные или обработать вывод статусов. Без кастомизации prepare_items это сложно, потому что WooCommerce жестко контролирует отображение.

Диагностика проблемы:

• Отсутствуют необходимые колонки в списке заказов
• Нельзя отфильтровать заказы по кастомным данным
• Нужно изменить пагинацию или количество элементов на странице

Пошаговое решение: создание кастомного класса для списка заказов

1. Создаем наследника WP_List_Table

Пример базового класса с добавлением колонки "Новый Статус":

if ( ! class_exists( 'WP_List_Table' ) ) {
    require_once ABSPATH . 'wp-admin/includes/class-wp-list-table.php';
}

class Custom_WC_Orders_Table extends WP_List_Table {
    public function __construct() {
        parent::__construct([
            'singular' => 'order',
            'plural'   => 'orders',
            'ajax'     => false
        ]);
    }

    public function get_columns() {
        return [
            'cb'          => '<input type="checkbox" />',
            'order_id'    => 'ID заказа',
            'customer'    => 'Покупатель',
            'new_status'  => 'Новый Статус',
            'order_total' => 'Сумма'
        ];
    }

    public function prepare_items() {
        $per_page = 20;
        $current_page = $this->get_pagenum();

        // Получаем заказы с метаполем
        $args = [
            'post_type'      => 'shop_order',
            'posts_per_page' => $per_page,
            'paged'          => $current_page,
        ];

        $query = new WP_Query($args);

        $data = [];
        foreach ($query->posts as $post) {
            $order = wc_get_order($post->ID);
            $new_status = get_post_meta($post->ID, '_my_custom_status', true);
            $data[] = [
                'order_id'    => $post->ID,
                'customer'    => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
                'new_status'  => $new_status ? $new_status : '-',
                'order_total' => $order->get_formatted_order_total(),
            ];
        }

        $this->items = $data;

        $this->set_pagination_args([
            'total_items' => $query->found_posts,
            'per_page'    => $per_page
        ]);
    }

    public function column_default( $item, $column_name ) {
        return $item[ $column_name ] ?? '';
    }

    public function column_cb($item) {
        return '<input type="checkbox" name="order[]" value="' . $item['order_id'] . '" />';
    }
}

2. Выводим таблицу на странице админки

Создаем страницу в админке, где выводим наш список:

add_action('admin_menu', function() {
    add_submenu_page('woocommerce', 'Кастомные заказы', 'Кастомные заказы', 'manage_woocommerce', 'custom-orders', 'render_custom_orders_page');
});

function render_custom_orders_page() {
    $table = new Custom_WC_Orders_Table();
    $table->prepare_items();
    ?>
    <div class="wrap">
        <h1>Кастомный список заказов</h1>
        <form method="post">
            <?php $table->display(); ?>
        </form>
    </div>
    <?php
}

Проверка результата после внедрения

Перейдите в WooCommerce —> Кастомные заказы и убедитесь, что в таблице появились новые колонки, данные загружаются и пагинация работает.

Проверьте, что метаполе _my_custom_status отображается правильно. Для этого можно вручную добавить метаданные к заказу через базу данных или плагин для редактирования метаданных.

Частые ошибки и как их исправить

• Класс WP_List_Table не найден — убедитесь, что подключили class-wp-list-table.php через require_once.
• Пустая таблица или нет данных — проверьте правильность запроса WP_Query, наличие заказов и метаполей.
• Ошибка с пагинацией — проверьте правильность передачи параметра paged и вызова set_pagination_args.
• Колонки не отображаются — убедитесь, что возвращаете массив колонок в методе get_columns, а также реализован метод column_default.

Практические советы по безопасности и производительности

• Используйте prepare_items только для вывода небольших объемов данных — для больших объемов лучше делать AJAX-загрузку и серверную фильтрацию.
• Всегда экранируйте вывод данных в таблице, если добавляете кастомный HTML.
• Проверяйте права доступа пользователя, чтобы случайно не раскрыть данные посторонним.
• Для сложных фильтров используйте WP_Meta_Query или SQL-запросы с подготовленными выражениями.

Сравнение вариантов кастомизации списка заказов