> ## 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 通过 iframe 嵌入 LI.FI Widget

Widget Light（`@lifi/widget-light`）让你可以通过 iframe 将完整的 LI.FI 跨链交换和桥接 widget 嵌入到你的应用中，同时将钱包连接保留在你自己一侧。用户使用他们现有的钱包对交易进行签名 -- widget 从不直接接触浏览器扩展或私钥。

## 何时使用 Widget Light 而非完整 Widget

|               | Widget Light（`@lifi/widget-light`）   | 完整 Widget（`@lifi/widget`）                |
| ------------- | ------------------------------------ | ---------------------------------------- |
| **渲染**        | 在托管于 `widget.li.fi` 的 iframe 内运行     | 直接在你的 React 树中渲染                         |
| **依赖**        | 除 React 外零核心依赖                       | MUI、Zustand、TanStack Router、i18next 等    |
| **Bundle 大小** | 最小 -- 只有 postMessage 桥接进入你的 bundle   | 完整的 widget 代码都包含在你的 bundle 中             |
| **钱包归属**      | 你的应用拥有所有钱包连接                         | widget 通过 provider 包管理钱包                 |
| **隔离**        | 沙箱化的 iframe -- widget 无法访问你的 DOM 或状态 | 共享你的 React 上下文和 DOM                      |
| **配置**        | 仅可 JSON 序列化的配置（无 React 节点、无 MUI 主题）  | 完整的 `WidgetConfig`，含 React 节点、回调和 MUI 主题 |
| **框架支持**      | 任何能渲染 iframe 的框架                     | 仅 React 19+                              |

当你想要在 widget 与你的应用之间实现强隔离时、当你已经管理钱包并希望保留这种控制权时、或者当你想要最小化 bundle 大小时，请选择 **Widget Light**。当你需要通过 MUI 主题、React 节点注入或基于回调的配置进行深度 UI 自定义时，请选择 **完整 widget**。

## 架构

```
+----------------------------------+       +----------------------------------+
|         YOUR APPLICATION         |       |      IFRAME (widget.li.fi)       |
|                                  |       |                                  |
|  LiFiWidgetLight component       | <---> |  Full LI.FI Widget               |
|  + Ecosystem handlers (wagmi...) | post  |  Receives config, sends RPC      |
|  + Event subscriptions           | Msg   |  requests back to your wallets   |
+----------------------------------+       +----------------------------------+
```

通信流程如下：

1. 你的应用渲染 `<LiFiWidgetLight>`，它会在 iframe 中加载托管的 widget URL
2. iframe 发送 `READY` 信号；你的应用以配置和钱包状态作为响应
3. 当 widget 需要签名或切换链时，它会通过 `postMessage` 发送一个 RPC 请求
4. 你的生态系统处理器（例如用于 EVM 的 wagmi）执行该请求并返回结果
5. 钱包状态变化（账户切换、网络更改）会自动推送到 iframe

出于安全考虑，所有通信都被限制到预期的来源（默认为 `https://widget.li.fi`）。

## 主要优势

* **iframe 隔离** -- widget 在沙箱化的 iframe 中运行；你的页面保持完全的控制权
* **零核心依赖** -- 除了作为对等依赖的 React 之外，`@lifi/widget-light` 不附带任何东西；链特定的处理器是可 tree-shake 的子路径导入
* **你的钱包，你的 UX** -- 交易由你已经管理的钱包（wagmi、wallet-standard、bigmi、dapp-kit）进行签名
* **响应式配置** -- 随时更新配置而无需重新加载 iframe
* **类型化事件系统** -- 订阅路由执行、钱包和 UI 事件，具备完整的 TypeScript 支持

## 支持的生态系统

Widget Light 支持五种区块链生态系统，每种都通过一个专用的处理器钩子提供支持：

| 生态系统          | 链类型    | 处理器                          | 导入路径                          |
| ------------- | ------ | ---------------------------- | ----------------------------- |
| Ethereum（EVM） | `EVM`  | `useEthereumIframeHandler()` | `@lifi/widget-light/ethereum` |
| Solana        | `SVM`  | `useSolanaIframeHandler()`   | `@lifi/widget-light/solana`   |
| Bitcoin       | `UTXO` | `useBitcoinIframeHandler()`  | `@lifi/widget-light/bitcoin`  |
| Sui           | `MVM`  | `useSuiIframeHandler()`      | `@lifi/widget-light/sui`      |
| Tron          | `TVM`  | `useTronIframeHandler()`     | `@lifi/widget-light/tron`     |

你只需为你支持的生态系统安装并使用处理器。未使用的生态系统包会被完全从你的 bundle 中 tree-shake 掉。

## 托管的 Widget

widget iframe 默认从 `https://widget.li.fi` 加载。你无需自行托管或部署任何 widget 代码 -- `<LiFiWidgetLight>` 组件会自动指向此 URL。

若要针对特定版本或自托管的部署进行测试，请将你的自定义 URL 作为 `src` prop 传入。

## 后续步骤

* [安装 Widget Light](/widget/widget-light-installation) -- 设置包和依赖
* [配置 Widget Light](/widget/widget-light-configuration) -- 了解所有配置选项
* [Widget Light 事件](/widget/widget-light-events) -- 订阅 widget 事件
* [Widget Light 钱包管理](/widget/widget-light-wallet-management) -- 理解生态系统处理器
* [Widget Light API 参考](/widget/widget-light-api-reference) -- 完整的组件和钩子参考