@blocklet/payment-react/docs/components-business-auto-topup.ja.md

Reusable react components for payment kit v2

# 自動チャージコンポーネント

自動チャージ機能は、ユーザーのクレジット残高が指定されたしきい値を下回った場合に自動的にチャージすることで、サービスの中断を防ぎます。これは主に2つのコンポーネントで管理されます：現在の設定を表示する`AutoTopup`と、設定用のインターフェースを提供する`AutoTopupModal`です。

## 自動チャージのワークフロー

以下の図は、自動チャージ機能設定の典型的なユーザーフローを示しています。ユーザーは`AutoTopup`表示コンポーネントを操作し、それが変更を行うための`AutoTopupModal`を起動します。その後、モーダルはバックエンドAPIと通信して設定を保存します。

<!-- DIAGRAM_IMAGE_START:flowchart:16:9 -->
![Auto-Topup Components](assets/diagram/auto-topup-diagram-0.jpg)
<!-- DIAGRAM_IMAGE_END -->

## AutoTopup

`AutoTopup`コンポーネントは、特定の通貨の現在の自動チャージステータスを表示し、設定へのエントリーポイントを提供する表示カードです。柔軟性のために複数のレンダリングモードをサポートしています。

### Props

| Prop | Type | Description |
| --- | --- | --- |
| `currencyId` | `string` | **必須。** 管理するクレジット通貨のID。 |
| `onConfigChange` | `(config: AutoRechargeConfig) => void` | 任意。設定が正常に更新されたときにトリガーされるコールバック関数。 |
| `mode` | `'default' \| 'simple' \| 'custom'` | 任意。レンダリングモード。デフォルトは`'default'`です。<br/>- `default`: 全ての詳細を表示する完全に展開されたカード。<br/>- `simple`: 詳細を展開するためのボタンが付いた、コンパクトで折りたたまれたビュー。<br/>- `custom`: `children`レンダープロップを使用してカスタムUIをレンダリングします。 |
| `sx` | `SxProps` | 任意。コンポーネントに適用するカスタムMUIスタイル。 |
| `children` | `(openModal, config, paymentData, loading) => React.ReactNode` | 任意。`mode`が`'custom'`の場合にのみ使用されるレンダープロップ関数。カスタムインターフェースを構築するために必要なツールを受け取ります。 |

### 使用方法

#### シンプルモード

これは最も一般的な使用例で、ユーザーが詳細を展開できるコンパクトな表示を提供します。

```tsx CreditManagement.tsx icon=logos:react
import { PaymentProvider, AutoTopup } from '@blocklet/payment-react';

function CreditManagement({ session, currencyId }) {
  const handleConfigChange = (config) => {
    console.log('自動チャージの設定が更新されました:', config);
    // ここでユーザーの残高を更新することをお勧めします
  };

  return (
    <PaymentProvider session={session}>
      <AutoTopup
        currencyId={currencyId}
        mode="simple"
        onConfigChange={handleConfigChange}
        sx={{ mt: 2 }}
      />
    </PaymentProvider>
  );
}
```

#### カスタムモード

UIを完全に制御するには、レンダープロップを使用して`custom`モードを使用します。これにより、自動チャージのステータスと設定トリガーを既存のレイアウトにシームレスに統合できます。

```tsx CustomAutoTopupDisplay.tsx icon=logos:react
import { PaymentProvider, AutoTopup } from '@blocklet/payment-react';
import { Button, Card, CardContent, Typography } from '@mui/material';

function CustomAutoTopupDisplay({ session, currencyId }) {
  return (
    <PaymentProvider session={session}>
      <AutoTopup currencyId={currencyId} mode="custom">
        {(openModal, config, paymentData, loading) => {
          if (loading) return <div>設定を読み込み中...</div>;

          return (
            <Card variant="outlined">
              <CardContent>
                <Typography variant="h6">スマート自動チャージ</Typography>
                {config?.enabled ? (
                  <Typography color="success.main">
                    ステータス: アクティブ
                  </Typography>
                ) : (
                  <Typography color="text.secondary">
                    ステータス: 非アクティブ
                  </Typography>
                )}
                <Button onClick={openModal} variant="contained" sx={{ mt: 2 }}>
                  {config?.enabled ? '設定を変更' : '今すぐ設定'}
                </Button>
              </CardContent>
            </Card>
          );
        }}
      </AutoTopup>
    </PaymentProvider>
  );
}
```

## AutoTopupModal

`AutoTopupModal`は、トリガーとなるしきい値、購入金額、支払い方法など、自動チャージ機能のすべての側面をユーザーが有効化、無効化、設定できるダイアログコンポーネントです。

### Props

| Prop | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | **必須。** モーダルが表示されるかどうかを制御します。 |
| `onClose` | `() => void` | **必須。** モーダルを閉じるためのコールバック関数。 |
| `currencyId` | `string` | **必須。** 設定するクレジット通貨のID。 |
| `customerId` | `string` | 任意。顧客のDID。デフォルトは`PaymentProvider`セッションからのユーザーです。 |
| `onSuccess` | `(config: AutoRechargeConfig) => void` | 任意。設定が正常に保存された後にトリガーされるコールバック。 |
| `onError` | `(error: any) => void` | 任意。送信中にエラーが発生した場合にトリガーされるコールバック。 |
| `defaultEnabled` | `boolean` | 任意。`true`の場合、新しい設定のためにモーダルが開かれると、'自動チャージを有効にする'スイッチがデフォルトでオンになります。 |

### 使用方法

以下は、`AutoTopupModal`の状態を管理し、そのコールバックを処理する方法の完全な例です。

```tsx AutoRechargeSettings.tsx icon=logos:react
import { PaymentProvider, AutoTopupModal } from '@blocklet/payment-react';
import { useState } from 'react';
import { Button } from '@mui/material';

function AutoRechargeSettings({ session, currencyId }) {
  const [isModalOpen, setModalOpen] = useState(false);

  const handleSuccess = (config) => {
    console.log('設定が正常に保存されました:', config);
    setModalOpen(false);
    // オプションで、成功のトーストを表示するか、データを更新します
  };

  const handleError = (error) => {
    console.error('設定の保存に失敗しました:', error);
    // オプションで、ユーザーにエラーメッセージを表示します
  };

  return (
    <PaymentProvider session={session}>
      <Button variant="contained" onClick={() => setModalOpen(true)}>
        自動チャージを設定
      </Button>

      <AutoTopupModal
        open={isModalOpen}
        onClose={() => setModalOpen(false)}
        currencyId={currencyId}
        onSuccess={handleSuccess}
        onError={handleError}
        defaultEnabled={true}
      />
    </PaymentProvider>
  );
}
```

この設定は、自動チャージ機能を管理するための堅牢な方法を提供し、ユーザーに制御権を与えながら、サービス利用クレジットを維持するためのスムーズな体験を保証します。