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

Reusable react components for payment kit v2

# 自动充值组件

自动充值功能通过在用户信用余额低于指定阈值时自动为其充值，确保服务不中断。该功能由两个主要组件管理：`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` 组件是一个显示卡片，用于展示特定货币的当前自动充值状态，并提供配置入口。它支持多种渲染模式以实现灵活性。

### 属性

| Prop | Type | Description |
| --- | --- | --- |
| `currencyId` | `string` | **必需。** 要管理的信用货币的 ID。 |
| `onConfigChange` | `(config: AutoRechargeConfig) => void` | 可选。配置成功更新时触发的回调函数。 |
| `mode` | `'default' \| 'simple' \| 'custom'` | 可选。渲染模式。默认为 `'default'`。<br/>- `default`：完全展开的卡片，显示所有详细信息。<br/>- `simple`：紧凑的折叠视图，带有一个展开详情的按钮。<br/>- `custom`：使用 `children` render prop 渲染自定义 UI。 |
| `sx` | `SxProps` | 可选。应用于组件的自定义 MUI 样式。 |
| `children` | `(openModal, config, paymentData, loading) => React.ReactNode` | 可选。仅在 `mode` 为 `'custom'` 时使用的 render prop 函数。它接收构建自定义界面所需的工具。 |

### 用法

#### 简单模式

这是最常见的用例，提供一个紧凑的显示，用户可以展开以查看更多详细信息。

```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，请使用带有 render prop 的 `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` 是一个对话框组件，允许用户启用、禁用和配置自动充值功能的所有方面，包括触发阈值、购买金额和支付方式。

### 属性

| 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>
  );
}
```

此设置提供了一种强大的方式来管理自动充值功能，在给予用户控制权的同时，确保了维持其服务信用的流畅体验。