开始使用
主题是 沙盒化的 Liquid — 仅数据的模板，依据固定的数据契约在服务端渲染。主题交付时 零 JavaScript: 购物车、商品选项和结账均来自平台商务运行时，您的标记以声明式方式与之绑定。
- 下载并解压入门主题。
- 重命名
slug在theme.json. - 编辑板块，位于
sections/; 添加代码片段，位于snippets/. - 将文件夹内容打包为 zip 并提交审核。
包结构
mytheme.zip
├── theme.json # manifest (data, never code)
├── templates/index.json # OS 2.0 sectioned template (or index.liquid single-file)
├── sections/*.liquid # section files, each with its schema block
├── snippets/*.liquid # reusable partials for the render tag
├── config/settings_schema.json # theme-level settings (Shopify-style groups)
├── locales/en.json … # theme strings for the t filter
├── assets/ # css / images / fonts — static only
└── preview.png # listing screenshot上限： 10 MB 邮编 2 MB 每个文件，文件夹深度 ≤ 3。允许的文件类型： .liquid .json .css .png .jpg .jpeg .webp .svg .woff2.
不允许 PHP。不允许 JavaScript。 SVG 中不得包含 script 或 foreignObject。
theme.json 清单
{
"name": "My Theme",
"slug": "my-theme", // letters/numbers/dashes — becomes the install path
"version": "1.0.0", // published versions are immutable; ship updates as new versions
"author": "You",
"description": "…",
"min_platform_version": "2.0"
}模板与板块（OS 2.0）
templates/index.json 列出 板块实例; 每个板块都是一个 Liquid 文件，位于
sections/ 并在一个 schema 区块中携带其设置架构。限制：
≤ 25 个板块 每个模板， ≤ 50 个区块 每个板块。
// templates/index.json
{
"sections": {
"hero": { "type": "hero", "settings": { "heading": "Welcome" } },
"menu": { "type": "menu-grid",
"blocks": { "b1": { "type": "badge", "settings": { "label": "New" } } },
"block_order": ["b1"] }
},
"order": ["hero", "menu"]
}在板块文件内部，您会收到 section.id, section.type,
section.settings.* 和 section.blocks (每个区块：
id / type / settings.*). 设置类型： text, textarea,
color, checkbox, select (选项), range
(最小值/最大值), image_picker.
数据 — Drop 参考
模板可以访问 仅 下方这些属性（由平台的 Drop 类生成——此表格不会与实际脱节）。全局变量：
restaurant, options, settings, menu,
allergies, banners, branches, active_branch,
table, customer, localization, flags,
stats, 和 section 在板块文件内部。其他任何内容都会渲染为空白（并在上传时报错）。
AllergyDrop
id int
image string
title string
BannerDrop
id int
image string
image_url string
link_url string
subtitle string
title string
BlockDrop
id string
settings App\Storefront\Drops\SettingsDrop
type string
BranchDrop
accepts_orders bool
id int
is_open bool
name string
status string
CategoryDrop
id int
image_url string
items array
name string
CustomerDrop
name string
phone string
store_credit float
store_credit_formatted string
ExtraDrop
id int
name string
price float
FlagsDrop
allow_order bool
delivery bool
on_table bool
payment bool
scheduling bool
takeaway bool
ItemDrop
description string
dietary_tags array
extras array
has_variants bool
id int
image string
is_daily_special bool
is_gluten_free bool
is_halal bool
is_popular bool
is_sold_out bool
is_vegan bool
name string
option_groups array
price float
rating float
rating_count int
variants array
LanguageDrop
code string
direction string
name string
LocalizationDrop
currencies array
current App\Storefront\Drops\LanguageDrop
direction string
languages array
MenuDrop
categories array
is_empty bool
items array
OptionGroupDrop
choices array
id int
max_select int
min_select int
name string
required bool
OptionsDrop
allow_call_waiter bool
allow_coupons bool
allow_dietary_filters bool
allow_multi_branch_switch bool
allow_order_scheduling bool
allow_tips bool
currency_code string
currency_pos string
currency_sign string
customer_auth_mode string
delivery_charge float
enable_multi_currency bool
menu_sections string
min_order_value float
open_close_store bool
tax_charge float
tax_label string
whatsapp_number string
RestaurantDrop
address string
color string
cover string
description string
id int
logo string
main_image string
phone string
slug string
sub_title string
title string
SectionDrop
blocks array
id string
settings App\Storefront\Drops\SettingsDrop
type string
SettingsDrop
StatsDrop
scans_today int
TableDrop
id int
table_no string
VariantDrop
id int
name string
price float
过滤器与标签
平台过滤器（外加标准的安全 Liquid 集合——escape、date、where、map、sort、size……）：
media_urlmoneymoney_codettheme_asset
t— 翻译一个键。只读；未知的键会返回该键本身。money/money_code— 以餐厅的货币格式化一个价格。media_url— 餐厅图片 URL：{{ item.image | media_url: 'menu' }}(类型：menu、logo、cover、allergy、banner).theme_asset— 您某个打包资源的 URL：{{ 'css/style.css' | theme_asset }}.
标签 schema (板块设置，会从输出中剥离), render
(按名称的代码片段——您的 snippets/ 目录，仅限于此), commerce (每页发出一次商务运行时). 未知的过滤器/标签会在上传时失败。
商务运行时
Drop {% commerce %} 一次（通常放在模板末尾），然后用 data 属性进行绑定——运行时负责购物车状态、选项面板和结账：
<button data-mb-add="{{ item.id }}">Add</button>
<span data-mb-cart-count></span>
<span data-mb-cart-total></span>
<button data-mb-open-cart>Cart</button>
<button data-mb-call-waiter>Call waiter</button>
<div data-mb-item-sheet-mount hidden></div>
<div data-mb-cart-mount hidden></div>通过其以下方式为运行时 UI 定制外观： .mb-* 类和 CSS 自定义属性
(--mb-sheet-bg, --mb-sheet-ink, --mb-accent).
商家设置
商家会在仪表盘中依据您的架构自定义您的主题。优先级：架构默认值 ← 模板值 ← 商家值。设置独立于主题版本存储，因此 发布更新绝不会抹除商家的自定义设置.
规则与限制
- 否
<script>, 不允许内联事件处理程序，不允许javascript:URL，不允许 iframe——上传时会被拒绝。 - 对用户可见的数据进行转义：
{{ item.name | escape }}. - 渲染受资源限制（输出长度 + 引擎工作量上限）。在运行时失败的板块会被跳过，绝不会出现空白页面；而在上传时它则是一个致命错误。
- 已发布的版本不可变——更新是经过审核的新版本。
- 使用逻辑 CSS 属性 (
inline-size,margin-inline…) — 菜单也会以 RTL 渲染。
