@blocklet/payment-react/docs/components-ui-payment-summary.zh-TW.md

Reusable react components for payment kit v2

# PaymentSummary

`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` 元件的基本範例。

```tsx PaymentSummary Example icon=lucide:shopping-cart
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` 回呼。

### 行動裝置響應式設計

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