Transfer a finished site into a Vizen shop

Статус: draft · Служить: GET /docs/transfer · проверенный: 2026-09-12, API и чеков на витрине · владелец: гладиатр API документация

Статический автономный site папка

Для целого multi-page Сайт, размещенный под одним category (type:site), использовать /site-folders/{id} вместо того, чтобы вставлять HTML widget за page. Видишь? /docs/file-storage для upload/release операции, вложенные URL, права и React статические-export маршрутизация. HTML pages обслуживаются в site Папка, одинокая-index Ограничения ниже применяются к встроенным widgets, не самостоятельный site папки; site папки не являются inherit shop chrome.

1.Что вы можете сделать здесь

А. site уже существующий - это HTML/CSS/JS папка, статическая React/Vite export, Figma, Webflow или Tilda export — входит в shop Как есть. Одна папка за page становится одним из level-3 widget; Одна папка становится site скелет (The Skone) layout); header и footer папки становятся chrome widgets; product и category папки становятся шаблонами. Ничто не разрезается на sections, нет path переписывается, Ничто не завернуто в тень DOM Или iframe. Что добавляет платформа, так это page вокруг тебя file (header, footer, тот site's own таблица стилей) и live data §7 говорит, что именно происходит с file; §8 Что такое cannot путешествие.

Каждый шаг ниже plain HTTP: POST /html-documents Для создания document, затем POST /html-documents/{id}/releases/zip?publish=1 с застегнутой папкой, И это весь механизм. Если у вас есть хранилище платформы, backend-3D/tools/html-transfer/transfer.mjs Делает те же звонки в одном Командование — это удобство, а не path.

2. Решать first (вилки)

3. Объекты и где они находятся live

Все, что вы загружаете, является освобождение из одного document; Все, что вы делаете, является связывающий.

Сфера охвата: catalog:read, catalog:write, storage:write; тот role на shop должен быть owner или admin для level 3 (HTML_SCRIPT_ROLE_REQUIRED В противном случае. Флаг сервера для авторизованной разметки включен production.

4.Рецепты - в order Реальный трансфер

Каждый рецепт заканчивается чеком, который это доказывает. "200" здесь ничего не доказывает..

4.1 Инвентаризация

Напишите один стол before тот first звонить:

4.2. key

GET /v1/account/token. contour: "dev" и writes_to_live: false — повторять свободно. contour: "prod" — каждый publish это live: Скажи так: owner Спроси для dev key before тот first освобождение. store.storefront_url Это address Вы откроете; warnings[] Иди к нему. owner стенографический.

4.3 Раскладная папка — site-широкий CSS, шрифты, favicon, сценарий

curl -s -H "Authorization: Bearer $VZ" $API/content-blocks \
  | jq '[.result[] | select(.group_type=="theme") | {id,name}] | sort_by(.id)'   # earliest = default
node backend-3D/tools/html-transfer/transfer.mjs ./theme --theme <id>

index.html Вот это скелет: <head> nodes Земля в head каждого page, тот <body> class на page корень, body content before </body>; *.css голый html/body/:root сфера применения .vz-theme-{doc}; icon.png генерирует favicon set. Сценарии читать window.VZ_THEME_BASE. Полная папка правила: /docs/own-markup §7.2.

Проверить: GET /themes/<id>/site ответы base и scope_class; Открыть любой page И найти class="… vz-theme-{doc}" на page Корень и ваш стиль в <head>.

4.4 Заголовок и footer

node backend-3D/tools/html-transfer/transfer.mjs ./header --name "Header"   # prints: создан HTML-проект #<doc>
node backend-3D/tools/html-transfer/transfer.mjs ./footer --name "Footer"

Без --page Командование создает document и публикует релиз; После этого три звонка на одну часть: html block (§3), то group (group_type:"chrome", props.widgets:[<block>]), связывающий:

curl -s -X PUT -H "Authorization: Bearer $VZ" -H 'Content-Type: application/json' \
  $API/design/bindings/shop/0 -d '{"slots":{"header":<G_header>,"footer":<G_footer>}}'
# one section only: /design/bindings/category/<id>; one layout: /design/bindings/theme/<id>

А. sticky header может использовать vz-sticky на корневой узел и сохраняет свое место в поток. position: fixed и absolute Также доступны для намеренного Оверлей; проверьте содержащее block, укладка и content перекрытие.

⚠️ Охраняемые зоны полоса more чем сценарии. Над /cart, /checkout, /account И другой охраняемый pages тот widget Подается в статической mode: тот <script> nodes Иди, и родственник <link rel="stylesheet" href="header.css"> И они идут с ними — header непривлекательные (измеренные на стенде), 2026-09-12). Вводная линия <style> Выжить, и в layout папка's таблица стилей Связанный в page <head> Везде охраняемые зоны, включая и охраняемые. header's CSS в layout папка (§4.3) или вставить ее в <style>; keep тот <link> form для pages только.

Проверить: GET /v1/storefronts/resolve?slug=<shop> → chrome Назовите свои имена Документы; Откройте дом page, а product page и /cart — тот header это Там, на всех трех, на /cart Без своих сценариев и до сих пор стилизован.

4.5 Страницы

curl -s -H "Authorization: Bearer $VZ" "$API/categories/by-slug/home?company_id=<N>"   # 404 = free
curl -s -X POST -H "Authorization: Bearer $VZ" -H 'Content-Type: application/json' $API/categories \
  -d '{"item":{"name":"Home","type":"page","is_published":true,"seo":{"slug":"home"}}}'
node backend-3D/tools/html-transfer/transfer.mjs ./home --page home --validate-only
node backend-3D/tools/html-transfer/transfer.mjs ./home --page home

The first Бег создает document и навесить на block after успешный publish; валидатор error оставляет page Нетронутый. Перезапуск - это new освобождение И только в этом случае files чей sha256 изменился (index.html Изменения в каждом Run — конвертер переписывает его). --doc <id> --list Показать историю, --doc <id> --rollback - Передвигает указатель назад. html blocks на этом page немонтированные (--keep-blocks Держите их).

The page Сохраняет платформу's технический layer выше своего widget — breadcrumbs и page heading — потому что page это category и рисует его сплетенный blocks. Для 1:1 page переключать layer off с помощью page флаги на zone block __page:top (/docs/webcoding §16.1: Создать или обновить с {"kind":"zone","refs":[<your block id>],"page":{"hideSystemBlock":true}} И привяжите его к себе block (PUT /categories/{id}/content-blocks это заменить-set). hideSiteHeader / hideSiteFooter Делайте то же самое для chrome когда page привносит в own. transfer.mjs монтировать block и оставляет после себя Слои, как они есть.

Проверить: Открыть url При этом печатается на dev key Это <slug>--dev Хозяин, под owner's Сессия — и ничего не подтверждать Платформа показывает выше вашего first section.

4.6 Продукты и category шаблоны

node backend-3D/tools/html-transfer/transfer.mjs ./product --name "Product template"
# html block → group group_type:"product" with props.widgets:[<block>] → binding:
curl -s -X PUT -H "Authorization: Bearer $VZ" -H 'Content-Type: application/json' \
  $API/design/bindings/category_children/<root category id> -d '{"slots":{"body":<G_product>}}'

category_children И каждый из них product из поддеревьев; /product/<id> это один product. А. category template это group category в slot body; keep Платформа productListing внутри group когда фильтры и paging Нужны — нужны own-разметка feed составляет ≤ 48 rows. Внутри template тот page's product это product ({{ product.name }}, {{ product.price_text }}, product.gallery[].url, product.attributes[]), тот section это category, crumbs и menu Везде есть.

Проверить: Две открытые products — один card Каждый из них – печатный price равные GET /products/{id}; vz-add-to-cart закладывает item в cart.

4.7 Переплетение data

vz-for и vz-if Иди по-другому nodes. Имена и scope fields: GET /docs/vz-keys.json — ан unknown vz- Атрибут удаляется молча.

Проверить: curl <page> | grep '<a real product name>' Найдет его в сыром HTML; Добавить в item Меняет счетчик.

4.8 Проверить и сообщить

• Открытый прямым URL и Кликнуть из другого page из site — два code пути;
• Скриншоты 1440 и 390;
• Консоль: нет ошибок, нет 404 /_html/;
• /cart показать свой header и footer;
• --doc <id> --list показывает active освобождение.

Отчет: ссылки, оба скриншота, что было поднято, что было снято и why, Откат команды.Токен нигде не появляется.

5.Безмолвно ignored

6. Пределы

Коды валидаторов — ошибки: ref.outside, ref.missing, ref.http, file.forbidden, sw.register, hash.mismatch, html.parse; warnings: page.extra, js.assets, head.stripped, form.nohandler; информация: img.large, img.nosize. Источник: internal/api/htmlrelease/validate.go.

7.Контракт на время выполнения — что платформа делает с вашим устройством file

1. обертка. <body class="dark" data-x="1"> становится <div class="vz-body vz-body-{doc} dark" data-x="1" data-vz-base="/_html/{doc}/{rid}/">. Чистая разметка получает то же самое wrapper. Нет никакого .vz-box/.vz-inner вокруг если только props.html.boxed: true. Див сидит в page <main> между тот header и footer.
2. Голова. link, style, script, noscript Сохраняется в a hidden div.vz-head-{doc} before тот body — таблицы стилей load, Сценарий работает; title и meta description Иди к нему. page SEO; все else выпадает.
3. CSS наброски. банальный body, html, :root в <style> и в том, освобождение's .css files Переписывается для .vz-body-{doc}; составные селекторы (body.dark) Остались одни. src, href, srcset, url(), @import Переписывается в widget корень output — тот files сами по себе не являются касаться.
4. Каскад делится. Уровень 3 - это реально page DOM без style изоляция. Витрина магазина's Стиль лист применяется к вашей разметке и он поставляется Tailwind v4 предполетный в @layer base (измеряется в live CSS, 2026-09-12): *{margin:0;padding:0;border:0 solid} · h1,…,h6{font-size:inherit;font-weight:inherit} · a{color:inherit;text-decoration:inherit} · ol,ul,menu{list-style:none} · img,svg,video,canvas{display:block;vertical-align:middle} · img,video{max-width:100%;height:auto} · button,input,select,textarea{font:inherit;background:transparent;border-radius:0} · button{appearance:button}. Твой CSS Неустойчивый и побеждает на равных Специфика, поэтому все, что вы стилизовали явно, выживает; то, что вы оставили на браузерные дефолты — heading sizes, пули, link подчеркивать, button chrome — Перезагрузите корабль. own base Стиль под корнем class. The page шрифт является ui-sans-serif, system-ui 16 х; ваш body { font-family } земля на .vz-body-{doc} Только. Список стилей, связанный с любым level-3 widget достигать тот целое page (тот product card из vezu-vezu Он берет свой шрифт из header's global.css); тот editor Однако, канвас загружает только layout's <head> — site-широкий CSS принадлежит к layout папка (§4.3)).
5. Сценарии. <script> и <link> когда браузер парсирует page. Ссылки вашей разметки открываются без перезагрузки (vz-reload отдавать предпочтение link выходить, /docs/own-markup §4.0. После такого щелчка платформа воссоздает все <script> узлы widget Так что он снова бежит — сделайте второй пробег безвредным; а CustomEvent('vz:navigate', {detail:{path}}) пожары на document after Каждая навигация и after тот first load. Писать code Это работает, когда выполняется прямо сейчас, и-init на vz:navigate. внешний и defer Сценарий не имеет document.currentScript: Читать корень из .vz-body-<id> или window.VZ_ASSETS[<id>]; два widgets на одном page перезаписывать голый window.VZ_ASSET_BASE друг для друга.
6. Охраняемые зоны. Над /cart, /checkout, /account, /wishlist, /orders, /coupons, /deals, /dashboard Ваша разметка и стили render и ваш скрипты — это стертый сервер-side; тот layout's head_html/foot_html есть И не выбрасывается. Переезжая в и из такой page это full перезарядить, так что layout script снова бегает. hidden выживать; data-* делать не — keep "закрытый default" в layout CSS через class или hidden. Счетчики, состояние входа и поиск все еще работают там: это ключи, а не твой script (/docs/own-markup §4.0).
7. Пути. /_html/{doc}/{rid}/… неизменяем и обслуживается байт-за-байт — не переусердствуйте с вашим own images (PNG/JPG из папки являются never посланный в рециркулировать, так size Сама покупай. images написанный как <img src> переписывается на ресивер с srcset; set sizes. Только active релиз подается; старые риды отвечают 404 design.
8. Геометрия. Проверить fixed прикрепление и query-container side Эффекты с использованием /docs/own-markup §7.2. Невключенный level-3 HTML изменениях, main query container; не является ни одним из них, ни одним из visibility rule.
9. Раскладывание папок дельты. Сфера охвата class .vz-theme-{doc} на page корень, реальный <head> теги, window.VZ_THEME_BASE, фавиконы из icon.png — /docs/own-markup §7.2.

якоря: packages/sections/src/sections/SectionHtmlAuthored.tsx, storefront/src/widgets/html/Slot.tsx (hasUnboxedAuthored), storefront/src/lib/render/PageShell.tsx и storefront/src/app/globals.css (vz-has-authored, @import 'tailwindcss'), pkg/htmlrefs/fragment.go (SetBodyBase, наброски), internal/api/catalog/get_html_document_content.go.

8.Копия; Remap · drop

9. Рамочные примечания

• Реакция / Вайт / Следующий. Клиент, отданный SPA корабли, empty index.html И все это он забирает script: нет text Поисковые системы и a page это Выглядит мертвым до тех пор, пока bundle Экспорт статически (SSG или предзаказа, один Путь = одна папка = одна папка widget, base: './' Пути активов являются Роутер, глобальное состояние и data не приносить move — тот shop's data Проходить через vz- ключи или платформа widgets. Сценарии должны начинаться немедленно и вновь-init на vz:navigate. CORS Открыт для localhost, так местный dev Сервер может вызывать API с токеном на preview реальный data; тот опубликованный widget не выдавать content на его own.
• Tailwind в проекте. Составьте его в папку; не load тот CDN Время выполнения. Ваша компиляция. CSS Сидит над платформой's @layer base и побеждает.
• гадость-code, Webflow, экспорт Tilda. Обычные папки. Типичные исправления: активы, которые указывают на export ведущий (download Войдет в их ряды — http:// Отказывается, а <base href> (В любом случае,), jQuery $(document).ready и window.onload (Беги один раз, Re-init на vz:navigate).
• Шрифты. woff2 в page в папке или в layout Ссылка на папку с родственником url() в @font-face; <link rel="preload"> в layout's <head>.
• Изображения. Выпуск files Они будут служить, как они есть, — before загружать. Каталог images Прибытие предварительно нарезанного через scope fields (p.preview).

10.Как это было проверено

• 2026-09-12, live shop vezu-vezu (Компания 14), prod key из owner: GET /v1/account/token; GET /html-documents — 15 документов в трех поколения (level 1 → level 1 → level 3), 31 выпуск в total; тот header document's global.css Стили в стиле product page (h1 вычисленный шрифт Монтсеррат 26 px 700 из header's таблица стилей; а position: fixed железнодорожный измерено 900 × 161 px в 1440 × 900 видопорт и 844 px высотой 390 × 844 (драматург, Хром).
• Живой магазин CSS (/_next/static/chunks/*.css) Для предполетного полета Правила, перечисленные в § 7.4; Tailwind 4.3.2 в разделе vizen-market/node_modules.
• Код читать: SectionHtmlAuthored.tsx, Slot.tsx, PageShell.tsx, globals.css, htmlrefs/fragment.go, htmlrelease/validate.go, tools/html-transfer/transfer.mjs.
• 2026-09-12, стенд local-stand.sh (:3970/:5621), shop proverka-limita-1, стартовый комплект tools/html-transfer/examples/: layout папка (фавиконы) генерируемый), header + footer привязанный к shop, page demo, product template привязанный category_children; Измеряется с помощью playwright-core: fixed рельс 900 px в окошке 900 px, h1 36x от base.css, menu из vz-for, тот widget корень /_html/48/207/ в script's note, /cart с header и footer но без разметки, без header's относительный стиль, page breadcrumbs и heading выше widget до тех пор, пока hideSystemBlock. The document оставаться draft до тех пор, пока owner's first external передача.

11.Отрицания в этом document (rule §3.9)