Widget API 参考

LiFiWidget 组件配置的属性和类型。

import { LiFiWidget, WidgetConfig } from '@lifi/widget'

const config: WidgetConfig = {
  integrator: 'your-dapp-name',
  // ... other options
}

<LiFiWidget integrator="your-dapp-name" config={config} />

核心配置

名称	类型	默认值	说明
`integrator`	`string`	必填	集成方标识符（dApp/公司名称）
`apiKey`	`string`	–	API 认证密钥
`referrer`	`string`	–	推荐方标识符
`feeConfig`	`WidgetFeeConfig`	–	手续费配置
`providers`	`WidgetProvider[]`	–	区块链 provider 组件数组

表单值（交换详情）

名称	类型	默认值	说明
`fromChain`	`number`	–	源链 ID
`toChain`	`number`	–	目标链 ID
`fromToken`	`string`	–	源代币合约地址
`toToken`	`string`	–	目标代币合约地址
`fromAmount`	`number \| string`	–	交换金额
`toAmount`	`number \| string`	–	预期的目标金额
`toAddress`	`ToAddress`	–	单个目标钱包地址
`toAddresses`	`ToAddress[]`	–	精选的目标地址列表
`minFromAmountUSD`	`number`	–	fromAmount 的最低美元价值
`formUpdateKey`	`string`	–	用于强制更新表单的唯一键

ToAddress 类型

interface ToAddress {
  name?: string        // Display name
  address: string      // Wallet address (required)
  chainType: ChainType // EVM, SVM, UTXO, etc. (required)
  logoURI?: string     // Optional logo
}

路由配置

名称	类型	默认值	说明
`routePriority`	`Order`	`'RECOMMENDED'`	路由选择优先级（`'RECOMMENDED'`、`'CHEAPEST'`、`'FASTEST'`、`'SAFEST'`）
`slippage`	`number`	`undefined`	可选的滑点容差。省略时，Widget 不发送 `slippage` 值，由 API 使用当前适用的服务端默认值。
`showSingleRoute`	`boolean`	`false`	仅显示推荐路由并隐藏路由选择器
`useRelayerRoutes`	`boolean`	`false`	启用无 gas/中继（relayer）路由

过滤选项

链

名称	类型	说明
`chains.allow`	`number[]`	仅允许这些链 ID
`chains.deny`	`number[]`	拒绝这些链 ID
`chains.from.allow`	`number[]`	仅允许作为源链
`chains.from.deny`	`number[]`	拒绝作为源链
`chains.to.allow`	`number[]`	仅允许作为目标链
`chains.to.deny`	`number[]`	拒绝作为目标链
`chains.types.allow`	`ChainType[]`	允许的链类型（EVM、SVM 等）
`chains.types.deny`	`ChainType[]`	拒绝的链类型

interface WidgetChains {
  types?: AllowDeny<ChainType>
  allow?: number[]
  deny?: number[]
  from?: AllowDeny<number>
  to?: AllowDeny<number>
}

代币

名称	类型	说明
`tokens.allow`	`BaseToken[]`	仅允许这些代币
`tokens.deny`	`BaseToken[]`	拒绝这些代币
`tokens.from.allow`	`BaseToken[]`	仅允许作为源代币
`tokens.from.deny`	`BaseToken[]`	拒绝作为源代币
`tokens.to.allow`	`BaseToken[]`	仅允许作为目标代币
`tokens.to.deny`	`BaseToken[]`	拒绝作为目标代币
`tokens.featured`	`StaticToken[]`	精选代币（显示在顶部）
`tokens.include`	`Token[]`	要额外包含的代币
`tokens.popular`	`StaticToken[]`	热门代币板块

interface WidgetTokens {
  featured?: StaticToken[]
  include?: Token[]
  popular?: StaticToken[]
  allow?: BaseToken[]
  deny?: BaseToken[]
  from?: AllowDeny<BaseToken>
  to?: AllowDeny<BaseToken>
}

桥接与交易所

名称	类型	说明
`bridges.allow`	`string[]`	仅允许这些桥接
`bridges.deny`	`string[]`	拒绝这些桥接
`exchanges.allow`	`string[]`	仅允许这些交易所
`exchanges.deny`	`string[]`	拒绝这些交易所

interface AllowDeny<T> {
  allow?: T[]
  deny?: T[]
}

UI 变体

名称	类型	默认值	说明
`variant`	`'compact' \| 'wide' \| 'drawer'`	`'compact'`	widget 布局样式
`mode`	`'default' \| 'split' \| 'custom' \| 'refuel'`	`'default'`	widget 模式
`modeOptions`	`ModeOptions`	–	模式特定选项

ModeOptions

type SplitMode = 'bridge' | 'swap'
type SplitModeOptions = { defaultTab: SplitMode }
type CustomMode = 'checkout' | 'deposit'

interface ModeOptions {
  split?: SplitMode | SplitModeOptions       // For split mode
  custom?: { type: CustomMode }              // For custom mode
}

外观与主题

名称	类型	默认值	说明
`appearance`	`'light' \| 'dark' \| 'system'`	`'system'`	主题模式
`theme`	`WidgetTheme`	–	主题自定义

WidgetTheme

interface WidgetTheme {
  colorSchemes?: {
    light?: { palette: PaletteOptions }
    dark?: { palette: PaletteOptions }
  }
  shape?: Partial<Shape>
  typography?: TypographyVariantsOptions
  components?: WidgetThemeComponents
  container?: CSSProperties
  routesContainer?: CSSProperties
  chainSidebarContainer?: CSSProperties
  header?: CSSProperties
  navigation?: {
    edge?: boolean  // @default true
  }
}

主题组件

type WidgetThemeComponents = Partial<Pick<Components<Theme>,
  | 'MuiAppBar'
  | 'MuiAvatar'
  | 'MuiButton'
  | 'MuiCard'
  | 'MuiDrawer'
  | 'MuiIconButton'
  | 'MuiInputCard'
  | 'MuiNavigationTabs'
  | 'MuiNavigationTab'
  | 'MuiTabs'
  | 'MuiCheckbox'
>>

UI 控制

UI 控制选项使用对象配置，其中每个键是一个 UI 元素，值是一个布尔值。

DisabledUIConfig

禁用特定的 UI 元素（仍可见但不可交互）：

interface DisabledUIConfig {
  fromAmount?: boolean
  fromToken?: boolean
  toAddress?: boolean
  toToken?: boolean
}

HiddenUIConfig

完全隐藏特定的 UI 元素：

interface HiddenUIConfig {
  addressBookConnectedWallets?: boolean
  allNetworks?: boolean
  appearance?: boolean
  bridgesSettings?: boolean
  chainSelect?: boolean
  chainSidebar?: boolean    // Hide chain sidebar in wide variant
  contactSupport?: boolean
  drawerCloseButton?: boolean
  fromToken?: boolean
  gasRefuelMessage?: boolean
  hideSmallBalances?: boolean
  history?: boolean
  insufficientGasMessage?: boolean
  integratorStepDetails?: boolean
  language?: boolean
  lowAddressActivityConfirmation?: boolean
  poweredBy?: boolean
  reverseTokensButton?: boolean
  routeCardPriceImpact?: boolean
  routeTokenDescription?: boolean
  searchTokenInput?: boolean
  toAddress?: boolean
  toToken?: boolean
  walletMenu?: boolean
}

RequiredUIConfig

将特定的 UI 元素设为必填：

interface RequiredUIConfig {
  accountDeployedMessage?: boolean
  toAddress?: boolean
}

DefaultUI

配置默认的 UI 状态：

interface DefaultUI {
  transactionDetailsExpanded?: boolean
  navigationHeaderTitleNoWrap?: boolean
}

国际化

名称	类型	说明
`languages.default`	`LanguageKey`	默认语言
`languages.allow`	`LanguageKey[]`	仅显示这些语言
`languages.deny`	`LanguageKey[]`	隐藏这些语言
`languageResources`	`LanguageResources`	自定义翻译

type LanguageKey = 
  | 'bn' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'id' 
  | 'it' | 'ja' | 'ko' | 'pl' | 'pt' | 'th' | 'tr' 
  | 'uk' | 'vi' | 'zh'

钱包配置

名称	类型	说明
`walletConfig.onConnect`	`(args?: WalletMenuOpenArgs) => void`	连接按钮的回调
`walletConfig.walletEcosystemsOrder`	`Record<string, ChainType[]>`	每个钱包的生态系统顺序
`walletConfig.usePartialWalletManagement`	`boolean`	启用混合钱包管理
`walletConfig.forceInternalWalletManagement`	`boolean`	强制使用内部钱包管理

interface WidgetWalletConfig {
  onConnect?(args?: WalletMenuOpenArgs): void
  walletEcosystemsOrder?: Record<string, ChainType[]>
  usePartialWalletManagement?: boolean  // @default false
  forceInternalWalletManagement?: boolean  // @default false
}

SDK 配置

名称	类型	说明
`sdkConfig.rpcUrls`	`Record<number, string[]>`	每条链的自定义 RPC URL
`sdkConfig.routeOptions`	`RouteOptions`	路由获取选项
`sdkConfig.executionOptions`	`ExecutionOptions`	路由执行选项

interface WidgetSDKConfig {
  rpcUrls?: Record<number, string[]>
  routeOptions?: Omit<RouteOptions, 'bridges' | 'exchanges' | 'fee' | 'referrer' | 'order' | 'slippage'>
  executionOptions?: {
    updateTransactionRequestHook?: (request: TransactionRequest) => Promise<TransactionRequest>
  }
}

在 Widget v4 中，disableMessageSigning 已从 sdkConfig.executionOptions 移至 EthereumProvider 配置。详情参见钱包管理。

手续费配置

名称	类型	说明
`feeConfig.name`	`string`	手续费的显示名称
`feeConfig.logoURI`	`string`	Logo URL
`feeConfig.fee`	`number`	静态手续费（0-1）
`feeConfig.showFeePercentage`	`boolean`	在 UI 中显示手续费百分比
`feeConfig.showFeeTooltip`	`boolean`	显示手续费提示框
`feeConfig.feeTooltipComponent`	`ReactNode`	自定义提示框组件
`feeConfig.calculateFee`	`(params) => Promise<number>`	动态手续费计算

interface WidgetFeeConfig {
  name?: string
  logoURI?: string
  fee?: number
  showFeePercentage?: boolean  // @default false
  showFeeTooltip?: boolean     // @default false
  feeTooltipComponent?: ReactNode
  calculateFee?(params: CalculateFeeParams): Promise<number | undefined>
}

interface CalculateFeeParams {
  fromChain: ExtendedChain
  toChain: ExtendedChain
  fromToken: Token
  toToken: Token
  fromAddress?: string
  toAddress?: string
  fromAmount?: bigint
  toAmount?: bigint
  slippage?: number
}

区块浏览器 URL

名称	类型	说明
`explorerUrls[chainId]`	`ExplorerUrl[]`	每条链的自定义区块浏览器 URL
`explorerUrls.internal`	`ExplorerUrl[]`	覆盖内部区块浏览器

type ExplorerUrl = string | {
  url: string
  txPath?: string      // Default: '/tx/'
  addressPath?: string // Default: '/address/'
}

路由标签

为路由添加自定义标签：

interface RouteLabelRule {
  label: RouteLabel
  bridges?: AllowDeny<string>
  exchanges?: AllowDeny<string>
  fromChainId?: number[]
  toChainId?: number[]
  fromTokenAddress?: string[]
  toTokenAddress?: string[]
  match?: (route: Route) => boolean
}

interface RouteLabel {
  text: string
  sx?: SxProps<Theme>  // MUI style object
}

合约集成

用于自定义结账/存款流程：

名称	类型	说明
`contractCalls`	`ContractCall[]`	要执行的合约调用
`contractComponent`	`ReactNode`	主自定义组件
`contractSecondaryComponent`	`ReactNode`	次要组件
`contractCompactComponent`	`ReactNode`	紧凑视图组件
`contractTool`	`WidgetContractTool`	工具展示信息

interface WidgetContractTool {
  name: string
  logoURI: string
}

表单与 URL 状态

名称	类型	默认值	说明
`buildUrl`	`boolean`	`false`	将 widget 状态同步到 URL
`keyPrefix`	`string`	–	用于多个 widget 实例的前缀
`formRef`	`RefObject<FormState>`	–	用于以编程方式控制表单的 ref

FormState

interface FormState {
  setFieldValue: <K extends FieldNames>(
    key: K,
    value: FieldValues[K],
    options?: { setUrlSearchParam: boolean }
  ) => void
}

type FieldNames = 
  | 'fromChain' | 'toChain' 
  | 'fromToken' | 'toToken'
  | 'fromAmount' | 'toAmount' 
  | 'toAddress'

抽屉属性

用于 variant: 'drawer'：

名称	类型	说明
`open`	`boolean`	受控的打开状态
`onClose`	`() => void`	关闭回调
`elementRef`	`RefObject<HTMLDivElement>`	指向抽屉元素的 ref

WidgetDrawer Ref

interface WidgetDrawer {
  isOpen(): boolean
  toggleDrawer(): void
  openDrawer(): void
  closeDrawer(): void
}

导出的钩子

钩子	说明
`useWidgetEvents`	订阅 widget 事件（返回事件发射器）
`useWidgetChains(config)`	使用 `WidgetConfig` 从 LI.FI API 获取可用链
`useFieldActions`	访问表单字段操作
`useFieldValues`	访问当前的表单字段值

钩子	说明
`useEthereumContext`	访问 Ethereum 钱包上下文
`useSolanaContext`	访问 Solana 钱包上下文
`useBitcoinContext`	访问 Bitcoin 钱包上下文
`useSuiContext`	访问 Sui 钱包上下文
`useTronContext`	访问 Tron 钱包上下文
`isWalletInstalled`	检查是否安装了特定钱包

导出	说明
`EthereumProvider`	返回 Ethereum provider 组件的工厂函数
`createDefaultWagmiConfig`	创建带有常用连接器的默认 Wagmi 配置
`useSyncWagmiConfig`	用于将 Wagmi 配置与 LI.FI 链同步的钩子

导出	说明
`SolanaProvider`	返回 Solana provider 组件的工厂函数
`useWalletAccount`	用于访问 Solana 钱包账户的钩子

导出	说明
`BitcoinProvider`	返回 Bitcoin provider 组件的工厂函数
`createDefaultBigmiConfig`	创建默认的 Bigmi 配置

导出	说明
`SuiProvider`	返回 Sui provider 组件的工厂函数

导出	说明
`TronProvider`	返回 Tron provider 组件的工厂函数
`createTronAdapters`	创建默认的 Tron 钱包适配器

其他选项

名称	类型	默认值	说明
`poweredBy`	`'default' \| 'jumper'`	`'default'`	Powered by 品牌样式
`routeLabels`	`RouteLabelRule[]`	–	自定义路由标签/徽章

​Widget 组件

​核心配置

​表单值（交换详情）

​ToAddress 类型

​路由配置

​过滤选项

​链

​代币

​桥接与交易所

​UI 变体

​ModeOptions

​外观与主题

​WidgetTheme

​主题组件

​UI 控制

​DisabledUIConfig

​HiddenUIConfig

​RequiredUIConfig

​DefaultUI

​国际化

​钱包配置

​SDK 配置

​手续费配置

​区块浏览器 URL

​路由标签

​合约集成

​表单与 URL 状态

​FormState

​抽屉属性

​WidgetDrawer Ref

​导出的钩子

​来自 @lifi/widget

​来自 @lifi/widget-provider

​来自 @lifi/widget-provider-ethereum

​来自 @lifi/widget-provider-solana

​来自 @lifi/widget-provider-bitcoin

​来自 @lifi/widget-provider-sui

​来自 @lifi/widget-provider-tron

​其他选项

Widget 组件

核心配置

表单值（交换详情）

ToAddress 类型

路由配置

过滤选项

链

代币

桥接与交易所

UI 变体

ModeOptions

外观与主题

WidgetTheme

主题组件

UI 控制

DisabledUIConfig

HiddenUIConfig

RequiredUIConfig

DefaultUI

国际化

钱包配置

SDK 配置

手续费配置

区块浏览器 URL

路由标签

合约集成

表单与 URL 状态

FormState

抽屉属性

WidgetDrawer Ref

导出的钩子

来自 `@lifi/widget`

来自 `@lifi/widget-provider`

来自 `@lifi/widget-provider-ethereum`

来自 `@lifi/widget-provider-solana`

来自 `@lifi/widget-provider-bitcoin`

来自 `@lifi/widget-provider-sui`

来自 `@lifi/widget-provider-tron`

其他选项