> ## 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.

# Дизайны

> Загрузите собственный HTML-сайт как дизайн и подключите его к товарам, корзине и оформлению заказа с помощью Liquid, атрибутов data-ps или JavaScript SDK.

Дизайн это ваш собственный сайт, загруженный в виде ZIP-архива, который PapelShip отдает как витрину вашего магазина. Вы сохраняете полный контроль над разметкой и добавляете торговые функции тремя способами:

1. **Страницы Liquid**: `pages/*.liquid` отрисовываются с данными вашего магазина на сервере.
2. **Атрибуты `data-ps`**: обычный HTML, который PapelShip заполняет данными товаров на сервере.
3. **SDK**: `window.PapelShip` для товаров, корзины и оформления заказа в браузере.

## Пакет

| Путь | Содержимое |
| - | - |
| `pages/*.html`, `pages/*.liquid` | Страницы. Страницы `.html` статичны; страницы `.liquid` отрисовываются с данными магазина. |
| `partials/`, `snippets/` | Общая разметка |
| `assets/`, `media/` | CSS, JavaScript, изображения и шрифты |
| `config/design.json` | Список страниц с путями и SEO, а также ваши настройки |
| `seo/robots.txt`, `seo/sitemap-extra.txt` | Необязательные SEO-файлы |

Каждая страница из `config/design.json` получает свой путь в вашем магазине.

**Шаблоны.** `pages/product.liquid` (или `.html`) является вашей страницей товара, а `pages/shop.liquid` списком товаров магазина. Без них PapelShip показывает нейтральную страницу товара или магазина внутри вашего дизайна.

**Страница не найдена.** Добавьте `pages/404.html` (или `.liquid`) для собственной страницы «не найдено». Она показывается для неизвестных адресов и неизвестных товаров.

## Сканирование и проверка

Каждая загрузка сканируется, прежде чем она может быть опубликована. Код, атакующий клиентов или платформу, блокируется: поля для данных карты, скрытые перенаправления, формы, отправляющие данные на другие сайты, запросы к API PapelShip или другим магазинам, а также вредоносные скрипты. Необычный код сначала отправляется на проверку PapelShip. Исправьте указанные файлы и загрузите снова.

Правки сохраняются как черновики; ваш магазин показывает опубликованную версию. **Опубликовать** сканирует ровно те файлы, которые отправляет в рабочую версию: заблокированный код отменяет публикацию, а находки, требующие проверки, ждут проверки PapelShip (магазин при этом сохраняет текущую версию) и публикуются после одобрения.

## Атрибуты data-ps

Пометьте элементы, и PapelShip заполнит их данными товара на сервере:

```html theme={"system"}
<div data-ps-product="current">
  <img data-ps="image" alt="">
  <h1 data-ps="title"></h1>
  <p><span data-ps="price"></span> <s data-ps="compare-price" data-ps-if="on-sale"></s></p>
  <div data-ps="variants"></div>
  <button data-ps="add" data-ps-if="in-stock">Add to cart</button>
  <span data-ps-if="sold-out">Sold out</span>
</div>
```

### Значения

| `data-ps` | Заполняет |
| - | - |
| `title` | Название товара |
| `price` | Текущая цена |
| `compare-price` | Цена для сравнения |
| `stock` | Метка наличия |
| `rating` | Средний рейтинг |
| `badge` | Значок распродажи или акции |
| `description` | Описание простым текстом |
| `image` | На `<img>`: изображение товара |
| `url` | На `<a>`: ссылка на страницу товара |
| `buy` | Кнопка «Купить сейчас», ведет на оформление заказа |
| `add` | Кнопка «В корзину» |
| `variants` | На `<div>`: выбор варианта. Кнопки добавления и покупки и цена рядом с ним следуют за выбором. |

### Условия

| `data-ps-if` | Элемент остается, только если |
| - | - |
| `on-sale` | Товар продается со скидкой |
| `in-stock` | Товар есть в наличии |
| `sold-out` | Товар распродан |

### Контейнеры

| Атрибут | Назначение |
| - | - |
| `data-ps-products="8"` | Повторяет первый дочерний `<template>` для N товаров (максимум 48) |
| `data-ps-collection` | Ограничивает список коллекцией по ее handle |
| `data-ps-sort` | `featured`, `newest`, `price-asc`, `price-desc`, `best-selling` |
| `data-ps-ids` | ID товаров для отображения через запятую |
| `data-ps-product` | Один товар: id, хеш или `current` в шаблоне товара |

```html theme={"system"}
<div data-ps-products="8" data-ps-sort="newest">
  <template>
    <a data-ps="url"><img data-ps="image" alt=""><span data-ps="title"></span></a>
    <span data-ps="price"></span>
    <button data-ps="add" data-ps-if="in-stock">Add to cart</button>
  </template>
</div>
```

## Страницы Liquid

Страницы `.liquid` используют те же объекты, фильтры и теги, что и темы Liquid, включая `{% app_block %}`. См. [Темы и Liquid](https://developers.papelship.com/ru/themes/liquid.md). Статические экспорты, использующие `{{ }}` для других шаблонизаторов, остаются безопасными: отрисовываются только страницы `.liquid`.

## SDK

> [!NOTE]
>
> SDK загружается только на страницах дизайна, содержащих привязку `data-ps` или заполнитель `data-app-block`. Вызывайте его из обработчика `DOMContentLoaded`. См. [Коммерция и оформление заказа](https://developers.papelship.com/ru/themes/commerce.md).

На этих страницах SDK доступен как `window.PapelShip`.

| Метод | Назначение |
| - | - |
| `products.list({ limit, ids, collection, sort })` | Promise со списком товаров |
| `products.get(id)` | Promise с одним товаром |
| `cart.items`, `cart.count`, `cart.subtotal` | Состояние корзины |
| `cart.add(id, { variantId, quantity })` | Добавляет позицию, возвращает promise |
| `cart.remove`, `cart.update(index, quantity)`, `cart.clear` | Изменяют корзину |
| `cart.open`, `cart.close` | Открывают или закрывают выдвижную панель корзины |
| `cart.on`, `cart.off` | События `change` и `add` (`papelship:cart-change`, `papelship:cart-add`) |
| `price` | Строки цен с примененными акциями |
| `checkout({ products?, mode: 'page' \| 'embed', onPaid? })` | `page` (по умолчанию) переходит на страницу оформления заказа платформы; `embed` открывает всплывающее окно оформления поверх вашей страницы |
| `checkoutInvoice` | Открывает существующий счет |
| `formatMoney(cents, currency)` | Форматирует цену |
| `bind` | Повторно сканирует страницу после добавления разметки |
| `on`, `off` | События `papelship:*` |

```js theme={"system"}
PapelShip.products.list({ limit: 8, sort: 'newest' }).then(function (items) {
  var grid = document.getElementById('grid')
  items.forEach(function (p) {
    var a = document.createElement('a')
    a.href = p.url
    a.textContent = p.title + ' ' + PapelShip.formatMoney(p.price_cents, p.currency)
    grid.appendChild(a)
  })
})
```

## Компоненты

Меню **Вставить компонент** в редакторе кода добавляет готовый редактируемый код: сетку товаров, карточку товара, страницу товара, цену, кнопку покупки, кнопку «В корзину», счетчик корзины, выдвижную панель корзины, встроенное оформление заказа и список коллекций. Нажмите на компонент в предпросмотре, чтобы снова изменить его настройки.

## Страницы магазина

Оформление заказа, корзина, вход, аккаунт и отслеживание заказа отрисовываются внутри вашего дизайна с макетом, который вы выбираете в панели. Чтобы оформить их самостоятельно, добавьте `pages/checkout.liquid`, `pages/cart.liquid`, `pages/login.liquid`, `pages/account.liquid` или `pages/track.liquid` (или `.html`) ровно с одним заблокированным блоком, например `<div data-app-block="checkout_form"></div>`. Блоки перечислены в разделе [Страницы платформы](https://developers.papelship.com/ru/themes/liquid.md#страницы-платформы).

> [!NOTE]
>
> Клиенты всегда платят на странице оформления заказа PapelShip или во встроенном всплывающем окне. Дизайны не могут заменять оформление заказа или собирать данные карт.


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