> ## 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 事件

> 与 widget 事件保持同步

**LI.FI Widget** 提供了一个 `useWidgetEvents` 钩子，让你可以订阅一系列 widget 事件，并帮助你获取有关执行路由的有用信息、跟踪桥接和交换进度、跟踪链和代币的选择、与特定 UI 元素的交互等等。

我们会持续扩展可用的事件，如果你对某个特定事件感兴趣，请通过我们的 [支持](https://help.li.fi) 联系我们。

为了最小化不必要的重新渲染并防止主 Widget 组件中的潜在故障，请在集成主 `LiFiWidget` 的组件之外集成 `useWidgetEvents` 钩子。

订阅 widget 事件的示例：

```typescript theme={"system"}
import type { Route, ExecutionAction } from '@lifi/sdk';
import type { RouteExecutionUpdate, RouteHighValueLossUpdate } from '@lifi/widget';
import { useWidgetEvents, WidgetEvent } from '@lifi/widget';
import { useEffect } from 'react';

export const WidgetEventsExample = () => {
  const widgetEvents = useWidgetEvents();

  // ...

  useEffect(() => {
    const onRouteExecutionStarted = (route: Route) => {
      // console.log('onRouteExecutionStarted fired.');
    };
    const onRouteExecutionUpdated = (update: RouteExecutionUpdate) => {
      // console.log('onRouteExecutionUpdated fired.');
    };
    const onRouteExecutionCompleted = (route: Route) => {
      // console.log('onRouteExecutionCompleted fired.');
    };
    const onRouteExecutionFailed = (update: RouteExecutionUpdate) => {
      // console.log('onRouteExecutionFailed fired.');
    };
    const onRouteHighValueLoss = (update: RouteHighValueLossUpdate) => {
      // console.log('onRouteHighValueLoss continued.');
    };
    
    widgetEvents.on(WidgetEvent.RouteExecutionStarted, onRouteExecutionStarted);
    widgetEvents.on(WidgetEvent.RouteExecutionUpdated, onRouteExecutionUpdated);
    widgetEvents.on(WidgetEvent.RouteExecutionCompleted, onRouteExecutionCompleted);
    widgetEvents.on(WidgetEvent.RouteExecutionFailed, onRouteExecutionFailed);
    widgetEvents.on(WidgetEvent.RouteHighValueLoss, onRouteHighValueLoss);
    
    return () => widgetEvents.removeAllListeners();
  }, [widgetEvents]);

  // ...
  
  // Return null because it's an example
  return null;
};
```

## 事件列表

以下是所有可用事件的列表：

**AvailableRoutes**

* 类型：*Route\[]*

当用户选择了源代币和目标代币、输入了金额并请求路由后，可用路由返回时触发该事件。

**RouteSelected**

* 类型：*RouteSelected*

当用户从可用路由列表中选择某个特定路由时触发该事件。

**RouteExecutionStarted**

* 类型：*Route*

当用户点击 Start swapping 或 Start bridging 按钮时触发该事件。

**RouteExecutionUpdated**

* 类型：*RouteExecutionUpdate*

当执行期间 Route 对象有更新时触发该事件。

**RouteExecutionCompleted**

* 类型：*Route*

当执行成功完成时触发该事件。

**RouteExecutionFailed**

* 类型：*RouteExecutionUpdate*

当执行失败时触发该事件。

**RouteHighValueLoss**

* 类型：*RouteHighValueLossUpdate*

当屏幕上出现 High Value Loss 底部弹层时触发该事件。

**ContactSupport**

* 类型：*ContactSupport*

当用户在交易详情页面点击 Contact support 按钮时触发该事件。

**SourceChainTokenSelected**

* 类型：*ChainTokenSelected*

当用户选择源链和代币时触发该事件。

**DestinationChainTokenSelected**

* 类型：*ChainTokenSelected*

当用户选择目标链和代币时触发该事件。

**SendToWalletToggled**

* 类型：*boolean*

当用户点击主页上操作按钮旁边的钱包图标以显示/隐藏目标钱包选择 UI 时触发该事件。

**WidgetExpanded**

* 类型：*boolean*

当向用户展示带有路由的侧边面板时触发该事件。仅在 `wide` widget 变体中可用。

**PageEntered**

* 类型：*NavigationRouteType*

当用户导航到 widget 中的某个页面时触发该事件。

**FormFieldChanged**

* 类型：*FormFieldChanged*

每当 widget 中的表单值发生变化时触发该事件。

**SettingUpdated**

* 类型：*SettingUpdated*

每当 widget 中的某项设置被更新时触发该事件。

**TokenSearch**

* 类型：*TokenSearch*

当用户搜索代币时触发该事件（包含查询值和匹配到的代币结果）。

**LowAddressActivityConfirmed**

* 类型：*LowAddressActivityConfirmed*

当用户在收到指定地址和链的低地址活跃度警告后，仍确认继续时触发该事件。

**ChainPinned**

* 类型：*ChainPinned*

当用户在 UI 中固定或取消固定某条链时触发该事件。

**Routes**：此处的一些事件会呈现有关路由的信息。路由是 LI.FI 呈现兑换/转移报价的方式。路由是与该次转移相关的一系列步骤、交易和成本的集合。在 Widget 中，我们会呈现一组路由供用户从中选择。一旦选定，该路由的执行即可开始，用户将被引导完成该路由所需的各个步骤。上述路由事件可以帮助跟踪路由状态。

## Widget 事件类型

`useWidgetEvents` 钩子的属性和类型。

```typescript theme={"system"}
enum WidgetEvent {
  AvailableRoutes = 'availableRoutes',
  ChainPinned = 'chainPinned',
  ContactSupport = 'contactSupport',
  DestinationChainTokenSelected = 'destinationChainTokenSelected',
  FormFieldChanged = 'formFieldChanged',
  LowAddressActivityConfirmed = 'lowAddressActivityConfirmed',
  PageEntered = 'pageEntered',
  RouteExecutionCompleted = 'routeExecutionCompleted',
  RouteExecutionFailed = 'routeExecutionFailed',
  RouteExecutionStarted = 'routeExecutionStarted',
  RouteExecutionUpdated = 'routeExecutionUpdated',
  RouteHighValueLoss = 'routeHighValueLoss',
  RouteSelected = 'routeSelected',
  SendToWalletToggled = 'sendToWalletToggled',
  SettingUpdated = 'settingUpdated',
  SourceChainTokenSelected = 'sourceChainTokenSelected',
  TokenSearch = 'tokenSearch',
  WidgetExpanded = 'widgetExpanded',
}

type WidgetEvents = {
  availableRoutes: (data: Route[]) => void
  chainPinned: (data: ChainPinned) => void
  contactSupport: (data: ContactSupport) => void
  destinationChainTokenSelected: (data: ChainTokenSelected) => void
  formFieldChanged: (data: FormFieldChanged) => void
  lowAddressActivityConfirmed: (data: LowAddressActivityConfirmed) => void
  pageEntered: (data: NavigationRouteType) => void
  routeExecutionCompleted: (data: Route) => void
  routeExecutionFailed: (data: RouteExecutionUpdate) => void
  routeExecutionStarted: (data: Route) => void
  routeExecutionUpdated: (data: RouteExecutionUpdate) => void
  routeHighValueLoss: (data: RouteHighValueLossUpdate) => void
  routeSelected: (data: RouteSelected) => void
  sendToWalletToggled: (data: boolean) => void
  settingUpdated: (data: SettingUpdated) => void
  sourceChainTokenSelected: (data: ChainTokenSelected) => void
  tokenSearch: (data: TokenSearch) => void
  widgetExpanded: (data: boolean) => void
}

type ContactSupport = {
  supportId?: string
}

type RouteHighValueLossUpdate = {
  fromAmountUSD: number
  toAmountUSD: number
  gasCostUSD?: number
  feeCostUSD?: number
  valueLoss: number
}

// `Route` and `ExecutionAction` are exported from `@lifi/sdk`.
type RouteExecutionUpdate = {
  route: Route
  action: ExecutionAction
}

type RouteSelected = {
  route: Route
  routes: Route[]
}

type TokenSearch = {
  value: string
  tokens: TokenAmount[]
}

type ChainTokenSelected = {
  chainId: ChainId
  tokenAddress: string
}

type FormFieldChanged = {
  [K in keyof DefaultValues]: {
    fieldName: K
    newValue: DefaultValues[K]
    oldValue: DefaultValues[K]
  }
}[keyof DefaultValues]

type SettingUpdated<
  K extends keyof SettingsProps = keyof SettingsProps,
> = {
  setting: K
  newValue: SettingsProps[K]
  oldValue: SettingsProps[K]
  newSettings: SettingsProps
  oldSettings: SettingsProps
}

type ChainPinned = {
  chainId: number
  pinned: boolean
}

type LowAddressActivityConfirmed = {
  address: string
  chainId: number
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.