@edgex-web/components

⚠️ Beta 版本警告: 这是一个 Beta 版本，功能还在完善中，仅用于测试和开发环境。

EdgeX Universal UI Components Library - Reusable React components for deposit, withdraw and other common UI patterns

🎯 项目概述

基于 RFC FE-01 设计，EdgeX Components 是一个独立的 npm 包，旨在解决 EdgeX 项目中 deposit/withdraw 组件 70% 代码重复的问题。采用事件驱动架构，支持全局调用能力。

✨ 特性

• 🚀 现代化技术栈: TypeScript + React + Vite
• 📦 独立 npm 包: 可在任何 React 项目中使用
• 🎪 事件驱动: 支持全局调用 openDeposit() / openWithdraw()
• 🔗 MPC 钱包支持: 链-代币关联，智能代币切换
• 🎨 主题配置: 支持 light/dark 主题切换
• 🌍 国际化: 多语言支持
• 🧪 高测试覆盖: 目标 85%+ 测试覆盖率
• 📚 完整文档: API 文档和使用指南

📦 安装

Beta 版本 (推荐用于测试)

# 使用 npm
npm install @edgex-web/components@beta

# 使用 yarn
yarn add @edgex-web/components@beta

# 使用 pnpm
pnpm add @edgex-web/components@beta

稳定版本 (暂未发布)

# 使用 npm
npm install @edgex-web/components

# 使用 yarn
yarn add @edgex-web/components

# 使用 pnpm
pnpm add @edgex-web/components

🏗️ 技术架构

edgex-components/
├── src/
│   ├── components/          # React 组件
│   │   ├── Provider/        # 全局配置提供者
│   │   ├── Deposit/         # 充值组件
│   │   └── Withdraw/        # 提现组件
│   ├── hooks/               # React Hooks
│   ├── types/               # TypeScript 类型定义
│   └── test/                # 测试配置
├── dev/                     # 开发环境
└── dist/                    # 构建输出

🚀 快速开始

安装依赖

# 使用 yarn (推荐)
yarn install

# 或使用 npm
npm install

开发模式

# 启动开发服务器
yarn dev

# 访问 http://localhost:5173 查看组件演示

构建

# 构建生产版本
yarn build

# 类型检查
yarn type-check

# 运行测试
yarn test

# 测试覆盖率
yarn test:coverage

# 代码检查
yarn lint

# 代码格式化
yarn format

📖 使用方法

基本用法

import React from 'react'
import { ComponentProvider, useDeposit, useWithdraw } from '@edgex-web/components'

// 1. 在应用根组件配置 Provider
const App = () => {
  const config = {
    theme: 'light',
    locale: 'en',
    apiBaseUrl: 'https://api.edgex.com',
    debug: true
  }

  return (
    <ComponentProvider config={config}>
      <YourApp />
    </ComponentProvider>
  )
}

// 2. 在任意组件中使用
const TradeComponent = () => {
  const { openDeposit } = useDeposit()
  const { openWithdraw } = useWithdraw()

  const handleDeposit = () => {
    openDeposit({
      type: 'trade',
      symbol: 'USDT',
      onSuccess: (result) => console.log('Success:', result),
      onError: (error) => console.error('Error:', error),
      onCancel: () => console.log('Cancelled')
    })
  }

  return <button onClick={handleDeposit}>充值</button>
}

事件驱动 API (推荐)

import React from 'react'
import {
  DepositManager,
  openDeposit,
  closeDeposit,
  MPCChainTokenSelector
} from '@edgex-web/components'

// 1. 在应用根组件添加 DepositManager
function App() {
  return (
    <div>
      <YourAppContent />
      <DepositManager />
    </div>
  )
}

// 2. 在任意位置调用
function MyComponent() {
  const handleDeposit = () => {
    openDeposit({
      curSelectToken: 'USDT',
      depositAmount: '100',
      onDeposit: async () => {
        console.log('Deposit initiated!')
      }
    })
  }

  return <button onClick={handleDeposit}>Open Deposit</button>
}

MPC 钱包链-代币关联

import React, { useState } from 'react'
import { MPCChainTokenSelector, type ChainWithTokens } from '@edgex-web/components'

// 定义链-代币关联数据
const mpcChainList: ChainWithTokens[] = [
  {
    chainId: 1,
    chain: 'Ethereum',
    chainIconUrl: 'https://static.edgex.exchange/icons/logo/ethereum.svg',
    allowDeposit: true,
    blockTime: 12,
    txConfirm: 12,
    tokenList: [
      {
        token: 'USDT',
        symbol: 'USDT',
        iconUrl: 'https://static.edgex.exchange/icons/coin/USDT.svg',
        decimals: 6,
        tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
      },
    ],
  },
  {
    chainId: 42161,
    chain: 'Arbitrum',
    chainIconUrl: 'https://static.edgex.exchange/icons/logo/arbitrum.svg',
    allowDeposit: true,
    blockTime: 1,
    txConfirm: 1,
    tokenList: [
      {
        token: 'USDT',
        symbol: 'USDT',
        iconUrl: 'https://static.edgex.exchange/icons/coin/USDT.svg',
        decimals: 6,
        tokenAddress: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
      },
      {
        token: 'USDC',
        symbol: 'USDC',
        iconUrl: 'https://static.edgex.exchange/icons/coin/USDC.svg',
        decimals: 6,
        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
      },
    ],
  },
]

function MPCWalletComponent() {
  const [currentChainId, setCurrentChainId] = useState(1)
  const [currentToken, setCurrentToken] = useState('USDT')

  const currentActiveChain = mpcChainList.find(
    chain => chain.chainId === currentChainId
  ) || mpcChainList[0]

  return (
    <MPCChainTokenSelector
      currentActiveChain={currentActiveChain}
      chainList={mpcChainList}
      onChainChange={setCurrentChainId}
      curSelectToken={currentToken}
      onTokenChange={setCurrentToken}
      t={(key) => key} // 翻译函数
    />
  )
}

🛠️ 开发工具链

已配置的工具

• 构建工具: Vite 5.x + Rollup
• 类型系统: TypeScript 5.x
• 测试框架: Vitest + Testing Library
• 代码质量: ESLint + Prettier
• Git Hooks: Husky + lint-staged
• 包管理: 支持 npm/yarn/pnpm

脚本命令

| 命令 | 描述 | |------|------| | yarn dev | 启动开发服务器 | | yarn build | 构建生产版本 | | yarn test | 运行测试 | | yarn test:coverage | 生成测试覆盖率报告 | | yarn lint | 代码检查 | | yarn format | 代码格式化 | | yarn type-check | TypeScript 类型检查 |

📋 开发状态

✅ 已完成

• [x] 项目基础架构搭建
• [x] TypeScript 配置
• [x] 构建工具配置 (Vite + Rollup)
• [x] 测试框架配置 (Vitest + Testing Library)
• [x] 代码质量工具 (ESLint + Prettier + Husky)
• [x] 基础组件结构
• [x] 开发环境设置
• [x] 核心组件开发 (Deposit/Withdraw)
• [x] 事件驱动系统实现
• [x] MPC 钱包链-代币关联功能
• [x] 智能代币切换逻辑
• [x] 完整测试覆盖
• [x] npm 包发布配置

🚧 进行中

• [ ] API 文档完善
• [ ] 集成指南编写
• [ ] 性能优化

📅 计划中

• [ ] Storybook 集成
• [ ] 更多钱包类型支持
• [ ] 主题系统增强
• [ ] 国际化完善

🎯 RFC FE-01 目标

• 减少代码重复: 从 70% 降至 <10%
• 提升测试覆盖: 达到 85%+
• 统一用户体验: 一致的 UI 和交互
• 全局调用能力: 支持任意位置唤起弹框
• 开发效率: 降低维护成本 60-80%

📄 许可证

MIT License - 详见 LICENSE 文件