配置 Widget Light

Widget Light 配置以 WidgetLightConfig 对象的形式传递给 <LiFiWidgetLight> 的 config prop。所有配置都必须可 JSON 序列化，因为它是通过 postMessage 发送到 iframe 的。

JSON 序列化约束

由于配置通过 postMessage（使用结构化克隆算法）跨越 iframe 边界，以下内容在 WidgetLightConfig 中不受支持：

React 节点或 JSX 元素
回调函数
类实例
MUI 主题对象（palette、colorSchemes、shape、typography、components）

WidgetLightConfig 是完整 widget 配置的一个精选子集，仅暴露可序列化的字段 — 上述不可序列化的选项根本不属于该类型，因此传入它们会导致 TypeScript 错误。这是通过省略字段来实现约束，而非一种通用的可序列化性守卫，因此请确保你确实传入的任何嵌套值在运行时都是可 JSON 序列化的。如果你需要包括 React 节点和 MUI 主题在内的完整配置能力，请改用完整 widget。

必需配置

唯一必填的字段是 integrator，它在 LI.FI 分析中标识你的项目：

import type { WidgetLightConfig } from '@lifi/widget-light'

const config: WidgetLightConfig = {
  integrator: 'your-project-name',
}

配置参考

布局

字段	类型	说明
`variant`	`'compact' \| 'wide' \| 'drawer'`	widget 布局变体
`mode`	`'default' \| 'split' \| 'custom' \| 'refuel'`	widget 模式
`modeOptions`	`WidgetModeOptions`	split 和 custom 模式的选项

const config: WidgetLightConfig = {
  integrator: 'my-app',
  variant: 'wide',
  mode: 'split',
  modeOptions: {
    split: { defaultTab: 'bridge' },
  },
}

外观

字段	类型	说明
`appearance`	`'light' \| 'dark' \| 'system'`	配色方案偏好
`theme`	`WidgetTheme`	基于 CSS 的主题覆盖（见下文）

theme 对象支持针对特定容器的 CSS 属性。这不是 MUI 主题 — 只接受可序列化的 CSS 属性：

const config: WidgetLightConfig = {
  integrator: 'my-app',
  appearance: 'dark',
  theme: {
    container: {
      border: '1px solid #eaeaea',
      borderRadius: '16px',
    },
    header: {
      background: '#f5f5f5',
    },
    navigation: {
      edge: true,
    },
  },
}

WidgetTheme 字段：

字段	类型	说明
`container`	CSS 属性	widget 容器的样式
`routesContainer`	CSS 属性	路由列表容器的样式
`chainSidebarContainer`	CSS 属性	链侧边栏的样式（wide 变体）
`header`	CSS 属性	widget 头部的样式
`navigation`	`{ edge?: boolean }`	导航布局选项

链和代币选择

字段	类型	说明
`fromChain`	`number`	预选的源链 ID
`toChain`	`number`	预选的目标链 ID
`fromToken`	`string`	预选的源代币地址
`toToken`	`string`	预选的目标代币地址
`fromAmount`	`number \| string`	预填的源金额
`toAmount`	`number \| string`	预填的目标金额
`minFromAmountUSD`	`number`	以美元计的最低源金额
`toAddress`	`WidgetToAddress`	预填的目标地址
`toAddresses`	`WidgetToAddress[]`	可选择的目标地址列表
`formUpdateKey`	`string`	用于强制表单更新的键

API 和手续费

字段	类型	说明
`apiKey`	`string`	你的 LI.FI API 密钥
`feeConfig`	`WidgetFeeConfig`	手续费配置
`referrer`	`string`	推荐方标识符

WidgetFeeConfig 字段：

字段	类型	默认值	说明
`name`	`string`	—	手续费的显示名称
`logoURI`	`string`	—	手续费的 Logo URL
`fee`	`number`	—	手续费百分比（0 到 1）
`showFeePercentage`	`boolean`	`false`	以百分比形式显示手续费
`showFeeTooltip`	`boolean`	`false`	显示信息提示框

路由

字段	类型	说明
`routePriority`	`'RECOMMENDED' \| 'FASTEST' \| 'CHEAPEST' \| 'SAFEST'`	默认路由排序优先级
`slippage`	`number`	默认滑点容忍度
`showSingleRoute`	`boolean`	仅显示推荐路由并隐藏路由选择器
`useRelayerRoutes`	`boolean`	启用无 gas/中继（relayer）路由

SDK 配置

sdkConfig 字段控制 API 和路由行为：

const config: WidgetLightConfig = {
  integrator: 'my-app',
  sdkConfig: {
    apiUrl: 'https://li.quest/v1',
    routeOptions: {
      maxPriceImpact: 0.4,
      bridges: { allow: ['stargate', 'across'] },
      exchanges: { deny: ['dodo'] },
    },
    rpcUrls: {
      1: ['https://your-eth-rpc.com'],
      137: ['https://your-polygon-rpc.com'],
    },
  },
}

WidgetSDKConfig 字段：

字段	类型	说明
`apiUrl`	`string`	自定义 LI.FI API URL
`userId`	`string`	用于跟踪的用户标识符
`rpcUrls`	`Record<number, string[]>`	每个链 ID 的自定义 RPC URL
`routeOptions`	`WidgetRouteOptions`	路由选项（见下文）
`preloadChains`	`boolean`	在初始化时预加载链数据
`chainsRefetchInterval`	`number`	链数据重新获取的间隔（毫秒）

WidgetRouteOptions 字段：

字段	类型	说明
`maxPriceImpact`	`number`	可接受的最大价格影响
`allowSwitchChain`	`boolean`	允许在执行期间切换链
`allowDestinationCall`	`boolean`	允许目标链合约调用
`bridges`	`{ allow?, deny?, prefer? }`	桥接的允许/拒绝/优先列表
`exchanges`	`{ allow?, deny?, prefer? }`	交易所的允许/拒绝/优先列表
`jitoBundle`	`boolean`	为 Solana 启用 Jito bundle 支持

fee、referrer、order 和 slippage 在 sdkConfig.routeOptions 中不可用。请改用顶层的 feeConfig、referrer、routePriority 和 slippage 配置字段。

允许/拒绝列表

过滤哪些链、代币、桥接和交易所可用：

const config: WidgetLightConfig = {
  integrator: 'my-app',
  chains: {
    allow: [1, 137, 42161],          // Only show these chains
    from: { allow: [1, 137] },       // Source chain filter
    to: { deny: [56] },              // Destination chain filter
    types: { allow: ['EVM', 'SVM'] }, // Filter by chain type
  },
  tokens: {
    featured: [{ chainId: 1, address: '0x...', symbol: 'USDC', decimals: 6, name: 'USD Coin' }],
    allow: [{ chainId: 1, address: '0x...' }],
    deny: [{ chainId: 1, address: '0x...' }],
  },
  bridges: {
    allow: ['stargate', 'across'],
  },
  exchanges: {
    deny: ['dodo'],
  },
}

UI 控制

控制哪些 UI 元素可见、被禁用或必填。每个选项使用一个对象配置，其中键是 UI 元素名称，值是布尔值：

字段	类型	说明
`hiddenUI`	`WidgetHiddenUIConfig`	要隐藏的 UI 元素
`disabledUI`	`WidgetDisabledUIConfig`	要禁用的 UI 元素（可见但不可交互）
`requiredUI`	`WidgetRequiredUIConfig`	必须先填写才能继续的 UI 元素
`defaultUI`	`WidgetDefaultUI`	默认 UI 状态覆盖

hiddenUI 键： appearance、drawerCloseButton、history、language、poweredBy、toAddress、fromToken、toToken、walletMenu、integratorStepDetails、reverseTokensButton、routeTokenDescription、routeCardPriceImpact、chainSelect、chainSidebar、bridgesSettings、addressBookConnectedWallets、lowAddressActivityConfirmation、gasRefuelMessage、searchTokenInput、insufficientGasMessage、contactSupport、hideSmallBalances、allNetworks disabledUI 键： fromAmount、fromToken、toAddress、toToken requiredUI 键： toAddress、accountDeployedMessage

const config: WidgetLightConfig = {
  integrator: 'my-app',
  hiddenUI: { appearance: true, language: true, poweredBy: true },
  disabledUI: { toAddress: true },
  requiredUI: { toAddress: true },
  defaultUI: {
    transactionDetailsExpanded: true,
    navigationHeaderTitleNoWrap: false,
  },
}

钱包配置

字段	类型	说明
`walletConfig.walletEcosystemsOrder`	`Record<string, WidgetChainType[]>`	自定义钱包生态系统排序
`walletConfig.usePartialWalletManagement`	`boolean`	启用部分钱包管理
`walletConfig.forceInternalWalletManagement`	`boolean`	强制使用 widget 的内部钱包 UI

当你向组件传入 onConnect 时，walletConfig.useExternalWalletManagement 字段会被自动设置。你无需手动设置它。

国际化

字段	类型	说明
`languages`	`WidgetLanguages`	语言配置
`languageResources`	`WidgetLanguageResources`	自定义翻译字符串

支持的语言键：en、es、fr、de、it、pt、ja、ko、zh、hi、bn、th、vi、tr、uk、id、pl

const config: WidgetLightConfig = {
  integrator: 'my-app',
  languages: {
    default: 'de',
    allow: ['en', 'de', 'fr'],
  },
}

杂项

字段	类型	说明
`buildUrl`	`boolean`	将 widget 状态同步到 URL 参数
`keyPrefix`	`string`	本地存储键的前缀
`explorerUrls`	`Record<number, WidgetExplorerUrl[]>`	每条链的自定义区块浏览器 URL
`poweredBy`	`'default' \| 'jumper'`	”Powered by” 品牌变体
`routeLabels`	`WidgetRouteLabelRule[]`	为匹配特定条件的路由添加自定义标签
`contractCalls`	`WidgetContractCall[]`	用于 custom 模式的合约调用
`contractTool`	`WidgetContractTool`	合约调用的工具品牌

响应式配置更新

配置是响应式的。当你传入一个新的 config 对象时，widget 会实时更新而无需重新加载 iframe：

import { LiFiWidgetLight } from '@lifi/widget-light'
import type { WidgetLightConfig } from '@lifi/widget-light'
import { useMemo, useState } from 'react'

const baseConfig: WidgetLightConfig = {
  integrator: 'my-app',
}

function App() {
  const [variant, setVariant] = useState<'wide' | 'compact'>('wide')

  const widgetConfig = useMemo(
    () => ({ ...baseConfig, variant }),
    [variant]
  )

  return (
    <>
      <button onClick={() => setVariant('compact')}>Compact</button>
      <button onClick={() => setVariant('wide')}>Wide</button>
      <LiFiWidgetLight config={widgetConfig} handlers={handlers} />
    </>
  )
}

在初始握手之后，配置更改会通过 CONFIG_UPDATE 消息发送到 iframe。widget 会应用新配置而无需完整重新加载，并保留任何进行中的状态。

入门

基本设置

高级

Widget Light (iframe)

其他

配置 Widget Light

JSON 序列化约束

必需配置

配置参考

布局

外观

链和代币选择

API 和手续费

路由

SDK 配置

允许/拒绝列表

UI 控制

钱包配置

国际化

杂项

响应式配置更新

​JSON 序列化约束

​必需配置

​配置参考

​布局

​外观

​链和代币选择

​API 和手续费

​路由

​SDK 配置

​允许/拒绝列表

​UI 控制

​钱包配置

​国际化

​杂项

​响应式配置更新

JSON 序列化约束

必需配置

配置参考

布局

外观

链和代币选择

API 和手续费

路由

SDK 配置

允许/拒绝列表

UI 控制

钱包配置

国际化

杂项

响应式配置更新