> ## 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.
# 从 v2 迁移到 v3
> LI.FI 组件 v2 升级到 v3 的迁移指南
## 概述
**LI.FI 组件 v3** 对其核心进行了全面改革，增强了与流行账户管理库（如 [Wagmi](https://wagmi.sh/) 和 [RainbowKit](https://www.rainbowkit.com/)）的兼容性，并整合了许多新功能，包括从 [Solana](https://github.com/anza-xyz/wallet-adapter) 开始的多生态系统支持。因此，有一些破坏性更改和弃用需要注意，如本指南中概述的。此外，我们鼓励您阅读更新的文档，其中包含此处未提及的新功能。
要开始使用，请安装最新版本的组件。
```typescript yarn theme={"system"}
yarn add @lifi/widget
```
```typescript pnpm theme={"system"}
pnpm add @lifi/widget
```
```typescript bun theme={"system"}
bun add @lifi/widget
```
```typescript npm theme={"system"}
npm install @lifi/widget
```
## 配置
### 重命名的变体
以下组件变体被重命名以更好地反映其功能：
`default` 现在是 `compact`
`expandable` 现在是 `wide`
有关更多详细信息，请参见[选择组件变体](https://docs.li.fi/integrate-li.fi-widget/select-widget-variants)。
### 更新的 toAddress 类型
在组件 v3 中，我们更新了目标钱包功能，包括钱包书签、最近使用的地址等。以前，`toAddress` 选项的类型是 `string`。为了在 v3 中扩展功能，我们为此字段添加了特定类型。
```typescript theme={"system"}
// Widget v2
interface WidgetConfig {
// ...
toAddress?: string;
// ...
}
// Widget v3
interface ToAddress {
name?: string;
address: string;
chainType: ChainType;
logoURI?: string;
}
interface WidgetConfig {
// ...
toAddress?: ToAddress;
// ...
}
```
### Updated subvariantOptions type
In Widget v3 we extended the functionality of subvariants and `subvariantOptions` required type update. Previously, `subvariantOptions` supported only `split` subvariant and had `SplitSubvariantOptions` type and now we added support for `custom` subvariant with possibly more subvariant options coming 中 future.
```typescript theme={"system"}
// Widget v2
type SplitSubvariantOptions = 'bridge' | 'swap';
interface WidgetConfig {
// ...
subvariantOptions?: SplitSubvariantOptions;
// ...
}
// Widget v3
type SplitSubvariant = 'bridge' | 'swap';
type CustomSubvariant = 'checkout' | 'deposit';
interface SubvariantOptions {
split?: SplitSubvariant;
custom?: CustomSubvariant;
}
interface WidgetConfig {
// ...
subvariantOptions?: SubvariantOptions;
// ...
}
```
### SDK configuration
Following the release of LI.FI SDK v3 there are some changes to SDK configuration 中 widget.
`SDKConfig` type is now `WidgetSDKConfig`.
`defaultRouteOptions` renamed to `routeOptions`.
### Removed pre-built drawer button
Previously in Widget v2 there were two ways of controlling the drawer. The first one was pre-built button which came with drawer variant to open and close it. The second one was hiding the button via `hiddenUI` option and controlling the drawer by attaches the ref. Since the title and positioning often required some adjustments we decided to remove pre-built drawer button in favor of controlling the drawer with external button.
Here is the example of controlling the drawer with ref and you can customize the button as you like.
```typescript theme={"system"}
export const WidgetPage = () => {
const drawerRef = useRef(null);
const toggleWidget = () => {
drawerRef.current?.toggleDrawer();
};
return (
);
}
```
We also removed `HiddenUI.DrawerButton` option since there is no default button anymore. However, we added a new option `HiddenUI.DrawerCloseButton` to hide the close button inside the drawer.
### Theming
In Widget v3, we revamped customization and theming possibilities and did a small cleanup.
The top-level `containerStyle` option is moved under the umbrella of the `theme` option and was renamed to `container`.
```typescript theme={"system"}
// Widget v2
export const WidgetPage = () => {
return (
);
};
// Widget v3
export const WidgetPage = () => {
return (
);
};
```
Also, `theme` option type was renamed from `ThemeConfig` to `WidgetTheme`.
Please check out more in [自定义组件](https://docs.li.fi/integrate-li.fi-widget/customize-widget) section.
### Miscellaneous
`disableLanguageDetector` configuration option was removed. Language detection should now be inherited from the integration dApp.
## 钱包管理
### Moved from Ethers.js to Wagmi
We dropped support for Ethers.js. Instead, Widget now has a first-class Wagmi and all Wagmi-based libraries support like RainbowKit. You can still use Ethers.js in your project and convert Signer/Provider object to use Wagmi's [injected](https://wagmi.sh/react/api/connectors/injected) connector before wrapping the Widget with [WagmiProvider](https://wagmi.sh/react/api/WagmiProvider). However, we suggest moving your dApp's wallet management to use Wagmi as a more future proof solution.
#### Widget v2 setup with Ethers.js
```typescript theme={"system"}
import { LiFiWidget, WidgetConfig } from '@lifi/widget';
export const WidgetPage = () => {
const { account, connect, disconnect, switchChain } = useWallet();
const widgetConfig = useMemo((): WidgetConfig => {
return {
walletManagement: {
signer: account.signer,
connect: async () => {
const signer = await connect();
return signer;
},
disconnect: async () => {
await disconnect();
},
switchChain: async (chainId: number) => {
await switchChain(chainId);
if (account.signer) {
return account.signer;
} else {
throw Error('No signer object is found after the chain switch.');
}
},
},
};
}, [account.signer, connect, disconnect, switchChain]);
return (
);
}
```
#### Widget v3 setup with Wagmi
No more complicated callbacks, just wrap the Widget in `WagmiProvider` and you are set. If you already have one in your dApp, just make sure to keep the Wagmi chains configuration in sync with the Widget chain list, so all functionality like switching chains can keep working.
See [钱包管理](https://docs.li.fi/integrate-li.fi-widget/wallet-management) for more details.
```typescript theme={"system"}
import { LiFiWidget } from '@lifi/widget';
import { createClient } from 'viem';
import { WagmiProvider, createConfig, http } from 'wagmi';
import { mainnet } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';
const wagmiConfig = createConfig({
// Make sure to provide the full list of chains
// you would like to support in the Widget
// and keep them in sync, so all functionality
// like switching chains can work correctly.
chains: [mainnet],
connectors: [injected()],
client({ chain }) {
return createClient({ chain, transport: http() });
},
});
export const WidgetPage = () => {
return (
);
};
```
### Updated wallet management configuration
Since we don't need to provide callbacks and signers to widget configuration, `walletManagement` option was renamed to `walletConfig` and now has the following interface:
```typescript theme={"system"}
interface WidgetWalletConfig {
// Can be used to open the external wallet menu,
// if the user is not connected and dApp uses external wallet management
onConnect(): void;
// Provide your projectId and other WalletConnect properties
// when using Widget's internal wallet management
walletConnect?: WalletConnectParameters;
// Provide your app name and other Coinbase properties
// when using Widget's internal wallet management
coinbase?: CoinbaseWalletParameters;
}
```
## Dependencies
### Wagmi is a new peer dependency
Since we moved from `ethers.js` to `Wagmi` we added it to our peer dependencies.
### Dropped CommonJS support
LI.FI Widget v3 no longer publishes a separate CommonJS build since most of the modern front-end tooling supports ESM and ESM is the future. See [Sindre Sorhus' guide](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) for more info about switching to ESM.