> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 从 v3 迁移到 v4

> LI.FI Widget 从 v3 升级到 v4 的迁移指南

## 概述

**LI.FI Widget v4** 引入了模块化的提供者架构、基于 TanStack Router 的内部路由改进，以及对 Ethereum、Solana、Bitcoin、Sui 和 Tron 链增强的多生态系统支持。本指南涵盖所有破坏性变更和迁移步骤。

### v4 的新特性

除了下面的破坏性变更外，v4 还新增了：

* **模块化提供者** — 只需为你需要的生态系统安装 `@lifi/widget-provider-*` 包；核心 widget 不再打包钱包栈。
* **TanStack Router** — 组件内导航使用 TanStack Router，而不再使用 react-router 兼容层。
* **wagmi v3** — 使用 `@lifi/widget-provider-ethereum` 时，Ethereum 流程与 wagmi 及 `@wagmi/core` v3 保持一致。
* **Tron (TVM)** — 通过 `@lifi/widget-provider-tron` 及配套的 Widget Light 处理器提供完整的 Tron 支持。
* **Widget Light** — 持续改进 iframe 集成层面（配置、事件、多链处理器）。

要开始使用，请安装最新版本的 Widget。

```bash theme={"system"}
# Core widget only
pnpm add @lifi/widget @tanstack/react-query

# With blockchain providers (recommended)
pnpm add @lifi/widget @lifi/widget-provider-ethereum @lifi/widget-provider-solana @lifi/widget-provider-bitcoin @lifi/widget-provider-sui @lifi/widget-provider-tron wagmi @wagmi/core @bigmi/react bs58 @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks @tanstack/react-query
```

***

## 提供者架构（最大的变化）

### 新的提供者包

Widget v4 引入了模块化的提供者系统。widget 不再在内部创建所有钱包提供者，你现在需要显式安装和配置仅你所需的提供者包：

| 包                                | 生态系统 | 对等依赖                                               |
| -------------------------------- | ---- | -------------------------------------------------- |
| `@lifi/widget-provider-ethereum` | EVM  | `wagmi` ^3, `@wagmi/core` ^3                       |
| `@lifi/widget-provider-solana`   | SVM  | `bs58` >=4.0.1                                     |
| `@lifi/widget-provider-bitcoin`  | UTXO | `@bigmi/react` ^0.8.0                              |
| `@lifi/widget-provider-sui`      | MVM  | `@mysten/dapp-kit-react` ^2.0.0                    |
| `@lifi/widget-provider-tron`     | TVM  | `@tronweb3/tronwallet-adapter-react-hooks` ^1.1.11 |

其他配套包：

| 包                       | 说明                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@lifi/widget-provider` | 带有 hooks（`useBitcoinContext`、`useEthereumContext`、`useSolanaContext`、`useSuiContext`、`useTronContext`）和 `isWalletInstalled` 的基础提供者抽象 |

### 核心 Widget 对等依赖已变更

**Widget v3** 核心具有区块链特定的对等依赖：`wagmi ^2`、`@bigmi/react`、`@mysten/dapp-kit`、`@solana/wallet-adapter-react`。

**Widget v4** 核心只需要：`react >=19`、`react-dom >=19`、`@tanstack/react-query >=5.90.0`。

区块链特定的对等依赖现在位于各个提供者包上。

### 配置提供者

**Widget v3** - 依赖单独安装，提供者自动检测：

```typescript theme={"system"}
// Widget v3
import { LiFiWidget } from '@lifi/widget';
import { WagmiProvider } from 'wagmi';

export const WidgetPage = () => {
  return (
    <WagmiProvider config={wagmiConfig}>
      <LiFiWidget integrator="your-dapp" />
    </WagmiProvider>
  );
};
```

**Widget v4** - 使用新的 `providers` 配置选项：

```typescript theme={"system"}
// Widget v4
import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { EthereumProvider } from '@lifi/widget-provider-ethereum';
import { SolanaProvider } from '@lifi/widget-provider-solana';
import { BitcoinProvider } from '@lifi/widget-provider-bitcoin';
import { SuiProvider } from '@lifi/widget-provider-sui';
import { TronProvider } from '@lifi/widget-provider-tron';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider(),
    SolanaProvider(),
    BitcoinProvider(),
    SuiProvider(),
    TronProvider(),
  ],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="your-dapp" config={widgetConfig} />;
};
```

如果你只需要 EVM 支持，则只需安装 `@lifi/widget-provider-ethereum`：

```typescript theme={"system"}
import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [EthereumProvider()],
};
```

### EthereumProvider 配置

钱包连接器选项已从 `walletConfig` 移至 `EthereumProvider`：

**Widget v3：**

```typescript theme={"system"}
// Widget v3
const widgetConfig: WidgetConfig = {
  walletConfig: {
    walletConnect: {
      projectId: 'your-project-id',
    },
    coinbase: {
      appName: 'Your App',
    },
  },
};
```

**Widget v4：**

```typescript theme={"system"}
// Widget v4
import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      walletConnect: {
        projectId: 'your-project-id',
      },
      coinbase: {
        appName: 'Your App',
      },
      metaMask: {
        // MetaMask SDK options
      },
      porto: {
        // Porto connector options (EIP-7702)
      },
      baseAccount: {
        // Base Account options
      },
    }),
  ],
};
```

### Wagmi v2 到 v3

Widget v4 需要 **Wagmi v3**（在 Widget v3 中为 v2）。如果你使用外部 Wagmi 设置，则必须将 Wagmi 升级到 v3。详情请参阅 [Wagmi v3 迁移指南](https://wagmi.sh/react/guides/migrate-from-v2-to-v3)。

### Sui 包变更

Sui 对等依赖从 `@mysten/dapp-kit` 变更为 `@mysten/dapp-kit-react` ^2.0.0：

```bash theme={"system"}
# Remove old package
pnpm remove @mysten/dapp-kit

# Install new package
pnpm add @mysten/dapp-kit-react
```

相应地更新你代码中的任何导入。

***

## 导入变更

### 移动的导出

若干导出已移至新的包中：

| 导出                         | v3 包                      | v4 包                             |
| -------------------------- | ------------------------- | -------------------------------- |
| `createDefaultWagmiConfig` | `@lifi/wallet-management` | `@lifi/widget-provider-ethereum` |
| `createDefaultBigmiConfig` | `@lifi/wallet-management` | `@lifi/widget-provider-bitcoin`  |
| `useSyncWagmiConfig`       | `@lifi/wallet-management` | `@lifi/widget-provider-ethereum` |
| `isWalletInstalled`        | `@lifi/wallet-management` | `@lifi/widget-provider`          |

### 重命名的 Hooks

```typescript theme={"system"}
// Widget v3
import { useAvailableChains } from '@lifi/widget';
const { chains } = useAvailableChains();

// Widget v4
import { useWidgetChains } from '@lifi/widget';
import type { WidgetConfig } from '@lifi/widget';
const widgetConfig: WidgetConfig = { integrator: 'your-dapp' };
const { chains } = useWidgetChains(widgetConfig);
```

`useWidgetChains` 接受一个 `WidgetConfig` 参数（用于创建获取链的 SDK 客户端）。

***

## 钱包配置

### 更新的 WidgetWalletConfig

钱包配置接口已简化。连接器特定的选项（`walletConnect`、`coinbase`、`metaMask`、`baseAccount`、`porto`）已移至 `EthereumProvider`：

**Widget v3：**

```typescript theme={"system"}
// Widget v3
interface WidgetWalletConfig {
  onConnect(): void
  walletConnect?: WalletConnectParameters
  coinbase?: CoinbaseWalletParameters
}
```

**Widget v4：**

```typescript theme={"system"}
// Widget v4
interface WidgetWalletConfig {
  onConnect?(args?: WalletMenuOpenArgs): void
  walletEcosystemsOrder?: Record<string, ChainType[]>
  usePartialWalletManagement?: boolean
  forceInternalWalletManagement?: boolean
}
```

### disableMessageSigning 已移动

`disableMessageSigning` 已从 `sdkConfig.executionOptions` 移至 `EthereumProvider` 配置：

```typescript theme={"system"}
// Widget v3
const widgetConfig: WidgetConfig = {
  sdkConfig: {
    executionOptions: {
      disableMessageSigning: true,
    },
  },
};

// Widget v4
import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      disableMessageSigning: true,
    }),
  ],
};
```

### SDK 执行选项

`sdkConfig.executionOptions` 已精简。`disableMessageSigning` 和 `getContractCalls` 已被移除。仅保留 `updateTransactionRequestHook`：

```typescript theme={"system"}
// Widget v4
interface WidgetSDKConfig {
  executionOptions?: {
    updateTransactionRequestHook?: (request: TransactionRequest) => Promise<TransactionRequest>
  }
}
```

***

## 路由变更

### 内部路由迁移

Widget v4 在内部使用 **TanStack Router**，而不再使用 React Router v6。这是一项内部变更，不应影响大多数集成。

**如果你在应用中使用 React Router：**

无需特殊配置。widget 的内部路由完全隔离。

**Widget v3** - 需要通配符路由：

```typescript theme={"system"}
// Widget v3 - React Router needed special handling
<BrowserRouter>
  <Routes>
    <Route path="/swap/*" element={<LiFiWidgetPage />} />
  </Routes>
</BrowserRouter>
```

**Widget v4** - 无需特殊路由配置：

```typescript theme={"system"}
// Widget v4 - Standard routes work fine
<BrowserRouter>
  <Routes>
    <Route path="/swap" element={<LiFiWidgetPage />} />
  </Routes>
</BrowserRouter>
```

***

## 导航路由变更

导航路由名称已更新：

```typescript theme={"system"}
// Widget v3
navigationRoutes.activeTransactions  // 'active-transactions'
navigationRoutes.transactionHistory  // 'transaction-history'

// Widget v4
navigationRoutes.activities          // 'activities' (replaces both)
```

`transactionHistory` 已被完全移除并合并到 `activities` 中。

***

## WidgetConfig 变更

### Subvariant 重命名为 Mode

`subvariant` 现在为 `mode`，`subvariantOptions` 现在为 `modeOptions`。所有相关类型都已重命名：

```typescript theme={"system"}
// Widget v3
const widgetConfig: WidgetConfig = {
  subvariant: 'split',
  subvariantOptions: {
    split: 'bridge',
  },
};

// Widget v4
const widgetConfig: WidgetConfig = {
  mode: 'split',
  modeOptions: {
    split: 'bridge',
  },
};
```

| v3                       | v4                 |
| ------------------------ | ------------------ |
| `subvariant`             | `mode`             |
| `subvariantOptions`      | `modeOptions`      |
| `WidgetSubvariant`       | `WidgetMode`       |
| `SplitSubvariant`        | `SplitMode`        |
| `SplitSubvariantOptions` | `SplitModeOptions` |
| `SubvariantOptions`      | `ModeOptions`      |
| `CustomSubvariant`       | `CustomMode`       |

### 自定义 Mode 选项已重构

`custom` mode 选项现在是一个带 `type` 字段的对象。`'fund'` 值已被移除：

```typescript theme={"system"}
// Widget v3
subvariantOptions: {
  custom: 'checkout',  // string shorthand
}

// Widget v4
modeOptions: {
  custom: { type: 'checkout' },  // object with type field
}
```

### 宽屏变体的链侧边栏已移至 HiddenUI

链侧边栏选项已从 `modeOptions` 移至 `hiddenUI`：

```typescript theme={"system"}
// Widget v3
subvariantOptions: {
  wide: {
    disableChainSidebar: true,
  },
}

// Widget v4
hiddenUI: {
  chainSidebar: true,  // Hide the chain sidebar in wide variant
}
```

### UI 控件从数组改为对象

`disabledUI`、`hiddenUI` 和 `requiredUI` 现在使用对象配置，而不再使用枚举数组：

```typescript theme={"system"}
// Widget v3
import { DisabledUI, HiddenUI } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  disabledUI: [DisabledUI.ToAddress],
  hiddenUI: [HiddenUI.Appearance, HiddenUI.Language, HiddenUI.PoweredBy],
};

// Widget v4
const widgetConfig: WidgetConfig = {
  disabledUI: { toAddress: true },
  hiddenUI: { appearance: true, language: true, poweredBy: true },
};
```

`DisabledUI`、`HiddenUI` 和 `RequiredUI` 枚举已被 `DisabledUIConfig`、`HiddenUIConfig` 和 `RequiredUIConfig` 接口取代。

### useRecommendedRoute 重命名为 showSingleRoute

```typescript theme={"system"}
// Widget v3
const widgetConfig: WidgetConfig = {
  useRecommendedRoute: true,
};

// Widget v4
const widgetConfig: WidgetConfig = {
  showSingleRoute: true,
};
```

### 移除了顶层 fee

顶层的 `fee` 简写已被移除。请改用 `feeConfig.fee`：

```typescript theme={"system"}
// Widget v3
const widgetConfig: WidgetConfig = {
  fee: 0.03,
};

// Widget v4
const widgetConfig: WidgetConfig = {
  feeConfig: {
    fee: 0.03,
  },
};
```

### SDK 路由选项受限

`fee`、`referrer`、`order` 和 `slippage` 不能再通过 `sdkConfig.routeOptions` 传递。请改用顶层配置字段（`feeConfig`、`referrer`、`routePriority`、`slippage`）。

### Split Mode 选项增强

`split` mode 现在支持带 `defaultTab` 的对象形式：

```typescript theme={"system"}
// New in v4 - both tabs with configurable default
modeOptions: {
  split: { defaultTab: 'swap' },
}
```

***

## 事件变更

### 事件总线迁移到 eventemitter3

内部事件总线已从 `mitt` 迁移到 `eventemitter3`。事件类型签名现在使用回调函数：

```typescript theme={"system"}
// Widget v3 (mitt-style)
type WidgetEvents = {
  availableRoutes: Route[]
  routeExecutionStarted: Route
}

// Widget v4 (eventemitter3-style)
type WidgetEvents = {
  availableRoutes: (data: Route[]) => void
  routeExecutionStarted: (data: Route) => void
}
```

`on`/`off` 订阅 API 保持不变——此更改仅影响自定义类型声明。

### WalletConnected 事件已移动

`walletConnected` 事件已从 `WidgetEvents` 移至 `@lifi/wallet-management` 包中的 `WalletManagementEvents`。事件类型也已更改——所有字段现在都是必需的，并新增了两个字段：

```typescript theme={"system"}
// Widget v3
interface WalletConnected {
  address?: string
  chainId?: number
  chainType?: ChainType
}

// Widget v4
import { useWalletManagementEvents, WalletManagementEvent } from '@lifi/wallet-management';
import type { WalletConnected } from '@lifi/wallet-management';

interface WalletConnected {
  address: string
  chainId: number
  chainType: ChainType
  connectorId: string
  connectorName: string
}
```

### TokensReversed 事件已移除

`WidgetEvent.TokensReversed` 已被完全移除。

### RouteExecutionUpdate 类型已更改

`RouteExecutionUpdate` 类型现在使用 `action`（类型为 `ExecutionAction`），而不再使用 `process`（类型为 `Process`）：

```typescript theme={"system"}
// Widget v3
type RouteExecutionUpdate = {
  route: Route
  process: Process
}

// Widget v4
type RouteExecutionUpdate = {
  route: Route
  action: ExecutionAction
}
```

更新任何访问 `process` 属性的事件处理器：

```typescript theme={"system"}
// Widget v3
widgetEvents.on(WidgetEvent.RouteExecutionUpdated, (update) => {
  console.log(update.process);
});

// Widget v4
widgetEvents.on(WidgetEvent.RouteExecutionUpdated, (update) => {
  console.log(update.action);
});
```

### ReviewTransactionPageEntered 已弃用

`WidgetEvent.ReviewTransactionPageEntered` 已被弃用。请改用 `WidgetEvent.PageEntered`，它会在所有页面导航时触发，并带有 `NavigationRouteType` 载荷。

***

## SDK v4 依赖

Widget v4 依赖于 LI.FI SDK v4，它有自己的破坏性变更：

* `createConfig` 现在为 `createClient`
* `Process` 类型现在为 `ExecutionAction`

这些变更主要影响上面所述的事件类型。如果你在使用 widget 的同时直接使用 SDK，请查阅 [SDK 迁移指南](/sdk/migrate-v3-to-v4)。

***

## 快速迁移检查清单

1. **更新包**：安装 `@lifi/widget` v4 以及你需要的提供者包
2. **将 `providers` 添加到配置中**：通过 `config.providers` 传入 `EthereumProvider()`、`SolanaProvider()` 等
3. **移动钱包连接器配置**：将 `walletConnect`、`coinbase` 等从 `walletConfig` 移至 `EthereumProvider({...})`
4. **移动 `disableMessageSigning`**：从 `sdkConfig.executionOptions` 移至 `EthereumProvider({ disableMessageSigning: true })`
5. **升级 Wagmi 到 v3**（如果使用外部 Wagmi 设置）
6. **更新 Sui 包**：用 `@mysten/dapp-kit-react` 替换 `@mysten/dapp-kit`
7. **更新 `useAvailableChains`**：替换为 `useWidgetChains(widgetConfig)`
8. **更新 `useSyncWagmiConfig` 导入**：从 `@lifi/wallet-management` 改为 `@lifi/widget-provider-ethereum`
9. **更新 `createDefaultWagmiConfig` 导入**：从 `@lifi/wallet-management` 改为 `@lifi/widget-provider-ethereum`
10. **将 `subvariant` 重命名为 `mode`**，并将 `subvariantOptions` 重命名为 `modeOptions`
11. **更新自定义 mode 选项**：将 `custom: 'checkout'` 改为 `custom: { type: 'checkout' }`
12. **移动链侧边栏配置**：从 `subvariantOptions.wide.disableChainSidebar` 移至 `hiddenUI: { chainSidebar: true }`
13. **将 UI 控件更新为对象配置**：将 `disabledUI: [DisabledUI.X]` 替换为 `disabledUI: { x: true }`，`hiddenUI` 和 `requiredUI` 同理
14. **将 `useRecommendedRoute` 重命名**为 `showSingleRoute`
15. **将顶层 `fee` 替换**为 `feeConfig: { fee: 0.03 }`
16. **从 `sdkConfig.routeOptions` 中移除 `fee`/`referrer`/`order`/`slippage`**：改用顶层配置字段
17. **修复事件处理器**：在路由执行事件处理器中，将 `update.process` 替换为 `update.action`
18. **移除 `TokensReversed` 事件**：如果已订阅，请移除该处理器
19. **更新 `walletConnected` 事件**：现在位于 `WalletManagementEvents` 中，而非 `WidgetEvents`
20. **更新导航路由**：将 `activeTransactions`/`transactionHistory` 替换为 `activities`
21. **移除 `'fund'` 自定义 mode**：如果使用，请替换为 `'checkout'` 或 `'deposit'`
22. **移除 React Router 通配符**：widget 路由不再需要它