@blocklet/payment-react/docs/components-business-resume-subscription.zh.md

Reusable react components for payment kit v2

# ResumeSubscription

`ResumeSubscription` 组件为用户提供了一个简单的 UI，用于恢复已取消的订阅。它会渲染一个对话框，引导用户完成确认过程，并自动处理需要重新质押等复杂场景。

该组件必须在 `PaymentProvider` 内部使用，以访问处理钱包交互所需的上下文。

## 工作流程

下图说明了用户恢复订阅时的流程，包括重新质押的条件逻辑。

<!-- DIAGRAM_IMAGE_START:sequence:4:3 -->
![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.jpg)
<!-- DIAGRAM_IMAGE_END -->


## Props

| Prop             | Type                                                     | Required | Description                                                                                                                              |
| ---------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `subscriptionId` | `string`                                                 | Yes      | 要恢复的订阅的唯一标识符。                                                                                                               |
| `onResumed`      | `(subscription: Subscription) => void`                   | No       | 订阅成功恢复后触发的回调函数。它会接收更新后的订阅对象作为参数。                                                                         |
| `dialogProps`    | `object`                                                 | No       | 用于自定义底层 Material-UI Dialog 的 Props。您可以控制其状态（`open`、`onClose`）和外观（`title`）。                                      |
| `successToast`   | `boolean`                                                | No       | 如果为 `true`，则在成功恢复时显示成功通知 toast。默认为 `true`。                                                                         |
| `authToken`      | `string`                                                 | No       | 用于 API 请求的可选身份验证令牌。这对于跨域或服务器到服务器的集成场景很有用。                                                           |

## 使用示例

### 基本用法

这是使用该组件最简单的方式。默认情况下，它将渲染一个打开的对话框。

```tsx Basic ResumeSubscription Example icon=logos:react
import { ResumeSubscription } from '@blocklet/payment-react';

function ResumePage({ subscriptionId }) {
  // 该组件必须在 PaymentProvider 内部渲染
  return <ResumeSubscription subscriptionId={subscriptionId} />;
}
```

### 处理结果

使用 `onResumed` 回调接收更新后的订阅数据并刷新您的应用程序状态。

```tsx Handling the onResumed Callback icon=logos:react
import { ResumeSubscription } from '@blocklet/payment-react';
import { useState } from 'react';

function SubscriptionDetails({ initialSubscription }) {
  const [subscription, setSubscription] = useState(initialSubscription);

  const handleSubscriptionResumed = (updatedSubscription) => {
    console.log('订阅已成功恢复:', updatedSubscription);
    setSubscription(updatedSubscription);
    // 您还可以显示确认消息或重定向用户。
  };

  return (
    <div>
      {/* 根据 `subscription` 状态显示订阅详情 */}
      <ResumeSubscription
        subscriptionId={subscription.id}
        onResumed={handleSubscriptionResumed}
      />
    </div>
  );
}
```

### 控制对话框

为了更实用的集成，可以从父组件控制对话框的可见性。这允许您响应用户操作（如点击按钮）来打开它。

```tsx Triggering ResumeSubscription with a Button icon=logos:react
import { ResumeSubscription } from '@blocklet/payment-react';
import { useState } from 'react';
import { Button } from '@mui/material';

function SubscriptionActions({ subscriptionId }) {
  const [isModalOpen, setIsModalOpen] = useState(false);

  const handleResumed = () => {
    setIsModalOpen(false);
    // 重新获取订阅数据以更新 UI
    alert('订阅已恢复！');
  };

  return (
    <>
      <Button variant="contained" onClick={() => setIsModalOpen(true)}>
        恢复订阅
      </Button>

      {isModalOpen && (
        <ResumeSubscription
          subscriptionId={subscriptionId}
          onResumed={handleResumed}
          dialogProps={{
            open: isModalOpen,
            title: '确认续订',
            onClose: () => setIsModalOpen(false),
          }}
        />
      )}
    </>
  );
}
```

## 完整集成示例

这是一个完整的示例，展示了如何在所需的 `PaymentProvider` 中集成 `ResumeSubscription`。

```tsx Complete Integration Example icon=logos:react
import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
import { useSessionContext } from 'path/to/your/session/context'; // 您的应用的会话上下文
import { useState } from 'react';
import { Button, Card, CardContent, Typography } from '@mui/material';

function SubscriptionManagementPage({ subscription }) {
  const { session, connect } = useSessionContext();
  const [isResumeOpen, setIsResumeOpen] = useState(false);

  const handleResumed = (updatedSubscription) => {
    console.log('订阅已更新:', updatedSubscription);
    setIsResumeOpen(false);
    // 理想情况下，您应在此处触发数据重新获取以更新整个页面。
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      <Card>
        <CardContent>
          <Typography variant="h5">管理您的订阅</Typography>
          <Typography color="text.secondary">状态: {subscription.status}</Typography>

          {subscription.status === 'canceled' && (
            <Button
              variant="contained"
              color="primary"
              sx={{ mt: 2 }}
              onClick={() => setIsResumeOpen(true)}>
              恢复订阅
            </Button>
          )}
        </CardContent>
      </Card>

      {isResumeOpen && (
        <ResumeSubscription
          subscriptionId={subscription.id}
          onResumed={handleResumed}
          dialogProps={{
            open: isResumeOpen,
            onClose: () => setIsResumeOpen(false),
          }}
        />
      )}
    </PaymentProvider>
  );
}
```