> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Справочник блоков приложений

> Все блоки платформы: аргументы, псевдонимы, что они отрисовывают, поведение всплывающего окна, выдвижной панели и навигации, а также какие виды тем их поддерживают.

ИИ-агенты получают тот же справочник из MCP тем: инструмент `get_reference` (тема `app_blocks`) и ресурс `papelship://reference/app-blocks`. Редактор кода, `validate` и `save_draft` предупреждают о неизвестных блоках, неизвестных или неверно типизированных аргументах и блоках, которые данный вид темы не поддерживает.

Блоки платформы (`{% app_block %}` / data-app-block): аргументы, поведение, поддержка по видам тем; заблокированные блоки страниц.

```liquid theme={"system"}
{% app_block 'buy_now', product_id: product.id, mode: 'embed' %}
```

```html theme={"system"}
<div data-app-block="buy_now" data-props='{"product_id":"PRODUCT_ID","mode":"embed"}'></div>
```

| Блок | Поведение | liquid | design | code | twin |
| - | - | - | - | - | - |
| `add_to_cart` | выдвижная панель | да | да | да\* | да\* |
| `buy_now` | навигация | да | да | да | да |
| `cart_count` | выдвижная панель | да | да | да\* | да\* |
| `cart_drawer` | выдвижная панель | да | да | да\* | да\* |
| `checkout_button` | навигация | да | да | да | да |
| `currency_selector` | встроенный | да | да | да\* | да\* |
| `language_selector` | навигация | да | да | да | да |
| `newsletter_form` | форма | да | да | да | да |
| `powered_by` | встроенный | да | нет | нет | нет |
| `quick_view` | диалог | да | да | да | да |
| `recently_viewed` | встроенный | да | да | да\* | да\* |
| `reviews_widget` | встроенный | да | да | нет | нет |
| `variant_picker` | встроенный | да | да | да | да |
| `wishlist_button` | встроенный | да | да | да | да |

`да*`: работает, с примечанием ниже. В секциях кода и выделенных двойниках блоки корзины используют выдвижную панель корзины платформы, а не собственную панель React-темы; значок корзины темы остается синхронизированным.

## add\_to\_cart

Кнопка добавления в корзину для одного товара. Добавляет товар в общую корзину витрины и открывает выдвижную панель корзины. Если у товара несколько вариантов и ни один не выбран, выбор запрашивает variant\_picker рядом с ней, иначе открывается страница товара.

| Аргумент | Тип | Обязателен | Псевдонимы | По умолчанию | Описание |
| - | - | - | - | - | - |
| `product_id` | product | да | `product` | | ID или хеш-ID товара (product.id / product.hash\_id). Также принимается объект товара. |
| `variant_id` | id | | `variant` | | ID варианта; по умолчанию используется вариант, выбранный в variant\_picker рядом, иначе вариант по умолчанию. |
| `quantity` | integer | | | `1` | Количество (1 или больше). |
| `label` | string | | | | Текст кнопки (по умолчанию "Add to cart" с переводом). Игнорируется, если у заполнителя есть собственная разметка. |
| `mode` | enum (`page`, `embed`) | | | | Не действует: add\_to\_cart всегда добавляет в корзину. Для оформления заказа используйте buy\_now. |

## buy\_now

Кнопка покупки в один клик для одного товара. `mode: 'page'` (по умолчанию) ведет на оформление заказа платформы только с этим товаром (корзина сохраняется). `mode: 'embed'` открывает всплывающее окно оформления поверх страницы (iframe платформы; данные карты никогда не попадают в тему) и переходит на страницу, если виджет не удается загрузить.

| Аргумент | Тип | Обязателен | Псевдонимы | По умолчанию | Описание |
| - | - | - | - | - | - |
| `product_id` | product | да | `product` | | ID или хеш-ID товара. Также принимается объект товара. |
| `variant_id` | id | | `variant` | | ID варианта; по умолчанию используется вариант, выбранный в variant\_picker рядом. |
| `quantity` | integer | | | `1` | Количество (1 или больше). |
| `label` | string | | | | Текст кнопки (по умолчанию "Buy now" с переводом). |
| `mode` | enum (`page`, `embed`) | | | `page` | `page` = страница оформления заказа; `embed` = всплывающее окно оформления поверх текущей страницы. |

## cart\_count

Кнопка корзины с количеством товаров ("Cart `<n>`"); ваша собственная разметка сохраняет свой вид, а дочерний элемент `[data-ps-count]` получает число. Нажатие открывает выдвижную панель корзины. Аргументов нет.

## cart\_drawer

Настраивает выдвижную панель корзины (позиции, количества, скидки по акциям, шкала бесплатной доставки, допродажи, оформление заказа). Ничего не отрисовывает на месте; первый `cart_drawer` на странице задает параметры.

| Аргумент | Тип | По умолчанию | Описание |
| - | - | - | - |
| `upsell` | string | | Handle или id коллекции, товары которой предлагаются в панели. |
| `upsell_limit` | integer | `3` | Количество показываемых товаров для допродажи (от 1 до 6). |
| `upsell_heading` | string | | Заголовок блока допродаж (по умолчанию "You may also like"). |
| `free_shipping` | boolean | `true` | `false` скрывает шкалу прогресса бесплатной доставки. |

## checkout\_button

Кнопка оформления заказа для всей корзины (неактивна, пока корзина пуста). `mode: 'page'` (по умолчанию) ведет на `<store>/checkout`; `mode: 'embed'` открывает всплывающее окно оформления; после оплаты корзина очищается.

| Аргумент | Тип | По умолчанию | Описание |
| - | - | - | - |
| `label` | string | | Текст кнопки (по умолчанию "Checkout" с переводом). |
| `mode` | enum (`page`, `embed`) | `page` | Страница оформления заказа или всплывающее окно. |

## currency\_selector

Выбор валюты отображения (скрыт, если валют меньше двух). Сохраняет валюту отображения (оплата всегда списывается в валюте магазина) и генерирует событие `papelship:currency-change`. В секциях кода и двойниках передавайте `currencies`: эти страницы знают только валюту магазина.

| Аргумент | Тип | Описание |
| - | - | - |
| `label` | string | Текст метки. |
| `currencies` | list | Коды валют (`"USD,EUR,TRY"` или массив); по умолчанию валюты отображения магазина. |

## language\_selector

Выбор языка магазина (скрыт, если у магазина один язык). Устанавливает cookie языка и перезагружает страницу. Аргумент: `label`.

## newsletter\_form

Подписка на рассылку с явным флажком согласия. Отправляет данные на эндпоинт лидов платформы; в предпросмотре подписка никогда не оформляется. Аргументы: `label`, `placeholder`, `button`, `consent_text`.

## powered\_by

Подпись "Powered by PapelShip" (скрыта на тарифах, которые позволяют ее скрывать). Только для тем Liquid: страницы дизайнов и подвалы React-тем получают подпись от платформы автоматически.

## quick\_view

Кнопка быстрого просмотра одного товара: открывает диалог с изображениями, ценой, вариантами и кнопкой добавления в корзину. Аргументы: `product_id` (обязательный, псевдоним `product`), `label`.

## recently\_viewed

Недавно просмотренные посетителем товары (из этого браузера); ничего не отрисовывает, если список пуст. Товары записываются на страницах товаров Liquid (страницы товаров React-тем просмотры не записывают). Аргументы: `limit` (по умолчанию 4, от 1 до 20), `heading`.

## reviews\_widget

Опубликованные отзывы: о товаре на страницах товаров, иначе о магазине. Не поддерживается в секциях кода и двойниках (на этих страницах нет данных отзывов; используйте секцию отзывов React-темы). Аргументы: `heading`, `limit` (по умолчанию 5, от 1 до 50), `write` (по умолчанию `true`; `false` скрывает ссылку «написать отзыв»).

## variant\_picker

Выбор варианта (группы переключателей) для одного товара. `add_to_cart` / `buy_now` того же товара в ближайшем общем контейнере (или элементе `data-ps-scope`) используют выбранный вариант; тексты `data-ps` price / compare-price / stock следуют за ним. Аргумент: `product_id` (обязательный, псевдоним `product`).

## wishlist\_button

Переключатель избранного для одного товара (кнопка в виде сердца с `aria-pressed`). Сохраняется в браузере и синхронизируется с аккаунтом клиента после входа. Аргумент: `product_id` (числовой id; хеш-ID не сохраняются в аккаунте).

## Заблокированные блоки страниц

| Блок | Страница | Файл темы Liquid | Файл дизайна |
| - | - | - | - |
| `checkout_form` | Страница оформления заказа | `templates/checkout.liquid` | `pages/checkout.liquid` или `.html` |
| `cart_view` | Страница корзины | `templates/cart.liquid` | `pages/cart.liquid` или `.html` |
| `customer_login` | Страница входа | `templates/customers/login.liquid` | `pages/login.liquid` или `.html` |
| `customer_account` | Страница аккаунта | `templates/customers/account.liquid` | `pages/account.liquid` или `.html` |
| `order_track` | Страница отслеживания заказа | `templates/customers/track.liquid` | `pages/track.liquid` или `.html` |

Каждый из них работает только один раз, в своем собственном файле переопределения. В пакетах кода React-тем переопределений страниц нет.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.