@blocklet/payment-react/docs/providers-donate-provider.ja.md

Reusable react components for payment kit v2

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