Widget Light 事件

Widget Light 提供了一套类型化的事件系统，让你可以对用户交互、路由执行进度、钱包变化等做出响应。事件通过 postMessage 从 widget iframe 转发到你的主机应用。

订阅事件

使用 useWidgetLightEvents() 钩子获取事件发射器，然后用 on 订阅、用 off 取消订阅：

import {
  useWidgetLightEvents,
  WidgetLightEvent,
} from '@lifi/widget-light'
import { useEffect } from 'react'

function TransactionTracker() {
  const events = useWidgetLightEvents()

  useEffect(() => {
    const onCompleted = (data: unknown) => {
      console.log('Route completed:', data)
    }
    events.on(WidgetLightEvent.RouteExecutionCompleted, onCompleted)
    return () => {
      events.off(WidgetLightEvent.RouteExecutionCompleted, onCompleted)
    }
  }, [events])

  return null
}

关键细节

模块级单例 — 事件总线是一个模块级单例，因此 useWidgetLightEvents() 可以从任何组件调用。它不需要与 <LiFiWidgetLight> 放在一起，也不需要任何 provider 包裹。
按订阅跟踪的转发 — 只有当至少有一个主机端监听器订阅时，事件才会从 iframe 转发。当你调用 events.on(eventName, handler) 时，主机会向 iframe 发送一条 WIDGET_EVENT_SUBSCRIBE 消息。当某个事件的最后一个监听器被移除时，主机会发送 WIDGET_EVENT_UNSUBSCRIBE。这避免了不必要的 postMessage 流量。
稳定引用 — useWidgetLightEvents() 返回的发射器是一个稳定的模块级对象。你无需对其进行 memoize，也无需将其添加到依赖数组中（尽管这样做是安全的）。

跟踪路由执行

一个常见的用例是跟踪交换或桥接路由的生命周期：

import {
  useWidgetLightEvents,
  WidgetLightEvent,
  type WidgetLightRouteExecutionUpdate,
} from '@lifi/widget-light'
import { useEffect } from 'react'

function RouteTracker() {
  const events = useWidgetLightEvents()

  useEffect(() => {
    const onStart = (data: unknown) => {
      console.log('Route started:', data)
    }
    const onUpdate = (data: WidgetLightRouteExecutionUpdate) => {
      console.log('Step updated:', data.route, data.action)
    }
    const onComplete = (data: unknown) => {
      console.log('Route completed:', data)
    }
    const onFail = (data: WidgetLightRouteExecutionUpdate) => {
      console.error('Route failed:', data.route, data.action)
    }

    events.on(WidgetLightEvent.RouteExecutionStarted, onStart)
    events.on(WidgetLightEvent.RouteExecutionUpdated, onUpdate)
    events.on(WidgetLightEvent.RouteExecutionCompleted, onComplete)
    events.on(WidgetLightEvent.RouteExecutionFailed, onFail)

    return () => {
      events.off(WidgetLightEvent.RouteExecutionStarted, onStart)
      events.off(WidgetLightEvent.RouteExecutionUpdated, onUpdate)
      events.off(WidgetLightEvent.RouteExecutionCompleted, onComplete)
      events.off(WidgetLightEvent.RouteExecutionFailed, onFail)
    }
  }, [events])

  return null
}

事件参考

路由执行事件

事件	Payload 类型	说明
`RouteExecutionStarted`	`unknown`	某个路由已开始执行
`RouteExecutionUpdated`	`WidgetLightRouteExecutionUpdate`	步骤进度更新（包含 `route` 和 `action`）
`RouteExecutionCompleted`	`unknown`	路由成功完成
`RouteExecutionFailed`	`WidgetLightRouteExecutionUpdate`	路由执行失败（包含 `route` 和 `action`）
`RouteSelected`	`WidgetLightRouteSelected`	用户选择了某个路由（包含 `route` 和 `routes` 数组）
`RouteHighValueLoss`	`WidgetLightRouteHighValueLoss`	在某个路由上检测到高价值损失

表单和选择事件

事件	Payload 类型	说明
`SourceChainTokenSelected`	`WidgetLightChainTokenSelected`	源链/代币发生变化（包含 `chainId` 和 `tokenAddress`）
`DestinationChainTokenSelected`	`WidgetLightChainTokenSelected`	目标链/代币发生变化（包含 `chainId` 和 `tokenAddress`）
`FormFieldChanged`	`WidgetLightFormFieldChanged`	任何表单字段发生变化（包含 `fieldName`、`newValue`、`oldValue`）
`TokenSearch`	`WidgetLightTokenSearch`	用户搜索了某个代币（包含 `value` 和 `tokens`）

钱包事件

事件	Payload 类型	说明
`WalletConnected`	`WidgetLightWalletConnected`	钱包已连接（包含 `address`、`chainId`、`chainType`、`connectorId`、`connectorName`）
`WalletDisconnected`	`WidgetLightWalletDisconnected`	钱包已断开连接（包含 `chainType` 以及可选的 `address`、`chainId`、`connectorId`、`connectorName`）

UI 事件

事件	Payload 类型	说明
`PageEntered`	`string`	用户导航到某个页面（页面名称为字符串）
`WidgetExpanded`	`boolean`	widget 展开或收起（drawer 变体）
`SendToWalletToggled`	`boolean`	发送到钱包的开关发生变化
`AvailableRoutes`	`unknown[]`	路由已获取并可用
`ContactSupport`	`WidgetLightContactSupport`	用户点击了联系支持（包含可选的 `supportId`）

设置和偏好事件

事件	Payload 类型	说明
`SettingUpdated`	`WidgetLightSettingUpdated`	用户更改了某项设置（包含 `setting`、`newValue`、`oldValue`、`newSettings`、`oldSettings`）
`ChainPinned`	`WidgetLightChainPinned`	链被固定或取消固定（包含 `chainId` 和 `pinned`）
`LowAddressActivityConfirmed`	`WidgetLightLowAddressActivityConfirmed`	低活跃度地址已确认（包含 `address` 和 `chainId`）

Payload 类型

所有 payload 类型都从 @lifi/widget-light 导出：

import type {
  WidgetLightRouteExecutionUpdate,
  WidgetLightRouteSelected,
  WidgetLightRouteHighValueLoss,
  WidgetLightChainTokenSelected,
  WidgetLightFormFieldChanged,
  WidgetLightWalletConnected,
  WidgetLightWalletDisconnected,
  WidgetLightContactSupport,
  WidgetLightSettingUpdated,
  WidgetLightChainPinned,
  WidgetLightTokenSearch,
  WidgetLightLowAddressActivityConfirmed,
} from '@lifi/widget-light'

携带路由的 payload（WidgetLightRouteExecutionUpdate、WidgetLightRouteSelected）对 route 字段使用 unknown，因为来自 @lifi/sdk 的完整路由类型在 Widget Light 的零依赖类型系统中不可用。如果你需要对路由属性进行类型化访问，请将其转换为你本地的 @lifi/sdk 类型。

WidgetLightEvent 枚举

所有事件名称都可以通过 WidgetLightEvent 枚举获取：

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

// Use enum values for type-safe event names
events.on(WidgetLightEvent.RouteExecutionCompleted, handler)

// Or use string literals directly
events.on('routeExecutionCompleted', handler)

枚举成员	字符串值
`WidgetLightEvent.AvailableRoutes`	`'availableRoutes'`
`WidgetLightEvent.ChainPinned`	`'chainPinned'`
`WidgetLightEvent.ContactSupport`	`'contactSupport'`
`WidgetLightEvent.DestinationChainTokenSelected`	`'destinationChainTokenSelected'`
`WidgetLightEvent.FormFieldChanged`	`'formFieldChanged'`
`WidgetLightEvent.LowAddressActivityConfirmed`	`'lowAddressActivityConfirmed'`
`WidgetLightEvent.PageEntered`	`'pageEntered'`
`WidgetLightEvent.RouteExecutionCompleted`	`'routeExecutionCompleted'`
`WidgetLightEvent.RouteExecutionFailed`	`'routeExecutionFailed'`
`WidgetLightEvent.RouteExecutionStarted`	`'routeExecutionStarted'`
`WidgetLightEvent.RouteExecutionUpdated`	`'routeExecutionUpdated'`
`WidgetLightEvent.RouteHighValueLoss`	`'routeHighValueLoss'`
`WidgetLightEvent.RouteSelected`	`'routeSelected'`
`WidgetLightEvent.SendToWalletToggled`	`'sendToWalletToggled'`
`WidgetLightEvent.SettingUpdated`	`'settingUpdated'`
`WidgetLightEvent.SourceChainTokenSelected`	`'sourceChainTokenSelected'`
`WidgetLightEvent.TokenSearch`	`'tokenSearch'`
`WidgetLightEvent.WidgetExpanded`	`'widgetExpanded'`
`WidgetLightEvent.WalletConnected`	`'walletConnected'`
`WidgetLightEvent.WalletDisconnected`	`'walletDisconnected'`

入门

基本设置

高级

Widget Light (iframe)

其他

Widget Light 事件

订阅事件

关键细节

跟踪路由执行

事件参考

路由执行事件

表单和选择事件

钱包事件

UI 事件

设置和偏好事件

Payload 类型

WidgetLightEvent 枚举

​订阅事件

​关键细节

​跟踪路由执行

​事件参考

​路由执行事件

​表单和选择事件

​钱包事件

​UI 事件

​设置和偏好事件

​Payload 类型

​WidgetLightEvent 枚举

订阅事件

关键细节

跟踪路由执行

事件参考

路由执行事件

表单和选择事件

钱包事件

UI 事件

设置和偏好事件

Payload 类型

WidgetLightEvent 枚举