> ## 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.

# 配置 Widget Light

> @lifi/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](/widget/overview)。

## 必需配置

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

```tsx theme={"system"}
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 模式的选项 |

```tsx theme={"system"}
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 属性：

```tsx theme={"system"}
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 和路由行为：

```tsx theme={"system"}
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 支持 |

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

### 允许/拒绝列表

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

```tsx theme={"system"}
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`

```tsx theme={"system"}
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 |

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

### 国际化

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

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

```tsx theme={"system"}
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：

```tsx theme={"system"}
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 会应用新配置而无需完整重新加载，并保留任何进行中的状态。