メインコンテンツへスキップ

DonateProvider

DonateProviderは、アプリケーション内のすべての寄付関連コンポーネントの状態と設定を管理する、極めて重要なコンテキストプロバイダーです。バックエンドから設定を取得し、パフォーマンス向上のためにキャッシュし、CheckoutDonateなどのコンポーネントに提供する役割を担います。

DonateProviderは、アプリケーション内のすべての寄付関連コンポーネントの状態と設定を管理する、極めて重要なコンテキストプロバイダーです。バックエンドから設定を取得し、パフォーマンス向上のためにキャッシュし、CheckoutDonateなどのコンポーネントに提供する役割を担います。

寄付機能を使用するには、コンポーネントをDonateProviderでラップする必要があります。また、このプロバイダーは、必要な支払いコンテキストとセッション情報へのアクセスを確保するために、PaymentProvider内にネストされている必要があります。

仕組み

DonateProviderは、いくつかの主要な機能を実行します：

  1. 設定の取得

    マウント時に、APIエンドポイントを呼び出して、一意のmountLocationプロップに関連付けられた寄付設定を取得します。これらの設定は、子となる寄付コンポーネントの動作を決定します。

  2. データのキャッシュ

    パフォーマンスを向上させ、ネットワークリクエストを削減するために、取得した設定はlocalStorageに保存されます。キャッシュは次回以降の読み込みで自動的に使用され、必要に応じて手動でクリアすることもできます。

  3. コンテキストの提供

    ReactのContext APIを使用して、設定と制御関数（refresh、updateSettings）を、それらを必要とするすべての子孫コンポーネントに渡します。

  4. 寄付の有効化

    管理者ユーザー（'owner'または'admin'）に対して、寄付インスタンスが非アクティブであってもenableDonateプロップが設定されている場合、プロバイダーはそれをアクティブ化するためのUIをレンダリングします。

Props

DonateProviderは、その動作を設定するために以下のプロップを受け入れます：

PropTypeRequiredDescription
mountLocationstringはいこの特定の寄付インスタンスのための一意の文字列識別子。設定の取得、キャッシュ、更新のキーとして使用されます。
descriptionstringはいシステムバックエンドやログでこの寄付インスタンスを識別するのに役立つ、人間が読める形式の説明。
childrenReactNodeはいプロバイダーの内部でレンダリングされる子コンポーネント。通常は CheckoutDonate を含みます。
defaultSettingsDonateConfigSettingsいいえバックエンドで設定が見つからない場合に適用されるデフォルト設定を持つオブジェクト。利用可能なオプションについては、以下の型定義を参照してください。
activebooleanいいえ寄付インスタンスが最初に作成されるときの初期アクティブ状態を設定します。デフォルトは true です。
enableDonatebooleanいいえtrue の場合、管理者ユーザーが現在非アクティブなこの寄付インスタンスをUIから有効にできるようにします。デフォルトは false です。

DonateConfigSettings 型

これは defaultSettings オブジェクトの形状です：

DonateConfigSettings type

typescript
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 の両方でラップする方法を示しています。

App.tsx

tsx
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 コンポーネントを使用して寄付ウィジェットをレンダリングする方法を学びます。