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

Reusable react components for payment kit v2

# PaymentSummary

`PaymentSummary`コンポーネントは、あらゆるチェックアウトプロセスにとって重要なUI要素です。すべての品目、トライアル期間情報、ステーキング要件、および最終的な合計金額を含む、注文の詳細な内訳を提供します。レスポンシブデザインになっており、モバイルデバイス向けにレイアウトを調整します。

このコンポーネントは`ProductItem`および`ProductDonation`と連携してカート内の各アイテムをレンダリングし、クロスセルの適用や数量の変更などのユーザーインタラクションを処理します。

## Props

`PaymentSummary`コンポーネントは、その動作と表示をカスタマイズするために以下のプロパティを受け入れます:

| 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` | いいえ | "Order Summary"を置き換える、サマリーセクションのカスタムタイトル。 |
| `completed` | `boolean` | いいえ | `true`の場合、数量調整などのインタラクティブな要素を無効にします。デフォルトは`false`です。 |

## Usage

`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'; // セッションコンテキストのフック

// デモ用のモックデータ
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`コールバックをトリガーします。

### モバイルレスポンシブ

モバイルデバイスでは、特に多くのアイテムがある注文の場合、スペースを節約するために製品リストはデフォルトで折りたたみ可能です。ユーザーはタップしてリストを展開または折りたたむことができ、小さな画面でよりクリーンでユーザーフレンドリーな体験を提供します。