@blocklet/payment-react
Version:
Reusable react components for payment kit v2
163 lines (125 loc) • 9.77 kB
Markdown
`CheckoutForm`コンポーネントは、支払いリンクとチェックアウトセッションを処理するための主要なエントリーポイントです。提供されたIDに基づいて必要なすべてのデータを取得し、適切な支払いまたは寄付インターフェースをレンダリングする高レベルのラッパーとして機能します。このコンポーネントは、完全なチェックアウトフローをアプリケーションに統合する最も簡単な方法です。
`CheckoutForm`またはその親コンポーネントを`PaymentProvider`でラップして、セッション情報やAPI設定などの必要なコンテキストにアクセスできるようにすることが不可欠です。詳細については、[PaymentProviderのドキュメント](./providers-payment-provider.md)を参照してください。
コンポーネントは、チェックアウトプロセス全体を調整します：
1. **初期化**: `paymentLink` ID（`plink_`で始まる）または`checkoutSession` ID（`cs_`で始まる）でマウントされます。
2. **データ取得**: 支払いバックエンドと通信して、支払い方法、ラインアイテム、顧客詳細など、必要なすべてのコンテキストを取得します。
3. **UIレンダリング**: `formType` propに基づいて、内部で標準の`Payment`コンポーネントまたは特化した`DonationForm`コンポーネントをレンダリングします。
4. **状態管理**: 読み込み状態、完了ステータス、エラーハンドリングなど、支払いのライフサイクル全体を処理します。
```d2 Basic Flow of CheckoutForm icon=lucide:workflow
direction: down
shape: sequence_diagram
User-Action: {
shape: c4-person
label: "ユーザー"
}
Application: {
label: "あなたのReactアプリケーション"
CheckoutForm-Component: {
label: "CheckoutForm"
}
Payment-Component: {
label: "Paymentコンポーネント"
}
Donation-Component: {
label: "DonationFormコンポーネント"
}
}
Payment-API: {
label: "支払いバックエンドAPI"
shape: cylinder
}
User-Action -> Application.CheckoutForm-Component: "1. 'id' propでマウント"
Application.CheckoutForm-Component -> Payment-API: "2. セッションデータを取得"
Payment-API -> Application.CheckoutForm-Component: "3. チェックアウトコンテキストを返す"
alt "formTypeが'payment'の場合" {
Application.CheckoutForm-Component -> Application.Payment-Component: "4. Payment UIをレンダリング"
}
alt "formTypeが'donation'の場合" {
Application.CheckoutForm-Component -> Application.Donation-Component: "5. Donation UIをレンダリング"
}
User-Action -> Application.Payment-Component: "6. 支払いを完了"
User-Action -> Application.Donation-Component: "7. 寄付を完了"
```
`CheckoutForm`コンポーネントは、次のpropsを受け入れます：
| Prop | Type | 必須 | デフォルト | 説明 |
|---------------|----------------------------------------------------------------------------|----------|---------------|-------------------------------------------------------------------------------------------------------------------------|
| `id` | `string` | はい | - | 支払いリンク（`plink_...`）またはチェックアウトセッション（`cs_...`）の一意の識別子。 |
| `mode` | `'standalone'` \| `'inline'` \| `'popup'` \| `'inline-minimal'` \| `'popup-minimal'` | いいえ | `'inline'` | レンダリングモードを定義します。`'standalone'`はフルページビュー用、`'inline'`はコンテナに埋め込む用です。 |
| `formType` | `'payment'` \| `'donation'` | いいえ | `'payment'` | レンダリングするフォームのタイプを決定します。特化した寄付フローには`'donation'`を使用します。 |
| `onPaid` | `(res: CheckoutContext) => void` | いいえ | - | 支払いが成功したときに実行されるコールバック関数。最終的なチェックアウトコンテキストを引数として受け取ります。 |
| `onError` | `(err: Error) => void` | いいえ | `console.error` | プロセス中にエラーが発生したときに実行されるコールバック関数。 |
| `onChange` | `(data: CheckoutFormData) => void` | いいえ | - | いずれかのフォームフィールドの値が変更されたときに発行されるコールバック関数。 |
| `goBack` | `() => void` | いいえ | - | 提供された場合、戻るボタンをレンダリングし、クリックされたときにこの関数を呼び出します。 |
| `extraParams` | `Record<string, any>` | いいえ | `{}` | 支払いリンクからセッションを開始する際にURLで渡される追加パラメータのオブジェクト。 |
| `theme` | `'default'` \| `'inherit'` \| `PaymentThemeOptions` | いいえ | `'default'` | コンポーネントのテーマを制御します。`'inherit'`は親テーマを使用するか、カスタムテーマオブジェクトを渡すことができます。 |
| `action` | `string` | いいえ | `''` | ボタンのテキストなどのUI要素をカスタマイズしたり、特定のフローを追跡したりするために使用される文字列識別子。 |
これは、支払いフォームをアプリケーションのUI内に直接埋め込む最も一般的なユースケースです。コンポーネントが内部ですべてのロジックを処理します。
```tsx MyStorePage.tsx icon=lucide:shopping-cart
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context'; // アプリのセッションフック
export default function MyStorePage() {
const { session, connectApi } = useSessionContext();
const handlePaymentSuccess = (result) => {
console.log('支払いが成功しました！', result);
alert('ご購入ありがとうございます！');
};
const handlePaymentError = (error) => {
console.error('支払いが失敗しました:', error);
alert('申し訳ありませんが、支払いを処理できませんでした。');
};
return (
<PaymentProvider session={session} connectApi={connectApi}>
<div style={{ maxWidth: '960px', margin: '0 auto' }}>
<h1>Checkout</h1>
<CheckoutForm
id="plink_xxxxxxxxxxxxxx" // あなたの支払いリンクIDに置き換えてください
mode="inline"
onPaid={handlePaymentSuccess}
onError={handlePaymentError}
/>
</div>
</PaymentProvider>
);
}
```
`mode="standalone"`を使用すると、専用のフルページチェックアウトエクスペリエンスをレンダリングできます。これは、ユーザーを別のページにリダイレクトして支払いを完了させるシナリオに最適です。
```tsx CheckoutPage.tsx icon=lucide:layout-template
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';
export default function CheckoutPage() {
const { session, connectApi } = useSessionContext();
const paymentLinkId = 'plink_xxxxxxxxxxxxxx'; // URLパラメータから取得可能
return (
<PaymentProvider session={session} connectApi={connectApi}>
<CheckoutForm id={paymentLinkId} mode="standalone" />
</PaymentProvider>
);
}
```
`formType="donation"`を設定することで、コンポーネントは寄付キャンペーンに特化したUIをレンダリングします。これには、金額のプリセットや特典の表示などの機能が含まれます。
```tsx DonationPage.tsx icon=lucide:gift
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';
export default function DonationPage() {
const { session, connectApi } = useSessionContext();
return (
<PaymentProvider session={session} connectApi={connectApi}>
<div style={{ padding: '2rem' }}>
<h2>Support Our Cause</h2>
<CheckoutForm
id="plink_yyyyyyyyyyyyyy" // あなたの寄付リンクIDに置き換えてください
formType="donation"
onPaid={() => alert('寛大なご寄付ありがとうございます！')}
/>
</div>
</PaymentProvider>
);
}
```