Checkout Block WooCommerce: как доработать оформление заказа без конфликтов

Checkout Block WooCommerce уже нельзя считать экспериментальной альтернативой старому checkout. Начиная с WooCommerce 8.3 блоки Cart и Checkout стали стандартным вариантом для новых магазинов, при этом существующие проекты могут продолжать работать на старом shortcode. Поэтому одинаковая внешне страница оформления заказа на двух сайтах может иметь совершенно разную техническую архитектуру.

Главная причина конфликтов при доработке — попытка перенести старый PHP-snippet или hook в Checkout Block без проверки. Блоковый checkout использует Store API и JavaScript-расширения, а для дополнительных полей, платежей и части UI существуют отдельные официальные API.

Сначала определите, какой checkout реально работает

До любых правок нужно открыть страницу Checkout в редакторе и проверить её структуру. Если используется блок Checkout, старые инструкции вида «вставьте поле через woocommerce_checkout_fields» могут не решить задачу. На действующем магазине также важно проверить, не оставлен ли классический checkout специально из-за несовместимого платежного или логистического расширения.

Почему старые hooks не переносятся один в один

Классический checkout в значительной степени рендерился PHP-шаблонами. Checkout Block формируется как интерактивное приложение, которое получает и изменяет состояние корзины через Store API. Если задача меняет данные checkout, сначала нужно искать официальный Blocks API; если интерфейс — предусмотренные extension points и JavaScript API.

Дополнительные поля регистрируются через Checkout Fields API

WooCommerce предоставляет отдельный API для дополнительных полей блокового checkout. Поле регистрируется через woocommerce_register_additional_checkout_field(), а его расположение задаётся как contact, address или order.

add_action( 'woocommerce_init', function () {
    woocommerce_register_additional_checkout_field( array(
        'id'       => 'asgroups/company-note',
        'label'    => 'Комментарий для менеджера',
        'location' => 'order',
        'type'     => 'text',
        'required' => false,
    ) );
} );

Для production-кода нужен уникальный namespace в id, корректная валидация и понимание жизненного цикла данных. Поле «ИНН компании» и поле «Комментарий курьеру» относятся к разным бизнес-сущностям, поэтому не стоит складывать всё в одно универсальное поле.

Contact, address и order — не просто визуальные зоны

Выбор location влияет на смысл и хранение данных. Contact подходит для информации о покупателе, address — для данных, связанных с адресом, order — для сведений конкретного заказа. Перед переносом legacy-поля нужно определить, требуется ли показывать его в админке, передавать в CRM, добавлять в письмо, экспортировать в ERP или использовать при расчёте доставки.

Платёжный метод должен поддерживать Blocks

Для front-end интеграции платежного метода WooCommerce Blocks предоставляет реестр, где способ оплаты регистрируется через JavaScript. Официальная документация использует wc.wcBlocksRegistry.registerPaymentMethod и механизм canMakePayment, позволяющий определить доступность метода для текущей корзины.

Серверную часть gateway не всегда нужно переписывать полностью, но если старый плагин выводил iframe, кнопку или дополнительные поля только через legacy hooks, его интерфейс может потребовать отдельной адаптации.

Не маскируйте несовместимость CSS-ом

Если платежный метод не умеет Checkout Block, попытка «вернуть» его стилями или ручной вставкой старого markup не решает регистрацию метода, валидацию и передачу данных. Безопаснее проверить обновление расширения или временно оставить classic checkout, чем рисковать оплатами на production.

Доставка зависит от состояния корзины

Блоковый checkout динамически пересчитывает варианты доставки при изменении адреса, товаров и других данных. Кастомная логика должна учитывать этот цикл. При собственной интеграции нужно тестировать смену страны и региона, индекс, несколько shipping packages, бесплатную доставку, купоны, виртуальные товары и возврат назад после выбора тарифа.

Store API — ключ к диагностике

Checkout Block работает поверх Store API. Корзина, выбранная доставка, адреса и checkout-состояние передаются между браузером и WooCommerce как структурированные данные. Поэтому при сложном баге нужно смотреть не только PHP error log, но и Network/Console в браузере: ошибка Store API часто объясняет бесконечный spinner точнее, чем визуальное сообщение.

CRM, ERP и webhooks не должны зависеть от DOM

Интеграцию надёжнее привязывать к серверному событию после создания заказа и использовать ID заказа как основу идемпотентности. Если CRM нужны дополнительные поля, сначала нужно убедиться, что данные реально сохранены в заказе, и только затем передавать их во внешнюю систему. Сложные сценарии я разбираю в услуге интеграции WordPress с CRM, REST API и webhooks.

Аналитика тоже может сломаться после миграции

Старый скрипт аналитики часто привязан к CSS-селекторам или событиям classic checkout. После перехода на Blocks часть DOM и этапов меняется. Отдельно нужно проверить начало checkout, выбор доставки, выбор оплаты и purchase. Серверный факт заказа при этом остаётся важнее клиентского события.

Безопасный план перехода с classic checkout

1. Инвентаризация. Выписать snippets, шаблоны темы, плагины полей, платежи, доставку, аналитику и CRM.
2. Совместимость. Проверить заявленную поддержку Blocks у каждого критичного расширения.
3. Staging. Выполнять миграцию на копии сайта.
4. Базовый заказ. Сначала добиться успешного checkout без кастомных правок.
5. Поля. Перенести нужные данные через Additional Checkout Fields API.
6. Оплата и доставка. Проверить реальные комбинации gateway и тарифов.
7. Интеграции. Проверить CRM, webhooks, письма и складские процессы.
8. Аналитика. Перепроверить события и purchase tracking.
9. Мобильный тест. Оформить тестовые заказы с телефона и десктопа.
10. Rollback. Иметь понятный способ вернуть старый checkout.

Типовые симптомы неправильной доработки

• поле видно, но значение не сохраняется в заказ;
• payment method исчезает после изменения адреса;
• в Console/Network есть ошибка, а пользователь видит spinner;
• доставка пересчитывается в неверный момент;
• CRM получает заказ дважды;
• аналитика считает purchase при неуспешной оплате;
• classic checkout работает, а Checkout Block ломает часть плагинов;
• кастомный JS зависит от внутренних CSS-классов и ломается после обновления.

Чего не стоит делать

Не стоит копировать случайный snippet из старой статьи и считать задачу закрытой только потому, что поле появилось визуально. Не нужно редактировать код WooCommerce Blocks внутри плагина — обновление сотрёт изменения. И нельзя мигрировать production checkout без тестового заказа через каждый реальный способ оплаты.

Чек-лист приёмки Checkout Block

Когда нужна кастомная разработка

Если задача ограничивается одним простым полем, её можно решить небольшим расширением. Но когда checkout связывает оплату, доставку, B2B-реквизиты, промокоды, CRM и динамические условия, изменения лучше проектировать как единый поток и проверять на staging.

Для существующего магазина подходит доработка WooCommerce, для нового проекта — разработка WooCommerce-магазина. Конкретную задачу можно отправить через форму контактов.