@blocklet/payment-react 1.20.16 → 1.20.17

package/docs/components-checkout-checkout-donate.zh.md

@@ -0,0 +1,259 @@
+# CheckoutDonate
+
+`CheckoutDonate` 组件为您的应用程序添加捐赠功能提供了一个灵活且易于集成的解决方案。它支持多种显示模式，从一个简单的打开结账对话框的按钮，到一个由您完全控制的自定义 UI。
+
+该组件必须同时包装在 `PaymentProvider` 和 `DonateProvider` 中才能正常工作。`DonateProvider` 管理应用程序特定范围内的捐赠实例的设置和状态。
+
+## 工作原理
+
+捐赠流程由 `DonateProvider` 和 `CheckoutDonate` 共同协调。以下是其高级概述：
+
+```d2 工作原理 icon=graph-ql:diagram
+direction: down
+
+user: {
+  shape: c4-person
+}
+
+app: {
+  label: "您的 React 应用"
+  
+  checkout-donate: {
+    label: "CheckoutDonate"
+  }
+  
+  checkout-form: {
+    label: "CheckoutForm（在对话框中）"
+  }
+}
+
+payment-api: {
+  label: "支付后端 API"
+  shape: cylinder
+}
+
+# 初始加载
+app.checkout-donate -> payment-api: "获取设置和支持者"
+
+# 捐赠流程
+user -> app.checkout-donate: "1. 点击捐赠"
+app.checkout-donate -> app.checkout-form: "2. 打开带有 CheckoutForm 的对话框"
+app.checkout-form -> payment-api: "3. 处理支付"
+payment-api -> app.checkout-form: "4. 返回成功"
+app.checkout-form -> app.checkout-donate: "5. 触发 onPaid 回调"
+app.checkout-donate -> payment-api: "6. 重新获取支持者列表"
+payment-api -> app.checkout-donate: "7. 返回更新后的支持者"
+```
+
+1.  **初始化**：`DonateProvider` 从后端获取并缓存捐赠设置（如预设金额、按钮文本），这些设置由唯一的 `mountLocation` 标识。
+2.  **渲染**：`CheckoutDonate` 根据检索到的设置及其 props 渲染一个按钮或自定义 UI。
+3.  **交互**：当用户发起捐赠时，`CheckoutDonate` 会打开一个包含为该捐赠预先配置好的 `CheckoutForm` 的对话框。
+4.  **支付**：用户通过 `CheckoutForm` 完成支付。
+5.  **确认**：支付成功后，将触发 `onPaid` 回调，并且组件会自动刷新支持者列表。
+
+## Provider 设置
+
+在使用 `CheckoutDonate` 之前，您必须使用 `PaymentProvider` 和 `DonateProvider` 包装您的组件树。
+
+```tsx Provider 设置示例 icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 你的会话上下文钩子
+
+function DonationPage() {
+  const { session, connect } = useSessionContext();
+
+  // 确保在渲染 provider 之前已加载会话
+  if (!session) {
+    return <div>加载中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="unique-page-identifier" // 此捐赠上下文的唯一键
+        description="为我的精彩博客文章捐赠"
+        defaultSettings={{
+          btnText: '支持我',
+        }}>
+        {/* 你的 CheckoutDonate 组件放在这里 */}
+        <CheckoutDonate 
+          settings={{
+            target: "post-123",
+            title: "支持作者",
+            description: "如果您觉得这篇文章有帮助，可以请我喝杯咖啡",
+            reference: "https://your-site.com/posts/123",
+            beneficiaries: [
+              {
+                address: "z2qa...",
+                share: "100",
+              },
+            ],
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+更多详情，请参阅 [`DonateProvider`](./providers-donate-provider.md) 文档。
+
+## 组件属性
+
+### `DonateProps`
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `settings` | `CheckoutDonateSettings` | **必需。** 此特定捐赠实例的配置。 |
+| `onPaid` | `(session) => void` | 可选。支付成功后执行的回调函数。 |
+| `onError` | `(error) => void` | 可选。发生错误时执行的回调函数。 |
+| `mode` | `'default' \| 'inline' \| 'custom'` | 可选。渲染模式。默认为 `'default'`。 |
+| `livemode` | `boolean` | 可选。覆盖来自 `PaymentProvider` 的 `livemode`。 |
+| `timeout` | `number` | 可选。支付后等待关闭对话框的毫秒数。默认为 `5000`。 |
+| `theme` | `'default' \| 'inherit' \| object` | 可选。主题自定义选项。请参阅 [Theming](./guides-theming.md) 指南。 |
+| `children` | `(openDialog, donateTotalAmount, supporters, loading, donateSettings) => React.ReactNode` | 可选。仅在 `mode="custom"` 时使用的渲染属性函数。 |
+
+### `CheckoutDonateSettings`
+
+此对象传递给 `settings` 属性，并定义了捐赠的核心细节。
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `target` | `string` | **必需。** 捐赠目标的唯一标识符（例如，帖子 ID、项目名称）。 |
+| `title` | `string` | **必需。** 显示在捐赠对话框顶部的标题。 |
+| `description` | `string` | **必需。** 显示在捐赠对话框中的简短描述。 |
+| `reference` | `string` | **必需。** 与捐赠相关的 URL，用于参考。 |
+| `beneficiaries` | `PaymentBeneficiary[]` | **必需。** 定义资金接收者的对象数组。每个对象需要一个 `address`（收款人的 DID）和 `share`（百分比）。 |
+| `amount` | `object` | 可选。配置捐赠金额，包括 `presets`（例如，`['1', '5', '10']`）、默认的 `preset`、`minimum`、`maximum`，以及是否允许 `custom` 金额。 |
+| `appearance` | `object` | 可选。自定义外观和感觉，包括 `button`（文本、图标、变体）和 `history` 显示（`'avatar'` 或 `'table'`）。 |
+
+## 用法示例
+
+### 默认模式
+
+这是使用 `CheckoutDonate` 的最简单方法。它会渲染一个打开捐赠对话框的按钮，以及近期支持者的摘要。
+
+```tsx 默认捐赠按钮 icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+
+function App() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>加载会话中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="为博客文章 123 捐赠"
+        defaultSettings={{
+          btnText: '请我喝杯咖啡',
+          historyType: 'avatar',
+        }}>
+        <CheckoutDonate
+          settings={{
+            target: 'post-123',
+            title: '支持作者',
+            description: '如果您觉得这篇文章有帮助，可以考虑小额捐赠。',
+            reference: 'https://example.com/posts/123',
+            beneficiaries: [
+              {
+                address: 'z2qa...gCLd', // 作者的 DID 地址
+                share: '100',
+              },
+            ],
+          }}
+          onPaid={() => {
+            console.log('捐赠成功！');
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+### 自定义 UI 模式
+
+要完全控制用户界面，请使用 `mode="custom"` 并提供一个渲染属性作为 `children`。此函数让您能够访问捐赠状态，包括筹集到的总金额和支持者列表，从而允许您构建一个完全自定义的显示。
+
+```tsx 自定义捐赠 UI icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+import { CircularProgress, Button } from '@mui/material';
+
+function CustomDonationDisplay() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>加载会话中...</div>;
+  }
+
+  const donateSettings = {
+    target: 'post-123',
+    title: '支持作者',
+    description: '如果您觉得这篇文章有帮助，可以考虑小额捐赠。',
+    reference: 'https://example.com/posts/123',
+    beneficiaries: [
+      {
+        address: 'z2qa...gCLd', // 作者的 DID 地址
+        share: '100',
+      },
+    ],
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="为博客文章 123 捐赠">
+        <CheckoutDonate mode="custom" settings={donateSettings}>
+          {(openDonate, totalAmount, supporters, loading, settings) => (
+            <div style={{ border: '1px solid #ccc', padding: '16px', borderRadius: '8px' }}>
+              <h2>我们的支持者</h2>
+              <p>总捐赠额：<strong>{totalAmount}</strong></p>
+              <Button variant="contained" onClick={openDonate}>
+                {settings?.appearance?.button?.text || '立即捐赠'}
+              </Button>
+              {loading ? (
+                <CircularProgress style={{ marginTop: '16px' }} />
+              ) : (
+                <ul style={{ listStyle: 'none', padding: 0, marginTop: '16px' }}>
+                  {(supporters.supporters || []).map((supporter) => (
+                    <li key={supporter.id}>
+                      <span>{supporter.customer?.name}</span>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          )}
+        </CheckoutDonate>
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+`children` 函数接收以下参数：
+
+-   `openDonate`：一个手动触发捐赠对话框的函数。
+-   `totalAmount`：格式化后的总捐赠金额字符串（例如，`"125.00 T"`）。
+-   `supporters`：一个 `DonateHistory` 对象，包含 `supporters` 数组和货币信息。
+-   `loading`：一个布尔值，指示是否正在获取支持者数据。
+-   `settings`：解析后的捐赠设置，由 `DonateProvider` 和 props 合并而成。

package/docs/components-checkout-checkout-form.ja.md

@@ -0,0 +1,163 @@
+# CheckoutForm
+
+`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. 寄付を完了"
+
+```
+
+## Props
+
+`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>
+  );
+}
+```

package/docs/components-checkout-checkout-form.zh-TW.md

@@ -0,0 +1,163 @@
+# CheckoutForm
+
+`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: "付款元件"
+  }
+
+  Donation-Component: {
+    label: "捐款表單元件"
+  }
+}
+
+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. 渲染付款 UI"
+}
+
+alt "若 formType 為 'donation'" {
+  Application.CheckoutForm-Component -> Application.Donation-Component: "5. 渲染捐款 UI"
+}
+
+User-Action -> Application.Payment-Component: "6. 完成付款"
+User-Action -> Application.Donation-Component: "7. 完成捐款"
+
+```
+
+## Props
+
+`CheckoutForm` 元件接受以下 props：
+
+| Prop          | Type                                                                       | Required | Default       | Description                                                                                             |
+|---------------|----------------------------------------------------------------------------|----------|---------------|-------------------------------------------------------------------------------------------------------------------------|
+| `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'; // 您應用程式的 session hook
+
+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>結帳</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>支持我們的事業</h2>
+        <CheckoutForm
+          id="plink_yyyyyyyyyyyyyy" // 請替換成您的捐款連結 ID
+          formType="donation"
+          onPaid={() => alert('感謝您的慷慨捐款！')}
+        />
+      </div>
+    </PaymentProvider>
+  );
+}
+```