如何使用 ProductForm 一次加购多个商品

子寒 · 2026 年6 月 15 日 03:14

通过 ProductForm 可以在一次请求中同时加购多个商品，并支持为每个商品附带独立的属性信息。

一、参数结构说明（productList）

关联商品通过 productList[index] 表示，其中：

index 表示商品序号（从 0 开始）
最大支持 0 ~ 49，共 50 个商品
超过 50 个商品（如 productList[50] 起）将不被接收并报错

1. 商品基础字段

字段	说明	示例	类型
`productList[0].id`	第一个关联商品 ID	`18070924256205928247524030`	hidden
`productList[0].quantity`	购买数量（正整数） + `quantity` 必须为正整数 + 非正整数将直接报错	`2`	hidden

2. 商品自定义属性（properties）

每个商品支持独立的属性配置：

productList[0][properties][0] 表示第 0 个商品的第 0 个属性

字段	说明
`name`	属性名称（必填）
`value`	属性值
`type`	属性类型
`show`	是否前台展示
`additional`	扩展字段
`urls`	图片/链接资源
`role_visibility`	可见性控制
`extInfo`	扩展信息

二、主题定制方式

在 product_form 中可直接写入 properties 字段：

{{#product_form product id=block.id }}
  <input type="hidden" name="id" value="{{ current_variant.id }}"/>
  <input type="hidden" required name="quantity" value="1"/>

  <!-- 利用 name 属性的数组嵌套规则（假设这是列表中的第 1 个商品，索引为 0） -->
  <input type="hidden" name="productList[0].id" value="18070924256205928247524030">
  <input type="hidden" name="productList[0].quantity" value="2">
  <!-- properties 也是一个列表/对象，继续向下嵌套 -->
  <input type="hidden" name="productList[0].properties[0].name" value="color">
  <input type="hidden" name="productList[0].properties[0].value" value="red">
  <input type="hidden" name="productList[0].properties[0].type" value="text">
  <input type="hidden" name="productList[0].properties[1].name" value="size">
  <input type="hidden" name="productList[0].properties[1].value" value="L">
  <input type="hidden" name="productList[0].properties[1].type" value="text">

  <!-- 如果有第 2 个商品，只需递增索引（例如：name="productList[1].id"） -->
  <input type="hidden" name="productList[1].id" value="18070924256205928247524555">
  <input type="hidden" name="productList[1].quantity" value="1">

  {{#payment_button/}}
{{/product_form}}

三、应用侧扩展方式

主题生成的 form 可作为基础结构，应用可通过以下方式扩展字段：

使用 JavaScript 向 form 内动态添加 input
通过 form 属性将 input 绑定到指定 form ID

示例 Form 结构：

<form method="post" action="/api/carts/ajax-cart/addSingle.js" id="quick-add-product-form-商品ID"
  class="shopline-product-form productFrom">

  <input type="hidden" name="returnTo" value="/cart">
  <input type="hidden" name="id" value="变体ID">
  <input type="hidden" name="quantity" value="1">

  <button style="margin-bottom:10px;" class="btn btn-primary" type="submit">
    products.product_list.add_to_cart
  </button>

  <div data-shopline="payment-button" class="shopline-payment-button-wrapper"></div>
</form>