PricingTable | ArcBlock

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

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

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 處理函式。

Integration Example

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 與支付服務後端建立一個結帳會話，然後開啟一個付款表單。