react-pp-bundle/README.md

Polaris组件库扩展包

# PPBundle

基于 Shopify Polaris 的 React 组件库扩展包

## 安装

```bash
npm i react-pp-bundle@latest -S
```

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build
```

## 使用手册

### PBProvide 组件

`PBProvide` 是一个全局 Provider 组件，主要用于提供国际化功能。

#### 使用方法

```tsx
import { PBProvide } from 'ppbundle'

function App() {
  return (
    <PBProvide 
      language="zh-CN"  // 设置语言
    >
      {/* 你的应用内容 */}
    </PBProvide>
  )
}
```

#### 参数说明

| 参数     | 类型      | 必填 | 说明                               |
| -------- | --------- | ---- | ---------------------------------- |
| language | string    | 是   | 设置语言，支持 'zh-CN'、'en-US' 等 |
| children | ReactNode | 是   | 子组件                             |

### PBPage 组件

`PBPage` 是一个用于展示和管理套餐订阅的页面组件，支持多个应用（Tracking/Returns）的套餐管理，包含价格周期切换、套餐选择等功能。

#### 使用方法

```tsx
import { PBPage } from 'ppbundle'

function SubscriptionPage() {
  const [period, setPeriod] = useState(1); // 1: 月付, 2: 年付
  const [data, setData] = useState<PkgListData | null>(null);
  
  const handleAction = (action: PBPageAction, actionData: ActionData) => {
    // 处理用户操作，如订阅、升级等
  }

  return (
    <PBPage
      data={data}
      setData={setData}
      period={period}
      setPeriod={setPeriod}
      app={APPEnum.Tracking}
      onAction={handleAction}
    />
  )
}
```

#### 参数说明

| 参数            | 类型                                             | 必填 | 说明                         |
| --------------- | ------------------------------------------------ | ---- | ---------------------------- |
| data            | PkgListData \| null                              | 是   | 套餐数据                     |
| setData         | (data: PkgListData) => void                      | 是   | 更新套餐数据的方法           |
| period          | number                                           | 是   | 付费周期（1: 月付, 2: 年付） |
| setPeriod       | (period: number) => void                         | 是   | 更新付费周期的方法           |
| app             | APPEnum                                          | 是   | 应用类型（Tracking/Returns） |
| onAction        | (action: PBPageAction, data: ActionData) => void | 是   | 用户操作回调函数             |
| loading         | boolean                                          | 否   | 加载状态                     |
| btnLoading      | boolean                                          | 否   | 按钮加载状态                 |
| btnDisabled     | boolean                                          | 否   | 按钮禁用状态                 |
| isStandardWidth | boolean                                          | 否   | 是否使用标准宽度，默认 true  |
| perferKind      | PackageKindEnum                                  | 否   | 默认套餐类型                 |
| perferPlanId    | number                                           | 否   | 默认套餐 ID                  |

#### 类型定义

```typescript
enum APPEnum {
  Tracking = 1,
  Returns = 2
}

enum PackageKindEnum {
  Essential = 1,
  Professional = 2,
  Enterprise = 3
}

interface ActionData {
  pbData: any;
  period: number;
  data: PkgListData;
  plans: Array<{
    app_id: APPEnum;
    plan_id: number;
  }>;
}
```

### PBToggle 组件

`PBToggle` 是一个自定义的切换组件，支持多个选项的切换，并提供了两种预设样式。

#### 基础用法

```tsx
import { PBToggle } from 'ppbundle'

function Demo() {
  const [value, setValue] = useState('option1')
  
  const options = [
    { value: 'option1', label: '选项1' },
    { value: 'option2', label: '选项2' },
  ]

  return (
    <PBToggle
      options={options}
      value={value}
      onChange={setValue}
    />
  )
}
```

#### 使用预设样式

PPBundle 提供了两种预设样式的 Toggle 组件：

```tsx
import { PBAppToggle, PBPeriodToggle } from 'ppbundle'

// 蓝色主题的 Toggle
function AppDemo() {
  return <PBAppToggle {...props} />
}

// 绿色主题的 Toggle
function PeriodDemo() {
  return <PBPeriodToggle {...props} />
}
```

#### 参数说明

| 参数      | 类型                               | 必填 | 说明               |
| --------- | ---------------------------------- | ---- | ------------------ |
| options   | Array<{value: any, label: string}> | 是   | 选项配置数组       |
| value     | any                                | 是   | 当前选中的值       |
| onChange  | (value: any) => void               | 是   | 值变化时的回调函数 |
| className | string                             | 否   | 自定义类名         |

#### 自定义样式

可以使用 `withCustomColorsToggle` 高阶组件创建自定义样式的 Toggle：

```tsx
import { withCustomColorsToggle } from 'ppbundle'

const MyCustomToggle = withCustomColorsToggle({
  '--pb-toggle-text-color-active': '#FFFFFF',
  '--pb-toggle-box-bg': 'linear-gradient(...)',
  '--pb-toggle-bg-active': 'linear-gradient(...)',
})
```

### getDevToken 方法

`getDevToken` 是一个用于获取开发环境认证 token 的工具方法。

#### 使用方法

```tsx
import { getDevToken } from 'ppbundle'

async function example() {
  const tokenParams = {
    // 填写必要参数
  }
  
  try {
    const token = await getDevToken(tokenParams)
    // 使用获取到的 token
  } catch (error) {
    // 处理错误
  }
}
```

#### 参数说明

| 参数 | 类型                     | 必填 | 说明                                |
| ---- | ------------------------ | ---- | ----------------------------------- |
| data | Omit<TokenParams, "pwd"> | 是   | Token 请求参数，不需要包含 pwd 字段 |

#### 返回值

返回一个 Promise，解析为带有 "Bearer " 前缀的 token 字符串。

### 注意事项

1. `PBProvide` 组件应该放在应用的最外层，以确保所有子组件都能访问到国际化功能。
2. `PBToggle` 组件的 value 值应该与 options 中的 value 值对应。
3. `getDevToken` 方法仅用于开发环境，不要在生产环境中使用。