@blocklet/payment-react/docs/components-ui-form-elements-currency-selector.zh.md

Reusable react components for payment kit v2

# CurrencySelector

`CurrencySelector` 组件提供了一个用户友好的界面，用于从可用选项列表中选择支付货币。它会显示每种货币的徽标、符号和关联的支付方式，方便用户做出选择。该组件通常在较大的支付或结账表单中使用。

## Props

| Prop         | Type                                                     | Description                                                                                                       | Required |
| :----------- | :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :------- |
| `value`      | `string`                                                 | 当前所选货币的 ID。该值应由父组件的状态管理。              | 是      |
| `currencies` | `TPaymentCurrency[]`                                     | 一个包含可用货币对象的数组，用作可选项进行显示。                                          | 是      |
| `onChange`   | `(currencyId: string, methodId?: string) => void`        | 当用户选择一种货币时执行的回调函数。它会接收新的货币 ID 和可选的关联支付方式 ID。 | 是      |

### TPaymentCurrency 类型

`currencies` prop 需要一个具有以下结构的对象数组：

```typescript TPaymentCurrency icon=mdi:code-json
export type TPaymentCurrency = {
  id: string;       // 货币选项的唯一标识符
  logo: string;     // 货币/方式的徽标 URL
  name: string;     // 货币的显示名称
  symbol: string;   // 货币符号（例如 '$', '€'）
  method: {         // 关联的支付方式
    id: string;
    name: string;
  };
};
```

## 用法示例

这是一个如何实现 `CurrencySelector` 组件的基本示例。您需要在父组件中管理所选货币的状态，并提供一个可用货币列表。

请注意，`@blocklet/payment-react` 组件设计为在 `PaymentProvider` 内部工作，`PaymentProvider` 提供了必要的主题和上下文。请确保您的组件被正确包裹。

```jsx MyCurrencySelectorComponent.tsx icon=logos:react
import React, { useState } from 'react';
import { PaymentProvider } from '@blocklet/payment-react';
import { CurrencySelector } from '@blocklet/payment-react/components';
import type { TPaymentCurrency } from '@blocklet/payment-types';
import { useSessionContext } from '@/hooks/session-context'; // 根据您的项目结构调整此导入路径

// 用于演示的模拟数据
const mockCurrencies: TPaymentCurrency[] = [
  {
    id: 'usd_xxxxxx',
    logo: 'https://path-to-your/usd-logo.png',
    name: 'US Dollar',
    symbol: 'USD',
    method: {
      id: 'stripe_yyyyy',
      name: 'Stripe',
    },
  },
  {
    id: 'eth_zzzzzz',
    logo: 'https://path-to-your/eth-logo.png',
    name: 'Ethereum',
    symbol: 'ETH',
    method: {
      id: 'crypto_aaaaa',
      name: 'Crypto Payment',
    },
  },
];

function MyCurrencySelectorComponent() {
  const [selectedCurrency, setSelectedCurrency] = useState<string>(mockCurrencies[0].id);

  const handleCurrencyChange = (currencyId: string, methodId?: string) => {
    console.log(`Selected currency: ${currencyId}, Method: ${methodId}`);
    setSelectedCurrency(currencyId);
  };

  return (
    <div>
      <h3>Select a Currency</h3>
      <CurrencySelector
        value={selectedCurrency}
        currencies={mockCurrencies}
        onChange={handleCurrencyChange}
      />
    </div>
  );
}

// 您的应用的入口点
export default function App() {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>Loading...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <MyCurrencySelectorComponent />
    </PaymentProvider>
  );
}
```

在此示例中：
1.  我们定义了一个遵循 `TPaymentCurrency` 结构的 `mockCurrencies` 数组。
2.  `MyCurrencySelectorComponent` 使用 `useState` 钩子来跟踪 `selectedCurrency`。
3.  `handleCurrencyChange` 函数在选择新货币时更新状态，并记录新值。
4.  `CurrencySelector` 是一个受控组件，其 `value` 和 `onChange` props 由父组件的状态管理。
5.  整个组件被包裹在 `PaymentProvider` 中，以确保正确渲染并访问用于样式的 Material-UI 主题。