PaymentSummary | ArcBlock

PaymentSummary 元件是任何結帳流程中至關重要的 UI 元素。它提供了訂單的詳細明細，包括所有訂單項目、試用期資訊、質押要求以及最終總金額。它的設計具有響應性，並能適應行動裝置的佈局。

這個元件與 ProductItem 和 ProductDonation 協同工作，以呈現購物車中的每個項目，並處理使用者互動，例如應用交叉銷售或更改數量。

Props

PaymentSummary 元件接受以下 props 以自訂其行為和顯示：

Prop	Type	Required	Description
`items`	`TLineItemExpanded[]`	是	要在摘要中顯示的訂單項目陣列。
`currency`	`TPaymentCurrency`	是	用於格式化金額的貨幣物件。
`trialInDays`	`number`	是	循環訂閱的試用天數。
`billingThreshold`	`number`	是	帳單門檻金額。如果適用，用於質押計算。
`trialEnd`	`number`	否	試用結束時的 Unix 時間戳。會覆寫 `trialInDays`。
`showStaking`	`boolean`	否	若為 `true`，則顯示質押詳細資訊。預設為 `false`。
`onUpsell`	`(from: string, to: string) => void`	否	當使用者接受追加銷售優惠時的回呼函式。
`onDownsell`	`(from: string) => void`	否	當使用者還原追加銷售優惠時的回呼函式。
`onQuantityChange`	`(itemId: string, quantity: number) => void`	否	當項目數量變更時的回呼函式。
`onChangeAmount`	`(itemId: string, amount: string) => void`	否	用於更改自訂金額項目（如捐贈）金額的回呼。
`onApplyCrossSell`	`(crossSellId: string) => void`	否	當使用者新增交叉銷售項目時的回呼函式。
`onCancelCrossSell`	`() => void`	否	當使用者移除交叉銷售項目時的回呼函式。
`checkoutSessionId`	`string`	否	結帳會話的 ID，用於獲取潛在的交叉銷售項目。
`crossSellBehavior`	`string`	否	定義交叉銷售項目的行為（例如：`'required'`）。
`donationSettings`	`DonationSettings`	否	捐贈項目的設定。
`action`	`string`	否	摘要區塊的自訂標題，取代「訂單摘要」。
`completed`	`boolean`	否	若為 `true`，則停用數量調整等互動元素。預設為 `false`。

用法

PaymentSummary 元件應放置在 PaymentProvider 內，通常作為更大型結帳表單的一部分使用。您需要為其提供訂單項目和貨幣資訊。

這是一個如何整合 PaymentSummary 元件的基本範例。

PaymentSummary Example

import React from 'react';
import { PaymentProvider, PaymentSummary } from '@blocklet/payment-react';
import { useSessionContext } from '../hooks/session-context'; // 您的 session context hook

// 用於示範的模擬資料
const mockCurrency = {
  id: 'usd_4573516104843264',
  symbol: '$',
  name: 'USD',
  decimal: 2,
  isDefault: true,
};

const mockItems = [
  {
    id: 'li_1',
    price_id: 'price_1',
    quantity: 1,
    adjustable_quantity: { enabled: true, minimum: 1, maximum: 10 },
    price: {
      id: 'price_1',
      type: 'recurring',
      recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
      unit_amount: '2000',
      product: {
        name: 'Pro Plan',
        images: [],
      },
    },
  },
];

export default function MyCheckoutPage() {
  const { session, connectApi } = useSessionContext();

  const handleQuantityChange = (itemId, newQuantity) => {
    console.log(`Item ${itemId} quantity changed to ${newQuantity}`);
    // 在這裡您通常會更新您的狀態並重新獲取結帳資訊
  };

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <PaymentSummary
        items={mockItems}
        currency={mockCurrency}
        trialInDays={14}
        billingThreshold={0}
        showStaking={true}
        onQuantityChange={handleQuantityChange}
      />
    </PaymentProvider>
  );
}

顯示質押與總計

如果 showStaking 設定為 true，該元件將計算並顯示循環項目所需的質押金額。它會將立即支付的金額與質押所需的金額分開，為使用者提供清晰的財務摘要。最終總額是這些金額的總和。

處理試用期

該元件會向使用者清楚地傳達試用期資訊。透過傳遞 trialInDays 或 trialEnd，總額下方將顯示類似「之後每月 $20.00」的訊息，告知使用者試用結束後的循環收費。

互動功能

數量調整：如果某個項目的 adjustable_quantity.enabled 設定為 true，PaymentSummary（透過其子元件 ProductItem）將呈現增加或減少數量的控制項。修改時會觸發 onQuantityChange 回呼。
追加銷售/降級銷售：對於具有追加銷售設定的產品，會呈現一個開關，讓使用者升級其方案。onUpsell 和 onDownsell 回呼會處理這些操作。
交叉銷售：如果提供了 checkoutSessionId，該元件可以獲取並顯示建議的交叉銷售項目。新增或移除這些項目的按鈕會觸發 onApplyCrossSell 和 onCancelCrossSell 回呼。

行動裝置響應式設計

在行動裝置上，產品列表預設是可折疊的，以節省空間，特別是對於包含許多項目的訂單。使用者可以點擊以展開或折疊列表，在較小的螢幕上提供更簡潔、更友善的使用者體驗。