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

Reusable react components for payment kit v2

# ResumeSubscription

`ResumeSubscription` 元件為使用者提供了一個簡單明瞭的使用者介面，以便恢復已取消的訂閱。它會渲染一個對話方塊，引導使用者完成確認過程，並在訂閱需要時自動處理重新質押等複雜情境。

此元件必須在 `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`                                                 | 是      | 要恢復的訂閱的唯一識別碼。                                                                                                             |
| `onResumed`      | `(subscription: Subscription) => void`                   | 否       | 訂閱成功恢復後觸發的回呼函式。它會收到更新後的訂閱物件作為參數。                                                                   |
| `dialogProps`    | `object`                                                 | 否       | 用於自訂底層 Material-UI Dialog 的 props。您可以控制其狀態（`open`、`onClose`）和外觀（`title`）。                                          |
| `successToast`   | `boolean`                                                | 否       | 如果為 `true`，成功恢復後會顯示成功通知吐司。預設為 `true`。                                                                     |
| `authToken`      | `string`                                                 | 否       | 用於 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'; // 您的應用程式的 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>
  );
}
```