@blocklet/payment-react 1.20.15 → 1.20.17

package/docs/overview.ja.md

@@ -0,0 +1,80 @@
+# 概要
+
+`@blocklet/payment-react` は、支払いフロー、サブスクリプション、および寄付システムの blocklet への統合を効率化するために設計された、包括的な React コンポーネントライブラリです。[Payment Kit](https://www.arcblock.io/docs/arcblock-payment-kit) を基盤として構築されており、事前に構築済みでカスタマイズ可能、かつ本番環境ですぐに利用できる一連のコンポーネントを提供し、最小限の労力で強力な決済体験を構築するのに役立ちます。
+
+## 主な機能
+
+<x-cards data-columns="3">
+  <x-card data-title="構築済みのUIコンポーネント" data-icon="lucide:layout-template">
+    チェックアウトフォーム、価格表、寄付ウィジェットなど、一般的な決済シナリオをすぐにカバーできる豊富なコンポーネントセットが含まれています。
+  </x-card>
+  <x-card data-title="カスタマイズ可能なテーマ" data-icon="lucide:palette">
+    Material-UI テーマを使用して決済フローの外観を完全に制御し、一貫したユーザーエクスペリエンスを保証します。
+  </x-card>
+  <x-card data-title="i18n サポート" data-icon="lucide:languages">
+    組み込みの国際化サポートにより、グローバルなユーザー向けにコンポーネントのテキストを簡単にローカライズできます。
+  </x-card>
+  <x-card data-title="包括的な決済操作" data-icon="lucide:credit-card">
+    サブスクリプション、返金、請求書管理、従量課金など、複雑な決済ロジックを簡単に処理します。
+  </x-card>
+  <x-card data-title="最適化されたパフォーマンス" data-icon="lucide:package-minus">
+    遅延読み込みと動的コンポーネントインポートの組み込みサポートにより、アプリケーションのバンドルサイズを最適化し、パフォーマンスを向上させます。
+  </x-card>
+</x-cards>
+
+## 仕組み
+
+このライブラリは、プロバイダーコンポーネントモデルを中心に設計されています。`PaymentProvider` はライブラリの中核であり、認証、API通信、状態を管理するコンテキストを作成します。他のすべての決済コンポーネントは、正しく機能するためにこのプロバイダーでラップする必要があります。これにより、決済ロジックが一元化され、個々のコンポーネントは軽量で特定の機能に集中できます。
+
+```d2 高レベルアーキテクチャ
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Your-Application: {
+  label: "あなたのアプリケーション"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    Payment-Components: {
+      label: "決済コンポーネント"
+      shape: rectangle
+      grid-columns: 2
+
+      CheckoutForm: { label: "CheckoutForm" }
+      CheckoutTable: { label: "CheckoutTable" }
+      CheckoutDonate: { label: "CheckoutDonate" }
+      CustomerInvoiceList: { label: "CustomerInvoiceList" }
+    }
+  }
+}
+
+Payment-Kit-Backend: {
+  label: "Payment Kit バックエンド"
+  shape: cylinder
+}
+
+User -> Your-Application.PaymentProvider.Payment-Components: "UIと対話する"
+Your-Application.PaymentProvider -> Payment-Kit-Backend: "API通信を処理する"
+Payment-Kit-Backend -> Your-Application.PaymentProvider: "データを返す"
+Your-Application.PaymentProvider.Payment-Components -> User: "UIの更新をレンダリングする"
+
+```
+
+## 構築できるもの
+
+- **サブスクリプションサービス:** `CheckoutTable` を使用して、SaaS製品の価格ページとチェックアウトフローを迅速に実装します。
+- **Eコマースチェックアウト:** `CheckoutForm` を使用して、商品を販売するための一回限りの支払いフォームを構築します。
+- **寄付システム:** `CheckoutDonate` を使用して、クリエイターや活動を支援するための柔軟な寄付ウィジェットを追加します。
+- **カスタマーポータル:** `CustomerInvoiceList` やその他の履歴コンポーネントを使用して、ユーザーの請求履歴を表示し、支払い方法を管理します。
+
+## 次のステップ
+
+`@blocklet/payment-react` が提供する機能の概要を理解したところで、何かを構築してみることが最善の学習方法です。
+
+[はじめに](./getting-started.md) ガイドを参考にしてライブラリをインストールし、数分で最初の支払いフォームを作成してみましょう。

package/docs/overview.zh-TW.md

@@ -0,0 +1,80 @@
+# 總覽
+
+`@blocklet/payment-react` 是一個全方位的 React 元件庫，旨在簡化將支付流程、訂閱和捐贈系統整合到您的 blocklet 中的過程。它建立在 [Payment Kit](https://www.arcblock.io/docs/arcblock-payment-kit) 的基礎之上，提供了一套預先建置、可自訂且生產就緒的元件，幫助您以最少的精力打造強大的支付體驗。
+
+## 主要功能
+
+<x-cards data-columns="3">
+  <x-card data-title="預先建置的使用者介面元件" data-icon="lucide:layout-template">
+    包含一組豐富的元件，如結帳表單、定價表和捐贈小工具，開箱即用，涵蓋常見的支付情境。
+  </x-card>
+  <x-card data-title="可自訂主題" data-icon="lucide:palette">
+    使用 Material-UI 主題完全控制您的支付流程外觀和風格，確保一致的使用者體驗。
+  </x-card>
+  <x-card data-title="支援 i18n" data-icon="lucide:languages">
+    內建的國際化支援讓您能輕鬆為全球受眾本地化元件文字。
+  </x-card>
+  <x-card data-title="全方位的支付操作" data-icon="lucide:credit-card">
+    輕鬆處理複雜的支付邏輯，包括訂閱、退款、發票管理和計量計費。
+  </x-card>
+  <x-card data-title="最佳化效能" data-icon="lucide:package-minus">
+    透過內建的延遲載入和動態元件匯入支援，最佳化您應用程式的套件大小並提升效能。
+  </x-card>
+</x-cards>
+
+## 運作方式
+
+此函式庫圍繞著提供者-元件模型架構。`PaymentProvider` 是此函式庫的核心，它建立了一個管理身份驗證、API 通訊和狀態的上下文 (context)。所有其他支付元件都必須包裹在此提供者內才能正常運作。這種方式集中了支付邏輯，並使個別元件保持輕量和專注。
+
+```d2 高階架構
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Your-Application: {
+  label: "Your Application"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    Payment-Components: {
+      label: "Payment Components"
+      shape: rectangle
+      grid-columns: 2
+
+      CheckoutForm: { label: "CheckoutForm" }
+      CheckoutTable: { label: "CheckoutTable" }
+      CheckoutDonate: { label: "CheckoutDonate" }
+      CustomerInvoiceList: { label: "CustomerInvoiceList" }
+    }
+  }
+}
+
+Payment-Kit-Backend: {
+  label: "Payment Kit Backend"
+  shape: cylinder
+}
+
+User -> Your-Application.PaymentProvider.Payment-Components: "Interacts with UI"
+Your-Application.PaymentProvider -> Payment-Kit-Backend: "Handles API Communication"
+Payment-Kit-Backend -> Your-Application.PaymentProvider: "Returns Data"
+Your-Application.PaymentProvider.Payment-Components -> User: "Renders UI Updates"
+
+```
+
+## 您可以建立什麼
+
+- **訂閱服務：** 使用 `CheckoutTable` 為 SaaS 產品快速實作定價頁面和結帳流程。
+- **電子商務結帳：** 使用 `CheckoutForm` 為銷售商品建立一次性支付表單。
+- **捐贈系統：** 使用 `CheckoutDonate` 新增靈活的捐贈小工具以支持創作者或公益事業。
+- **客戶入口網站：** 使用 `CustomerInvoiceList` 和其他歷史記錄元件為使用者顯示發票歷史並管理支付方式。
+
+## 下一步
+
+既然您已對 `@blocklet/payment-react` 提供的功能有了大致了解，最好的學習方式就是動手實作。
+
+深入閱讀我們的 [入門指南](./getting-started.md) 來安裝此函式庫，並在幾分鐘內建立您的第一個支付表單。

package/docs/overview.zh.md

@@ -0,0 +1,80 @@
+# 概述
+
+`@blocklet/payment-react` 是一个全面的 React 组件库，旨在简化将支付流程、订阅和捐赠系统集成到您的 Blocklet 中的过程。它基于 [Payment Kit](https://www.arcblock.io/docs/arcblock-payment-kit) 构建，提供了一套预构建、可定制且生产就绪的组件，帮助您以最少的精力构建强大的支付体验。
+
+## 主要特性
+
+<x-cards data-columns="3">
+  <x-card data-title="预构建的 UI 组件" data-icon="lucide:layout-template">
+    包含一组丰富的组件，如结账表单、定价表和捐赠小部件，可开箱即用地覆盖常见的支付场景。
+  </x-card>
+  <x-card data-title="可定制主题" data-icon="lucide:palette">
+    使用 Material-UI 主题完全控制支付流程的外观和感觉，确保一致的用户体验。
+  </x-card>
+  <x-card data-title="i18n 支持" data-icon="lucide:languages">
+    内置的国际化支持使您可以轻松地为全球受众本地化组件文本。
+  </x-card>
+  <x-card data-title="全面的支付操作" data-icon="lucide:credit-card">
+    轻松处理复杂的支付逻辑，包括订阅、退款、发票管理和计量计费。
+  </x-card>
+  <x-card data-title="优化的性能" data-icon="lucide:package-minus">
+    通过内置的懒加载和动态组件导入支持，优化应用程序的包大小并提高性能。
+  </x-card>
+</x-cards>
+
+## 工作原理
+
+该库围绕提供者-组件模型构建。`PaymentProvider` 是该库的核心，它创建了一个管理身份验证、API 通信和状态的上下文。所有其他支付组件都必须在此提供者内包装才能正常工作。这种方式集中了支付逻辑，并使各个组件保持轻量和专注。
+
+```d2 High-Level Architecture
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Your-Application: {
+  label: "你的应用"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    Payment-Components: {
+      label: "支付组件"
+      shape: rectangle
+      grid-columns: 2
+
+      CheckoutForm: { label: "CheckoutForm" }
+      CheckoutTable: { label: "CheckoutTable" }
+      CheckoutDonate: { label: "CheckoutDonate" }
+      CustomerInvoiceList: { label: "CustomerInvoiceList" }
+    }
+  }
+}
+
+Payment-Kit-Backend: {
+  label: "Payment Kit 后端"
+  shape: cylinder
+}
+
+User -> Your-Application.PaymentProvider.Payment-Components: "与 UI 交互"
+Your-Application.PaymentProvider -> Payment-Kit-Backend: "处理 API 通信"
+Payment-Kit-Backend -> Your-Application.PaymentProvider: "返回数据"
+Your-Application.PaymentProvider.Payment-Components -> User: "渲染 UI 更新"
+
+```
+
+## 你可以构建什么
+
+- **订阅服务：** 使用 `CheckoutTable` 为 SaaS 产品快速实现定价页面和结账流程。
+- **电子商务结账：** 使用 `CheckoutForm` 构建用于销售商品的一次性支付表单。
+- **捐赠系统：** 使用 `CheckoutDonate` 添加灵活的捐赠小部件以支持创作者或事业。
+- **客户门户：** 使用 `CustomerInvoiceList` 和其他历史组件为用户显示发票历史和管理支付方式。
+
+## 下一步
+
+现在你已经对 `@blocklet/payment-react` 提供的功能有了大致了解，最好的学习方式就是动手构建一些东西。
+
+深入阅读我们的 [入门指南](./getting-started.md) 来安装该库，并在几分钟内创建你的第一个支付表单。

package/docs/providers-donate-provider.ja.md

@@ -0,0 +1,153 @@
+# DonateProvider
+
+`DonateProvider`は、アプリケーション内のすべての寄付関連コンポーネントの状態と設定を管理する、極めて重要なコンテキストプロバイダーです。バックエンドから設定を取得し、パフォーマンス向上のためにキャッシュし、`CheckoutDonate`などのコンポーネントに提供する役割を担います。
+
+寄付機能を使用するには、コンポーネントを`DonateProvider`でラップする必要があります。また、このプロバイダーは、必要な支払いコンテキストとセッション情報へのアクセスを確保するために、[`PaymentProvider`](./providers-payment-provider.md)内にネストされている必要があります。
+
+## 仕組み
+
+`DonateProvider`は、いくつかの主要な機能を実行します：
+
+1.  **設定の取得**：マウント時に、APIエンドポイントを呼び出して、一意の`mountLocation`プロップに関連付けられた寄付設定を取得します。これらの設定は、子となる寄付コンポーネントの動作を決定します。
+2.  **データのキャッシュ**：パフォーマンスを向上させ、ネットワークリクエストを削減するために、取得した設定は`localStorage`に保存されます。キャッシュは次回以降の読み込みで自動的に使用され、必要に応じて手動でクリアすることもできます。
+3.  **コンテキストの提供**：ReactのContext APIを使用して、設定と制御関数（`refresh`、`updateSettings`）を、それらを必要とするすべての子孫コンポーネントに渡します。
+4.  **寄付の有効化**：管理者ユーザー（'owner'または'admin'）に対して、寄付インスタンスが非アクティブであっても`enableDonate`プロップが設定されている場合、プロバイダーはそれをアクティブ化するためのUIをレンダリングします。
+
+## Props
+
+`DonateProvider`は、その動作を設定するために以下のプロップを受け入れます：
+
+| Prop              | Type                               | Required | Description                                                                                                                              |
+| ----------------- | ---------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `mountLocation`   | `string`                           |   はい    | この特定の寄付インスタンスのための一意の文字列識別子。設定の取得、キャッシュ、更新のキーとして使用されます。        |
+| `description`     | `string`                           |   はい    | システムバックエンドやログでこの寄付インスタンスを識別するのに役立つ、人間が読める形式の説明。                                      |
+| `children`        | `ReactNode`                        |   はい    | プロバイダーの内部でレンダリングされる子コンポーネント。通常は `CheckoutDonate` を含みます。                                       |
+| `defaultSettings` | `DonateConfigSettings`             |    いいえ    | バックエンドで設定が見つからない場合に適用されるデフォルト設定を持つオブジェクト。利用可能なオプションについては、以下の型定義を参照してください。 |
+| `active`          | `boolean`                          |    いいえ    | 寄付インスタンスが最初に作成されるときの初期アクティブ状態を設定します。デフォルトは `true` です。                                   |
+| `enableDonate`    | `boolean`                          |    いいえ    | `true` の場合、管理者ユーザーが現在非アクティブなこの寄付インスタンスをUIから有効にできるようにします。デフォルトは `false` です。               |
+
+### DonateConfigSettings 型
+
+これは `defaultSettings` オブジェクトの形状です：
+
+```typescript DonateConfigSettings type
+export interface DonateConfigSettings {
+  amount?: {
+    presets?: string[]; // 例：['1', '5', '10']
+    preset?: string; // デフォルトで選択されるプリセット金額
+    custom: boolean; // ユーザーがカスタム金額を入力できるようにする
+    minimum?: string; // 最小カスタム金額
+    maximum?: string; // 最大カスタム金額
+  };
+  btnText?: string; // メインの寄付ボタンのテキスト、例：「寄付する」
+  historyType?: 'table' | 'avatar'; // 支援者リストの表示方法
+}
+```
+
+## 使用例
+
+以下は、ページに寄付セクションを設定する完全な例です。`CheckoutDonate` を `DonateProvider` と `PaymentProvider` の両方でラップする方法を示しています。
+
+```tsx App.tsx icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/use-session'; // あなたのカスタムセッションフック
+
+function DonationSection() {
+  const { session, connectApi } = useSessionContext();
+
+  // ユーザーが認証されていない場合は何もレンダリングしないか、ログインプロンプトを表示します
+  if (!session?.user) {
+    return <div>Please log in to make a donation.</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <DonateProvider
+        mountLocation="support-our-blog-post-123"
+        description="Donation for the article 'Getting Started with React'"
+        defaultSettings={{
+          btnText: 'Support the Author',
+          amount: {
+            presets: ['1', '5', '10'],
+            custom: true,
+            minimum: '1',
+          },
+        }}>
+        <CheckoutDonate
+          settings={{
+            target: 'post-123', // 寄付対象の一意の識別子
+            title: 'Support the Author',
+            description: 'If you found this article helpful, feel free to buy me a coffee.',
+            reference: 'https://your-site.com/posts/123',
+            beneficiaries: [
+              {
+                address: 'z8iZ75n8fWJ2aL1c9a9f4c3b2e1a0d9f8e7d6c5b4a392817',
+                share: '100',
+              },
+            ],
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+## フックとユーティリティ
+
+このライブラリは、寄付コンテキストとキャッシュを高度に制御するためのヘルパー関数もいくつかエクスポートしています。
+
+### `useDonateContext`
+
+`DonateProvider` の任意の子コンポーネントから寄付コンテキストに直接アクセスするためのReactフック。
+
+```tsx
+import { useDonateContext } from '@blocklet/payment-react';
+
+function CustomDonationInfo() {
+  const { settings, refresh } = useDonateContext();
+
+  return (
+    <div>
+      <p>Donations are currently {settings.active ? 'enabled' : 'disabled'}.</p>
+      <button onClick={() => refresh(true)}>Refresh Settings</button>
+    </div>
+  );
+}
+```
+
+### `clearDonateCache`
+
+この関数は、特定の `mountLocation` のキャッシュされた設定を `localStorage` から手動で削除します。これは、サーバー上で設定が変更されたことがわかっており、次のコンポーネントのレンダリング時に強制的に新しいデータを取得したい場合に便利です。
+
+```javascript
+import { clearDonateCache } from '@blocklet/payment-react';
+
+// キャッシュを無効にする必要があるときにこの関数を呼び出します
+clearDonateCache('support-our-blog-post-123');
+```
+
+### `clearDonateSettings`
+
+この関数は、指定された `mountLocation` の設定を永久に削除するために、バックエンドAPIに `DELETE` リクエストを送信します。また、その場所のローカルキャッシュもクリアします。
+
+```javascript
+import { clearDonateSettings } from '@blocklet/payment-react';
+
+async function deleteDonationInstance() {
+  try {
+    await clearDonateSettings('support-our-blog-post-123');
+    console.log('Donation settings have been deleted.');
+  } catch (error) {
+    console.error('Failed to delete settings:', error);
+  }
+}
+```
+
+`DonateProvider` を設定すると、さまざまな寄付機能を実装できるようになります。次のステップは、寄付UIを表示するためのメインコンポーネントを探ることです。
+
+➡️ 次に、[`CheckoutDonate`](./components-checkout-checkout-donate.md) コンポーネントを使用して寄付ウィジェットをレンダリングする方法を学びます。

package/docs/providers-donate-provider.zh-TW.md

@@ -0,0 +1,153 @@
+# DonateProvider
+
+`DonateProvider` 是一個關鍵的 context provider，負責管理應用程式中所有捐款相關元件的狀態和設定。它會處理從後端擷取設定、為了效能而快取設定，並將設定提供給像 `CheckoutDonate` 這樣的元件。
+
+若要使用任何捐款功能，您必須用 `DonateProvider` 包裹您的元件。此 provider 也必須巢狀嵌套在 [`PaymentProvider`](./providers-payment-provider.md) 內，以確保能存取必要的支付 context 和 session 資訊。
+
+## 運作方式
+
+`DonateProvider` 執行幾個關鍵功能：
+
+1.  **擷取設定**：在掛載時，它會呼叫一個 API 端點來擷取與唯一的 `mountLocation` prop 相關聯的捐款設定。這些設定決定了子捐款元件的行為。
+2.  **快取資料**：為了提升效能並減少網路請求，擷取到的設定會儲存在 `localStorage` 中。快取會在後續載入時自動使用，如有需要也可以手動清除。
+3.  **提供 Context**：它使用 React 的 Context API 將設定和控制函式（`refresh`、`updateSettings`）傳遞給任何需要它們的後代元件。
+4.  **啟用捐款**：對於管理員使用者（'owner' 或 'admin'），如果捐款實例處於非活動狀態但設定了 `enableDonate` prop，provider 將會渲染一個 UI 來啟用它。
+
+## Props
+
+`DonateProvider` 接受以下 props 來設定其行為：
+
+| Prop | Type | Required | Description |
+| ----------------- | ---------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `mountLocation` | `string` | 是 | 此特定捐款實例的唯一字串識別碼。它被用作擷取、快取和更新設定的鍵。 |
+| `description` | `string` | 是 | 一個人類可讀的描述，有助於在系統後端或日誌中識別此捐款實例。 |
+| `children` | `ReactNode` | 是 | 將在 provider 內渲染的子元件，通常包含 `CheckoutDonate`。 |
+| `defaultSettings` | `DonateConfigSettings` | 否 | 一個包含預設設定的物件，如果在後端找不到設定時套用。有關可用選項，請參閱下方的類型定義。 |
+| `active` | `boolean` | 否 | 設定捐款實例首次建立時的初始活動狀態。預設為 `true`。 |
+| `enableDonate` | `boolean` | 否 | 如果為 `true`，允許管理員使用者在捐款實例目前為非活動狀態時，從 UI 啟用它。預設為 `false`。 |
+
+### DonateConfigSettings 類型
+
+這是 `defaultSettings` 物件的結構：
+
+```typescript DonateConfigSettings type
+export interface DonateConfigSettings {
+  amount?: {
+    presets?: string[]; // 例如 ['1', '5', '10']
+    preset?: string; // 預設選擇的預設金額
+    custom: boolean; // 允許使用者輸入自訂金額
+    minimum?: string; // 最小自訂金額
+    maximum?: string; // 最大自訂金額
+  };
+  btnText?: string; // 主要捐款按鈕的文字，例如 "Donate"
+  historyType?: 'table' | 'avatar'; // 如何顯示支持者列表
+}
+```
+
+## 使用範例
+
+這是一個在頁面上設定捐款區塊的完整範例。它展示了如何使用 `DonateProvider` 和 `PaymentProvider` 來包裹 `CheckoutDonate`。
+
+```tsx App.tsx icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/use-session'; // 您的自訂 session hook
+
+function DonationSection() {
+  const { session, connectApi } = useSessionContext();
+
+  // 如果使用者未經驗證，則不渲染任何內容或顯示登入提示
+  if (!session?.user) {
+    return <div>Please log in to make a donation.</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <DonateProvider
+        mountLocation="support-our-blog-post-123"
+        description="Donation for the article 'Getting Started with React'"
+        defaultSettings={{
+          btnText: 'Support the Author',
+          amount: {
+            presets: ['1', '5', '10'],
+            custom: true,
+            minimum: '1',
+          },
+        }}>
+        <CheckoutDonate
+          settings={{
+            target: 'post-123', // 捐款目標的唯一識別碼
+            title: 'Support the Author',
+            description: 'If you found this article helpful, feel free to buy me a coffee.',
+            reference: 'https://your-site.com/posts/123',
+            beneficiaries: [
+              {
+                address: 'z8iZ75n8fWJ2aL1c9a9f4c3b2e1a0d9f8e7d6c5b4a392817',
+                share: '100',
+              },
+            ],
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+## Hooks 和公用程式
+
+該函式庫還匯出了一些輔助函式，用於對捐款 context 和快取進行進階控制。
+
+### `useDonateContext`
+
+一個 React hook，用於從 `DonateProvider` 的任何子元件中直接存取捐款 context。
+
+```tsx
+import { useDonateContext } from '@blocklet/payment-react';
+
+function CustomDonationInfo() {
+  const { settings, refresh } = useDonateContext();
+
+  return (
+    <div>
+      <p>Donations are currently {settings.active ? 'enabled' : 'disabled'}.</p>
+      <button onClick={() => refresh(true)}>Refresh Settings</button>
+    </div>
+  );
+}
+```
+
+### `clearDonateCache`
+
+此函式會從 `localStorage` 中手動移除特定 `mountLocation` 的快取設定。當您知道伺服器上的設定已變更，並希望在下次元件渲染時強制重新擷取時，這非常有用。
+
+```javascript
+import { clearDonateCache } from '@blocklet/payment-react';
+
+// 當您需要讓快取失效時，呼叫此函式
+clearDonateCache('support-our-blog-post-123');
+```
+
+### `clearDonateSettings`
+
+此函式會向後端 API 發送一個 `DELETE` 請求，以永久移除給定 `mountLocation` 的設定。它也會清除該位置的本地快取。
+
+```javascript
+import { clearDonateSettings } from '@blocklet/payment-react';
+
+async function deleteDonationInstance() {
+  try {
+    await clearDonateSettings('support-our-blog-post-123');
+    console.log('Donation settings have been deleted.');
+  } catch (error) {
+    console.error('Failed to delete settings:', error);
+  }
+}
+```
+
+設定好 `DonateProvider` 後，您現在可以實作各種捐款功能。下一步是探索用於顯示捐款 UI 的主要元件。
+
+➡️ 接下來，學習如何使用 [`CheckoutDonate`](./components-checkout-checkout-donate.md) 元件來渲染捐款小工具。