如何在加购时添加自定义属性

解决方案
1

方式一：在商品页表单中添加自定义字段（Online Store / Theme）

如果你在 主题 3.0 中使用 product_form 进行加购，只需在表单中新增 properties[...] 字段即可。
该方式同时支持普通加购与快捷支付流程。

该能力常用于：定制信息、刻字内容、礼品留言、尺码备注等场景。这些数据会作为 line item properties 绑定到购物车中的每一件商品上。

参数说明

  1. name（必填）：自定义属性名称
  2. value：自定义属性值
  3. type（必填）：属性类型，枚举如下：
    • text：文本类型，展示为 name: value
    • picture：图片类型，展示为 name + 缩略图，缩略图可点击放大预览并支持下载（通过 urls 渲染）
    • link：链接类型，展示为 name: value，点击可跳转至 urls 中第一个链接
  4. show（boolean）：是否在前台展示
  5. extInfo：扩展信息字段

主题定制方式

在对应 section（例如 main-product）中，可将原有加购表单扩展为如下结构：

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

  <input type="hidden" name="properties[0].name" value="自定义属性名称" />
  <input type="hidden" name="properties[0].value" value="自定义属性值" />
  <input type="hidden" name="properties[0].type" value="text" />
  <input type="hidden" name="properties[0].show" value="true" />

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

应用扩展方式

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

  • 使用 JS 动态向 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>

方式二：通过 Ajax 加购时传递自定义属性

如果通过 JS 调用 /cart/add 接口，可直接在请求体中携带 properties 参数。
该方式不支持快捷支付流程。

参考文档：
https://developer.shopline.com/zh-hans-cn/docs/ajax-api/cart/add-to-cart

请求示例：

fetch('/cart/add', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    items: [
      {
        id: "123456",        // 变体 ID
        quantity: 1,
        properties: [{
          name: "自定义属性名称",
          value: "自定义属性值",
          type: "text",
          show: true
        }]
      }
    ]
  })
})
.then(response => response.json())
.then(data => {
  console.log('已加购：', data);
});