spz-product-form 商品表单

支持布局: container

何时使用

需要处理商品变体加购、结账等操作时。一般用在商品详情页、快速加购弹窗等。

代码演示

基本用法

组件内必需有一个form元素，所有的商品相关代码都写到表单内。在表单内部使用原生的input、select等控件。
当点击加购/结账按钮时，会获取表单的所有数据来作为请求数据。
当我们需要展示变体选项来供用户选择时，需要使用 spz-variants 组件来实现。

<spz-product-form
  layout="container"
  product-id="c10c000b-470d-4733-8d5a-bd3acf612a8e"
  variant-id="d69a1d5e-bb42-4dc6-b887-bf07936fad76"
  @atcSuccess="add-to-card-success-toast.showToast(content='Added successfully');"
>
  <form>
    <!-- Variants -->
    <spz-variants layout="container" src="script:product-json" manual interference inherit-url-variant>
      <fieldset name="Color">
        <legend class="w-full">
          <span>Color</span>
        </legend>
        <div>
          <label>
            <input type="radio" option="DarkKhaki" name="product-info-variant-Color" value="DarkKhaki">
            <span>DarkKhaki</span>
          </label>
          <label>
            <input type="radio" option="SteelBlue" name="product-info-variant-Color" value="SteelBlue">
            <span>SteelBlue</span>
          </label>
        </div>
      </fieldset>
      <fieldset name="Size">
        <legend class="w-full">
          <span>Size</span>
        </legend>
        <div>
          <label>
            <input type="radio" option="S" name="product-info-variant-Size" value="S">
            <span>S</span>
          </label>
          <label>
            <input type="radio" option="M" name="product-info-variant-Size" value="M">
            <span>M</span>
          </label>
        </div>
      </fieldset>
    </spz-variants>

    <!-- OR: <input type="number" value="1" name="quantity" /> -->
    <spz-quantity
      id="product-info-quantity"
      name="quantity"
      value="1"
      min="1"
      max="12"
      height="40"
      layout="fixed-height"
    ></spz-quantity>

    <button role="addToCart">Add to cart</button>
    <button role="buyNow">BuyNow</button>
  </form>
</spz-product-form>

<script id="product-json" type="application/json">
  {
    "product": "...",
    "selected": "..."
  }
</script>

<spz-toast id="add-to-card-success-toast" layout="nodisplay" hidden>
  <span class="flex justify-between items-center w-full">
    <span role="content"></span>
    <a href="/cart">View cart</a>
  </span>
</spz-toast>

属性

属性名	说明	类型	默认值	是否必需
product-id	商品ID	string	-	是，变体组合(`variantCombination`)模式不需要
variant-id	默认	string	-	是，变体组合(`variantCombination`)模式不需要
buy-now-url	自定义结账的URL	string	`/api/checkout/order`	否
disable-first-change-trigger	存在该属性时初始化不触发productChange事件	-	-	否｜
show-toast	当存在此属性时，商品状态变更、接口异常时会弹出toast提示	-	-	-
loading	当处于等待接口响应过程中时会自动加上此属性	-	-	-
finish	当接口响应后会自动加上此属性	-	-	-
invalid	当表单数据未通过校验时自动加上此属性	-	-	-

其他属性

属性	说明
role="addToCart"	带有该属性的元素作为加购按钮，点击该元素，当前选中的变体组合加入购物车
role="buyNow"	带有该属性的元素作为结账按钮，点击该元素，当前选中的变体组合进行结账

方法

setProduct

更改商品数据。

参数名	说明	类型	是否必需
data	商品数据	Object	是

addToCart

当前选中的商品变体组合加入购物车，不需要参数。

buyNow

当前选中的商品变体组合进行结账，不需要参数。当在变体组合(variantCombination)模式时需要以下参数：

参数名	说明	类型	是否必需
index	当前变体组合的索引，从 `0` 开始	number	是
quantity	当前变体组合要更新的数量	number	否
isFirst	如果值为`true`，当前已有选择的变体组合，不进行结账；否则，进行结账	boolean	否

事件

update

当切换变体组合时该事件会自动触发。event 字符串类型，值为当前状态的提示信息。

productChange

当选择的变体组合或数量有更新时该事件会自动触发。

event 对象数据：

属性名	说明	类型
product	商品原数据	Object
product_id	商品ID	string
variant	当前选中变体的数据	Object
variant_id	当前选中变体的ID	string
selectedValues	已选择的变体组合	Object
quantity	当前选中变体的数量	number
max	当前选中变体可购买的最大库存	number

orderChange

当URL带有 order_id 字段且值不为空时该事件自动触发。

event 对象数据：

属性名	说明	类型
order_id	订单ID	string
order_url	获取订单数据API	string

productInvalid

当结账的变体组合或选中的变体组合不存在时该事件会自动触发。

firstBuyNowSuccess

在变体组合(variantCombination)模式下调用 buyNow 方法、isFirst 参数值为 true、当前没有选中的变体组合时，结账成功后该事件会自动触发。

buyNowSuccess

在变体组合(variantCombination)模式下，isFirst 值为false时，结账成功时该事件会自动触发。event 对象数据为结账URL请求返回的数据。

buyNowError

结账失败时该事件会自动触发。event 对象数据为结账URL请求返回的错误信息。

atcSuccess

加购成功时该事件会自动触发。event 对象数据为变体数据。

atcError

加购失败时该事件会自动触发。event 对象数据为变体数据。

requestStart

请求发起前该事件会自动触发，无数据对象。

requestEnd

请求响应后该事件会自动触发，无数据对象。

AI 摘要（LLM Ready）

组件标识：spz-product-form
用途一句话：处理商品变体加购、结账等操作。
可识别属性条目：3
可识别方法小节：3
可识别事件小节：11
关键属性名（Top）：product-id、variant-id、buy-now-url
关键方法名（Top）：setProduct、addToCart、buyNow
关键事件名（Top）：update、productChange、orderChange、productInvalid、firstBuyNowSuccess、buyNowSuccess
阅读顺序建议：先看「何时使用」与「代码演示」，再核对属性/方法/事件。
关联文档：/guide/actions-and-events/ 、/guide/layouts/

spz-product-form 商品表单#

#何时使用

#代码演示

#基本用法

#属性

#其他属性

#方法

#setProduct

#addToCart

#buyNow

#事件