Widget Light API 参考

@lifi/widget-light 所有导出项的完整 API 参考。

`<LiFiWidgetLight>`

在 iframe 内渲染 widget 并管理 postMessage 桥接的主组件。

import { LiFiWidgetLight } from '@lifi/widget-light'

Props

Prop	类型	是否必填	默认值	说明
`src`	`string`	否	`'https://widget.li.fi'`	托管的 widget iframe 的 URL
`config`	`WidgetLightConfig`	是	—	可 JSON 序列化的 widget 配置（参考）
`handlers`	`IframeEcosystemHandler[]`	否	`[]`	用于钱包/RPC 桥接的生态系统处理器
`iframeOrigin`	`string`	否	从 `src` 派生	将 `postMessage` 限制到此来源
`autoResize`	`boolean`	否	`false`	当为 `true` 时，iframe 高度自动调整以匹配内容
`onConnect`	`(args?: ConnectWalletArgs) => void`	否	—	当 widget 请求连接钱包时调用
`style`	`CSSProperties`	否	—	iframe 元素的内联样式
`className`	`string`	否	—	iframe 元素的 CSS 类
`title`	`string`	否	`'LI.FI Widget'`	iframe 的无障碍标题

示例

<LiFiWidgetLight
  config={{ integrator: 'my-app', variant: 'wide' }}
  handlers={[ethHandler, solHandler]}
  autoResize
  style={{ width: 392, borderRadius: 16 }}
/>

每个页面仅支持一个 <LiFiWidgetLight> 实例。事件总线和 guest bridge 是模块级单例。

`useWidgetLightHost(options)`

管理 postMessage 桥接主机端的底层钩子。如果你需要渲染自己的 <iframe> 元素而非使用 <LiFiWidgetLight> 组件，请使用它。

import { useWidgetLightHost } from '@lifi/widget-light'

Options

Option	类型	是否必填	默认值	说明
`config`	`WidgetLightConfig`	是	—	widget 配置
`handlers`	`IframeEcosystemHandler[]`	否	`[]`	生态系统处理器
`iframeOrigin`	`string`	否	`'*'`	用于消息过滤的预期 iframe 来源
`autoResize`	`boolean`	否	`false`	通过 RESIZE 消息启用自动调整大小
`onConnect`	`(args?: ConnectWalletArgs) => void`	否	—	外部钱包连接回调

返回值

字段	类型	说明
`iframeRef`	`RefObject<HTMLIFrameElement \| null>`	附加到你的 `<iframe>` 元素的 ref

示例

import { useWidgetLightHost } from '@lifi/widget-light'
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'
import { useMemo } from 'react'

function CustomIframeSetup() {
  const ethHandler = useEthereumIframeHandler()
  const handlers = useMemo(() => [ethHandler], [ethHandler])

  const { iframeRef } = useWidgetLightHost({
    config: { integrator: 'my-app', fromChain: 1, toChain: 137 },
    handlers,
    iframeOrigin: 'https://widget.li.fi',
    autoResize: true,
  })

  return (
    <iframe
      ref={iframeRef}
      src="https://widget.li.fi"
      title="LI.FI Widget"
      style={{ border: 'none', width: 392, height: 640 }}
      allow="clipboard-write"
    />
  )
}

`useWidgetLightEvents()`

返回一个类型化的事件发射器，用于订阅 widget 事件。可以从任何组件调用 — 无需 provider 包裹。

import { useWidgetLightEvents } from '@lifi/widget-light'

返回值

interface WidgetLightEventEmitter {
  on<E extends keyof WidgetLightEvents>(
    event: E,
    handler: (data: WidgetLightEvents[E]) => void
  ): void
  off<E extends keyof WidgetLightEvents>(
    event: E,
    handler: (data: WidgetLightEvents[E]) => void
  ): void
}

示例

const events = useWidgetLightEvents()

useEffect(() => {
  const handler = (data: WidgetLightChainTokenSelected) => {
    console.log('Token selected:', data.chainId, data.tokenAddress)
  }
  events.on(WidgetLightEvent.SourceChainTokenSelected, handler)
  return () => events.off(WidgetLightEvent.SourceChainTokenSelected, handler)
}, [events])

完整的事件参考请见 Widget Light 事件。

类型

WidgetLightChainType 与 WidgetChainType： 这两个联合类型都描述生态系统的判别标识，并包含用于 Tron 的 TVM。在 iframe 的 postMessage 协议中使用 WidgetLightChainType（例如 IframeEcosystemHandler.chainType）。在面向主机的配置类型（例如 ConnectWalletArgs.chainType，即托管的 widget 告知你的应用要连接哪个生态系统）中使用 WidgetChainType。这两个名称之所以不同，是因为协议层级的类型和配置层级的类型在包中是分开定义的。

`WidgetLightConfig`

主配置类型。必须可 JSON 序列化。完整参考请见配置 Widget Light。

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

必填字段：integrator: string

`ConnectWalletArgs`

当 widget 请求连接钱包时传递给 onConnect 回调的参数：

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

字段	类型	说明
`chainId`	`number \| undefined`	目标链 ID
`chainType`	`WidgetChainType \| undefined`	目标链类型（`'EVM'`、`'SVM'`、`'UTXO'`、`'MVM'`、`'TVM'`）

`IframeEcosystemHandler`

由所有生态系统处理器实现的接口：

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

方法	类型	说明
`chainType`	`WidgetLightChainType`	`'EVM' \| 'SVM' \| 'UTXO' \| 'MVM' \| 'TVM'`
`getInitState()`	`EcosystemInitState \| null`	返回用于 INIT 握手的初始钱包状态
`handleRequest(id, method, params?)`	`Promise<unknown>`	处理来自 iframe 的 RPC 请求
`subscribe(emit)`	`() => void`	订阅钱包状态变化；返回取消订阅函数

`WidgetLightEvent`

所有事件名称的枚举。其取值和 payload 类型请见 Widget Light 事件。

import { WidgetLightEvent } from '@lifi/widget-light'

`WidgetLightChainType`

用于 postMessage 协议的链类型判别标识：

type WidgetLightChainType = 'EVM' | 'SVM' | 'UTXO' | 'MVM' | 'TVM'

`WidgetChainType`

用于配置的扩展链类型（包含 TVM）：

type WidgetChainType = 'EVM' | 'SVM' | 'MVM' | 'UTXO' | 'TVM'

FAQ

不可以。@lifi/widget-light 对事件总线和 guest bridge 使用模块级单例。每个页面仅支持一个 <LiFiWidgetLight> 实例。

`src` 应该使用什么 URL？

默认值（https://widget.li.fi）是生产环境托管的 widget。在大多数用例中，你完全不需要设置 src。若要针对特定版本或自托管的部署进行测试，请将你的自定义 URL 作为 src 传入。

为什么 config 必须可 JSON 序列化？

配置通过 postMessage 发送到 iframe，而 postMessage 使用结构化克隆算法。React 节点、函数、类实例和 MUI 主题对象无法被克隆。WidgetLightConfig 类型只暴露可序列化的字段（不含 React 节点、回调或 MUI 主题对象），因此类型系统会在编译时拒绝大多数不可序列化的值。这是通过省略字段来实现约束，而非一种通用的可序列化性检查，因此仍要确保你传入的任何值在运行时都是可 JSON 序列化的。

自动调整大小是如何工作的？

当 autoResize 为 true 时，iframe 内容使用 ResizeObserver 检测高度变化并将其发布到主机。主机直接设置 iframe.style.height 以实现零闪烁的更新。如果你想自行通过 CSS 控制 iframe 尺寸，请设置 autoResize={false}。

页面刷新后我需要处理重新连接吗？

在每次挂载时，钱包状态会通过 INIT 握手从你的应用发送到 iframe。如果你的 wagmi/wallet-adapter 处理重新连接（大多数默认情况下都会），widget 将自动接收到重新连接后的状态。

安全性是如何处理的？

iframeOrigin 会自动从 src 派生（默认为 https://widget.li.fi），因此 postMessage 通信被限制到正确的来源。来自其他来源的消息会被静默丢弃。只有当你想覆盖派生出的值时，才需要显式设置 iframeOrigin。

我在哪里可以找到可运行的示例？

widget 仓库包含两个示例：

vite-iframe-wagmi — 最小化的仅 EVM 集成
vite-iframe — 完整的多生态系统设置，包含事件、配置响应式和外部钱包管理

在本地运行它们：

# From the widget repository root
pnpm install
pnpm --filter vite-iframe-wagmi dev
# or
pnpm --filter vite-iframe dev

入门

基本设置

高级

Widget Light (iframe)

其他

Widget Light API 参考

`<LiFiWidgetLight>`

Props

示例

`useWidgetLightHost(options)`

Options

返回值

示例

`useWidgetLightEvents()`

返回值

示例

类型

`WidgetLightConfig`

`ConnectWalletArgs`

`IframeEcosystemHandler`

`WidgetLightEvent`

`WidgetLightChainType`

`WidgetChainType`

FAQ

我可以在同一页面上运行多个 widget 吗？

`src` 应该使用什么 URL？

为什么 config 必须可 JSON 序列化？

自动调整大小是如何工作的？

页面刷新后我需要处理重新连接吗？

安全性是如何处理的？

我在哪里可以找到可运行的示例？

​<LiFiWidgetLight>

​Props

​示例

​useWidgetLightHost(options)

​Options

​返回值

​示例

​useWidgetLightEvents()

​返回值

​示例

​类型

​WidgetLightConfig

​ConnectWalletArgs

​IframeEcosystemHandler

​WidgetLightEvent

​WidgetLightChainType

​WidgetChainType

​FAQ

​我可以在同一页面上运行多个 widget 吗？

​src 应该使用什么 URL？

​为什么 config 必须可 JSON 序列化？

​自动调整大小是如何工作的？

​页面刷新后我需要处理重新连接吗？

​安全性是如何处理的？

​我在哪里可以找到可运行的示例？

`<LiFiWidgetLight>`

Props

示例

`useWidgetLightHost(options)`

Options

返回值

示例

`useWidgetLightEvents()`

返回值

示例

类型

`WidgetLightConfig`

`ConnectWalletArgs`

`IframeEcosystemHandler`

`WidgetLightEvent`

`WidgetLightChainType`

`WidgetChainType`

FAQ

我可以在同一页面上运行多个 widget 吗？

`src` 应该使用什么 URL？

为什么 config 必须可 JSON 序列化？

自动调整大小是如何工作的？

页面刷新后我需要处理重新连接吗？

安全性是如何处理的？

我在哪里可以找到可运行的示例？