@blocklet/payment-react/docs/components-ui-pricing-table.zh-TW.md

Reusable react components for payment kit v2

# PricingTable

`PricingTable` 元件是一個彈性的 UI 元件，旨在以結構化、響應式的表格來顯示訂閱方案與價格選項。它允許使用者切換計費週期（例如，月繳、年繳）、選擇偏好的貨幣，並選擇一個方案以繼續進行。

當您需要精細控制價格方案的呈現方式以建立自訂結帳流程時，此元件是理想的選擇。若需要一個能處理完整結帳流程的整合度更高的解決方案，請考慮使用更高階的 [`CheckoutTable`](./components-checkout-checkout-table.md) 元件。

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `table` | `TPricingTableExpanded` | - | **必填**。一個包含價格表資料的物件，包括項目（方案）列表、貨幣資訊和其他詳細資訊。 |
| `onSelect` | `(priceId: string, currencyId: string) => void` | - | **必填**。當使用者點擊方案的動作按鈕時觸發的回呼函式。它會接收所選的 `priceId` 和 `currencyId`。 |
| `alignItems` | `'center' \| 'left'` | `'center'` | 控制表格標頭內容（計費週期和貨幣選擇器）的水平對齊方式。 |
| `mode` | `'checkout' \| 'select'` | `'checkout'` | 決定動作按鈕的行為和文字。`'checkout'` 模式用於啟動付款，而 `'select'` 模式用於在較大的表單中選擇方案。 |
| `interval` | `string` | `''` | 設定初始選擇的計費間隔。格式通常為 `interval-interval_count`（例如 `month-1`、`year-1`）。 |
| `hideCurrency` | `boolean` | `false` | 若為 `true`，即使有多種貨幣可用，貨幣選擇器下拉選單也將被隱藏。 |

## 使用範例

若要使用 `PricingTable`，您必須將其包裝在 `PaymentProvider` 中。該元件需要一個包含您產品資料的 `table` 物件，以及一個用於管理使用者選擇的 `onSelect` 處理函式。

```tsx Integration Example icon=lucide:code
import { PaymentProvider } from '@blocklet/payment-react';
import { PricingTable } from '@blocklet/payment-react/components/ui';
import type { TPricingTableExpanded } from '@blocklet/payment-types';

// 在實際應用中，您會從您的支付服務中獲取此資料。
const pricingTableData: TPricingTableExpanded = {
  id: 'pt_123',
  livemode: false,
  currency: { id: 'usd', symbol: '$' },
  items: [
    {
      price_id: 'price_basic_monthly',
      product: {
        name: 'Basic Plan',
        description: 'For individuals and small teams.',
        unit_label: 'user',
        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '1000', // 以分為單位
        recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
      },
      is_highlight: false,
    },
    {
      price_id: 'price_pro_monthly',
      product: {
        name: 'Pro Plan',
        description: 'For growing businesses.',
        unit_label: 'user',
        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '2500',
        recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '2500' }],
      },
      is_highlight: true,
      highlight_text: 'Popular',
    },
    {
      price_id: 'price_basic_yearly',
      product: {
        name: 'Basic Plan',
        description: 'For individuals and small teams.',
        unit_label: 'user',
        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '10000',
        recurring: { interval: 'year', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '10000' }],
      },
      is_highlight: false,
    },
    {
      price_id: 'price_pro_yearly',
      product: {
        name: 'Pro Plan',
        description: 'For growing businesses.',
        unit_label: 'user',
        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
      },
      price: {
        currency: 'usd',
        unit_amount: '25000',
        recurring: { interval: 'year', interval_count: 1, usage_type: 'licensed' },
        currency_options: [{ currency_id: 'usd', unit_amount: '25000' }],
      },
      is_highlight: true,
      highlight_text: 'Popular',
    },
  ],
};

function MyPricingPage() {
  const { session, connect } = useSessionContext();

  const handlePlanSelect = async (priceId: string, currencyId: string) => {
    console.log(`Plan selected: ${priceId}, Currency: ${currencyId}`);
    // 在這裡，您通常會導向到結帳頁面或打開一個付款彈出視窗。
    // 例如：`router.push("/checkout?price_id=${priceId}&currency_id=${currencyId}")`
    alert(`Selected Price ID: ${priceId}`);
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      <div style={{ maxWidth: 800, margin: 'auto' }}>
        <PricingTable table={pricingTableData} onSelect={handlePlanSelect} />
      </div>
    </PaymentProvider>
  );
}

export default MyPricingPage;
```

## 使用情境

### 模式：`checkout` vs. `select`

`mode` 屬性會改變行動呼籲按鈕以適應不同的使用案例。

-   **`mode='checkout'` (預設):** 按鈕文字將根據情境顯示，例如「訂閱」或「開始試用」。此模式適用於使用者點擊後應立即啟動付款或結帳流程的情況。

-   **`mode='select'`:** 按鈕文字將顯示「選擇」或「已選擇」。當價格表是較大表單或多步驟流程的一部分時，這非常有用。`onSelect` 回呼可用於更新應用程式狀態中所選擇的方案，且 UI 將視覺上指示目前選擇的方案。

### 處理 `onSelect`

`onSelect` 回呼是處理使用者互動的核心機制。它是一個非同步函式，會接收所選方案的 `priceId` 和 `currencyId`。您的應用程式邏輯應置於此處。常見的操作包括：

-   將所選方案儲存在您的應用程式狀態中。
-   將使用者重新導向至專用的結帳頁面，並將 `priceId` 作為 URL 參數傳遞。
-   使用 `priceId` 與支付服務後端建立一個結帳會話，然後開啟一個付款表單。