@blocklet/payment-react/docs/guides-utilities.ja.md

Reusable react components for payment kit v2

# ユーティリティ

`@blocklet/payment-react` ライブラリは、APIリクエストの作成、キャッシュの管理、日付の処理、価格のフォーマット、国際化の設定といった一般的なタスクを簡素化するために設計された一連のユーティリティ関数とクラスをエクスポートします。これらのツールは、ライブラリのコンポーネントやプロバイダーとシームレスに連携するように構築されています。

## APIクライアント

ライブラリは、支払いバックエンドへのAPIリクエストを行うための事前設定済みAxiosインスタンスを提供します。ベースURLやその他の必要な設定を自動的に処理します。

```tsx API Client Usage icon=logos:javascript
import { api } from '@blocklet/payment-react';

// 基本的なGETリクエスト
const getPayments = async () => {
  const response = await api.get('/api/payments');
  return response.data;
};

// ペイロード付きのPOSTリクエスト
const createCheckout = async (amount) => {
  const data = await api.post('/api/checkout', { amount });
  return data;
};

// クエリパラメータ付きのGETリクエスト
const getPaidInvoices = async () => {
  const results = await api.get('/api/invoices', { 
    params: { status: 'paid' } 
  });
  return results.data;
};

// 追加設定付きのPUTリクエスト
const updateSubscription = async (data) => {
  const config = { 
    headers: { 'Custom-Header': 'value' }
  };
  const response = await api.put('/api/subscription', data, config);
  return response.data;
};
```

## CachedRequest

パフォーマンスを最適化し、冗長なネットワークリクエストを削減するために、`CachedRequest` クラスを使用できます。これは、設定可能な戦略と生存期間（TTL）でデータをキャッシュする簡単な方法を提供します。

### 設定オプション

`CachedRequest` インスタンスを作成する際に、以下のオプションを指定できます：

| オプション | タイプ | 説明 | デフォルト |
| :--- | :--- | :--- | :--- |
| `strategy` | `'session' \| 'local' \| 'memory'` | キャッシュのストレージメカニズム。 | `'session'` |
| `ttl` | `number` | キャッシュの生存期間（ミリ秒）。`0` の値は有効期限がないことを意味します。 | `0` |

### 使用例

ここでは、製品価格を取得するためのキャッシュ付きリクエストの作成方法と使用方法を示します。

```tsx CachedRequest Example icon=logos:javascript
import { CachedRequest, api } from '@blocklet/payment-react';

// 1. キャッシュ付きリクエストインスタンスを作成
const priceRequest = new CachedRequest(
  'product-prices', 
  () => api.get('/api/prices'),
  {
    strategy: 'session',  // sessionStorageにデータをキャッシュ
    ttl: 5 * 60 * 1000   // 5分間キャッシュ
  }
);

// 2. コンポーネントでキャッシュ付きリクエストを使用
async function fetchPrices() {
  // キャッシュが利用可能で期限切れでない場合、キャッシュが使用されます
  const prices = await priceRequest.fetch();
  
  // キャッシュをバイパスして強制的に新しいデータを取得する
  const freshPrices = await priceRequest.fetch(true);
  
  return prices;
}

// 3. データが変更されたときにキャッシュをクリア
async function updatePrices() {
  await api.post('/api/prices', newPriceData);
  priceRequest.clearCache(); // または await priceRequest.fetch(true);
}
```

## 日付処理

ライブラリは、`relativeTime`、`utc`、`timezone` のような便利なプラグインが既に含まれた事前設定済みの `dayjs` インスタンスを再エクスポートします。これを任意の日時操作のニーズに使用できます。

```tsx Date Handling with dayjs icon=logos:javascript
import { dayjs } from '@blocklet/payment-react';

// 現在の日付をフォーマット
const formattedDate = dayjs().format('YYYY-MM-DD HH:mm');

// タイムスタンプをパース
const dateFromTimestamp = dayjs(1672531200000);
const unixTimestamp = dateFromTimestamp.unix();

// 相対時間を計算
const fiveMinutesAgo = dayjs().subtract(5, 'minute');
const relativeTime = dayjs().from(fiveMinutesAgo); // "5 minutes ago"
```

## 国際化 (i18n)

`@blocklet/payment-react` には、i18nの組み込みサポートが含まれています。独自の翻訳機を作成するか、ライブラリのデフォルト翻訳とマージすることができます。

### 翻訳機の作成

`createTranslator` 関数を使用して、独自の翻訳インスタンスを設定します。

```tsx Custom Translator Setup icon=logos:javascript
import { createTranslator } from '@blocklet/payment-react';

const myTranslations = {
  en: { 
    checkout: { title: 'Complete Payment' }
  },
  zh: { 
    checkout: { title: '完成支付' }
  }
};

const translator = createTranslator({ fallbackLocale: 'en' }, myTranslations);

translator('checkout.title', 'zh'); // '完成支付'
```

### ライブラリ翻訳とのマージ

コンポーネント用にライブラリの組み込み翻訳を活用しつつ、独自の翻訳を追加するには、それらをマージします。

```tsx Merging Translations icon=logos:javascript
import { translations as paymentTranslations } from '@blocklet/payment-react';
import merge from 'lodash/merge';

// アプリケーションの翻訳
import en from './locales/en';
import zh from './locales/zh';

export const translations = merge(
  {
    en,
    zh,
  },
  paymentTranslations
);
```

## フォーマットユーティリティ

表示用のデータをフォーマットするためのヘルパー関数がいくつか利用可能です。

| 関数 | 説明 |
| :--- | :--- |
| `formatPrice` | 価格オブジェクトを、定期的な間隔を考慮して人間が読める文字列にフォーマットします。 |
| `formatRecurring` | 定期的なオブジェクトを "monthly" や "every 3 months" のような文字列にフォーマットします。 |
| `formatBNStr` | 基本単位からのBigNumber文字列を、指定された精度のトークン値にフォーマットします。 |
| `formatNumber` | 数値または文字列を、千単位の区切り文字と精度でフォーマットします。 |
| `formatError` | 様々なエラーフォーマット（GraphQL, Joi, Axios）を読みやすい文字列にパースします。 |

```tsx Formatting Example icon=logos:javascript
import { formatNumber, formatRecurring } from '@blocklet/payment-react';

// 数値をフォーマット
const formatted = formatNumber('1234567.89123', 2); // "1,234,567.89"

// 定期的な間隔をフォーマット
const monthly = formatRecurring({ interval: 'month', interval_count: 1 }); // "per month"
const quarterly = formatRecurring({ interval: 'month', interval_count: 3 }); // "Quarterly"
```

## バリデーションユーティリティ

ライブラリには、フォームバリデーション用のヘルパーも含まれています。

### `validatePostalCode`

指定された郵便番号が特定の国で有効かどうかをチェックします。

```tsx Postal Code Validation icon=logos:javascript
import { validatePostalCode } from '@blocklet/payment-react';

// trueを返します
const isValidUS = validatePostalCode('90210', 'US');

// falseを返します
const isInvalidUS = validatePostalCode('ABC-123', 'US');

// 英国の郵便番号に対してtrueを返します
const isValidGB = validatePostalCode('SW1A 0AA', 'GB');
```