自动充值组件

自动充值功能通过在用户信用余额低于指定阈值时自动为其充值，确保服务不中断。该功能由两个主要组件管理：AutoTopup，用于显示当前配置；以及 AutoTopupModal，用于提供设置界面。

自动充值工作流

下图展示了配置自动充值功能的典型用户流程。用户与 AutoTopup 显示组件交互，该组件会启动 AutoTopupModal 以进行更改。然后，该模态框与后端 API 通信以保存配置。

Auto-Topup Components

AutoTopup

AutoTopup 组件是一个显示卡片，用于展示特定货币的当前自动充值状态，并提供配置入口。它支持多种渲染模式以实现灵活性。

属性

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

用法

简单模式

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

CreditManagement.tsx

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 模式。这允许您将自动充值状态和配置触发器无缝集成到现有布局中。

CustomAutoTopupDisplay.tsx

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 状态并处理其回调的完整示例。

AutoRechargeSettings.tsx

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

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