选择 Widget 布局

模式

模式让你能够为用户呈现不同的工作流。

在 Widget Playground 中尝试不同的模式——在侧边栏中打开 Mode。

type WidgetMode = 'default' | 'split' | 'custom' | 'refuel';

默认模式

default 模式在统一视图中提供标准的桥接和交换功能。

const widgetConfig: WidgetConfig = {
  mode: 'default', // This is the default
};

分屏模式

split 模式分离了心智模型，通过主页面上的标签为桥接和交换体验提供不同的视图。

const widgetConfig: WidgetConfig = {
  mode: 'split',
};

分屏模式选项

对于 mode: 'split'，modeOptions 配置控制是显示 “Swap” 和 “Bridge” 两个标签，还是显示单一界面：

默认（无选项）：显示 “Bridge” 和 “Swap” 两个标签
split: 'bridge'：仅显示桥接界面（无标签）
split: 'swap'：仅显示交换界面（无标签）
split: { defaultTab: 'bridge' } 或 split: { defaultTab: 'swap' }：显示两个标签，并选中指定的默认标签

// Default - shows both tabs
const tabsConfig: WidgetConfig = {
  mode: 'split',
};

// Pure bridge interface
const bridgeConfig: WidgetConfig = {
  mode: 'split',
  modeOptions: {
    split: 'bridge',
  },
};

// Pure swap interface
const swapConfig: WidgetConfig = {
  mode: 'split',
  modeOptions: {
    split: 'swap',
  },
};

// Both tabs with swap as default
const tabsSwapDefaultConfig: WidgetConfig = {
  mode: 'split',
  modeOptions: {
    split: { defaultTab: 'swap' },
  },
};

Split mode (Default)

Split mode (Swap option)

自定义模式

custom 模式提供了不同的外观，允许你展示自定义组件并构建包括 NFT Checkout 和 Deposit 在内的全新流程。

type CustomMode = 'checkout' | 'deposit';

Checkout 流程

用于 NFT 或产品的结账流程：

const widgetConfig: WidgetConfig = {
  mode: 'custom',
  modeOptions: {
    custom: { type: 'checkout' },
  },
  contractCalls: [...], // Your contract calls
  contractComponent: <YourCheckoutComponent />,
  contractTool: {
    name: 'Your Protocol',
    logoURI: 'https://your-protocol.com/logo.png',
  },
};

Deposit 流程

用于协议的存款流程：

import { ChainType, LiFiWidget, WidgetConfig } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  mode: 'custom',
  modeOptions: {
    custom: { type: 'deposit' },
  },
  toAddress: {
    name: 'Protocol Vault',
    address: '0x...',
    chainType: ChainType.EVM,
    logoURI: 'https://your-protocol.com/logo.png',
  },
  disabledUI: { toAddress: true },
  hiddenUI: { appearance: true, language: true },
  showSingleRoute: true,
  contractComponent: <YourDepositCard />,
  contractTool: {
    name: 'Your Protocol',
    logoURI: 'https://your-protocol.com/logo.png',
  },
};

请参阅完整的 Deposit 流程示例。

Refuel 模式

refuel 模式针对 gas 加油操作进行了优化，帮助用户在目标链上获取原生代币。

const widgetConfig: WidgetConfig = {
  mode: 'refuel',
};

ModeOptions 接口

type SplitMode = 'bridge' | 'swap'
type SplitModeOptions = {
  defaultTab: SplitMode
}

type CustomMode = 'checkout' | 'deposit'

interface ModeOptions {
  // Options for 'split' mode
  // Pass a string for single-mode (no tabs), or an object for tabs with a default
  split?: SplitMode | SplitModeOptions
  
  // Options for 'custom' mode
  custom?: { type: CustomMode }
}

变体

变体提供了一种方式，可根据你应用中可用的空间来优化 Widget 的呈现样式。

在 Widget Playground 中尝试不同的变体——在侧边栏中打开 Variant。

type WidgetVariant = 'compact' | 'wide' | 'drawer';

紧凑型变体

当你在页面上空间有限或处理较小屏幕尺寸时，紧凑型变体是一个很好的选择。它在紧凑视图中拥有桥接和交换所需的一切，并允许你将 widget 集成到 Web 应用页面中的任意位置。

const widgetConfig: WidgetConfig = {
  variant: 'compact', // This is the default
};

宽屏型变体

宽屏型变体让你能够充分利用更大的页面和屏幕尺寸，在那里你可能拥有更多可用的屏幕空间。它以带有流畅动画的侧边栏形式，提供了对可用路由更全面的概览。

const widgetConfig: WidgetConfig = {
  variant: 'wide',
};

链侧边栏

wide 变体默认显示一个链侧边栏。要隐藏它，请在 hiddenUI 中将 chainSidebar 设为 true：

const widgetConfig: WidgetConfig = {
  variant: 'wide',
  hiddenUI: {
    chainSidebar: true,
  },
};

抽屉型变体

抽屉型变体允许你根据用户交互来显示或隐藏 Widget。它可以很好地放置在页面的一侧，并具有与紧凑型变体相同的布局。

const widgetConfig: WidgetConfig = {
  variant: 'drawer',
};

控制抽屉

抽屉没有用于打开和关闭它的预构建按钮。要控制抽屉，请创建一个 ref 并将其分配给 widget：

import { useRef } from 'react';
import { LiFiWidget, WidgetDrawer, WidgetConfig } from '@lifi/widget';

export const WidgetPage = () => {
  const drawerRef = useRef<WidgetDrawer>(null);

  const toggleWidget = () => {
    drawerRef.current?.toggleDrawer();
  };

  const openWidget = () => {
    drawerRef.current?.openDrawer();
  };

  const closeWidget = () => {
    drawerRef.current?.closeDrawer();
  };

  const isWidgetOpen = () => {
    return drawerRef.current?.isOpen();
  };

  return (
    <div>
      <button onClick={toggleWidget}>Toggle Widget</button>
      <button onClick={openWidget}>Open Widget</button>
      <button onClick={closeWidget}>Close Widget</button>
      <LiFiWidget
        ref={drawerRef}
        config={{
          variant: 'drawer',
        }}
        integrator="drawer-example"
      />
    </div>
  );
};

WidgetDrawer 接口

interface WidgetDrawer {
  isOpen(): boolean      // Check if drawer is open
  toggleDrawer(): void   // Toggle drawer open/closed
  openDrawer(): void     // Open the drawer
  closeDrawer(): void    // Close the drawer
}

受控抽屉

你还可以使用 open 和 onClose props 从外部控制抽屉状态：

import { useState } from 'react';
import { LiFiWidget, WidgetConfig } from '@lifi/widget';

export const WidgetPage = () => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Open Widget</button>
      <LiFiWidget
        open={isOpen}
        onClose={() => setIsOpen(false)}
        config={{
          variant: 'drawer',
        }}
        integrator="controlled-drawer-example"
      />
    </div>
  );
};

高度

以下是配置 widget 高度的几种推荐方式：默认、限制最大高度、限制高度和全高度。

在 Widget Playground 中尝试不同的高度配置——在侧边栏中打开 Height。

对于紧凑型和宽屏型变体，我们推荐使用默认、限制最大高度或限制高度。全高度仅推荐用于紧凑型。抽屉型变体使用完整的容器/视口高度。

默认

默认情况下，widget 在较小的页面上适应其内容，并在具有长列表的页面上以 686 像素（maxHeight）为上限。这无需更改配置。

限制最大高度

widget 会扩展和收缩以适应内容，但不会超过所声明的最大高度。溢出的页面会变为可滚动。在 theme.container 上将 maxHeight 设为一个数字（像素）。需要设置高于 686（默认值）的值。

import { WidgetConfig } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  theme: {
    container: {
      maxHeight: 820,
    },
  },
};

限制高度

所有页面都占据指定的确切高度——widget 保持一致的大小。溢出的页面会变为可滚动。在 theme.container 上将 height 设为一个数字（像素）。需要设置高于 686（默认值）的值。

import { WidgetConfig } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  theme: {
    container: {
      height: 900,
    },
  },
};

Page height stays consistent across pages

不要同时使用 height 和 maxHeight——它们代表 widget 中不同的布局方式。

全高度

推荐用于移动端和屏幕空间有限、且 widget 是主要内容的场景。widget 会填满其容器 HTML 元素的完整高度，并将滚动委托给页面。

import { WidgetConfig } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  variant: 'compact',
  theme: {
    container: {
      display: 'flex',
      height: '100%',
    },
    header: {
      position: 'fixed',
      top: 0,
    },
  },
};

配置详解：

variant: ‘compact’ — 必需；紧凑型专为较小屏幕而构建。
theme.container — display: 'flex' 和 height: '100%' 使 widget 填满其容器。
theme.header（可选）— 设置 position: 'fixed' 和一个 top 值以使页头固定。调整 top 以考虑 widget 上方的元素（例如，一个 60px 的导航栏 → top: 60）。若不设置，页头会随页面内容滚动。

全高度将尺寸委托给父容器，因此你页面的 HTML 和 CSS 必须正确处理这一点。

可能需要更新视口 meta，以使页面正确呈现
- 例如 <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
Widget Playground 使用 min-height: 100dvh——高于视口的页面保持可滚动，而较矮的页面则使用 flex 填满屏幕。
在页面的根/body 上添加 overscroll-behavior: none;，以防止不期望的滚动行为。

考虑相对于你站点的导航、页头和页脚进行放置。在 Widget Playground 中预览页头和/或页脚的放置——在侧边栏中打开 Developer Controls 并切换 ‘Show mock header’ 和/或 ‘Show mock footer’。

入门

基本设置

高级

Widget Light (iframe)

其他

选择 Widget 布局

模式

默认模式

分屏模式

分屏模式选项

Split mode (Default)

Split mode (Swap option)

自定义模式

Checkout 流程

Deposit 流程

Refuel 模式

ModeOptions 接口

变体

紧凑型变体

宽屏型变体

链侧边栏

抽屉型变体

控制抽屉

WidgetDrawer 接口

受控抽屉

高度

默认

限制最大高度

限制高度

全高度

​模式

​默认模式

​分屏模式

​分屏模式选项

Split mode (Default)

Split mode (Swap option)

​自定义模式

​Checkout 流程

​Deposit 流程

​Refuel 模式

​ModeOptions 接口

​变体

​紧凑型变体

​宽屏型变体

​链侧边栏

​抽屉型变体

​控制抽屉

​WidgetDrawer 接口

​受控抽屉

​高度

​默认

​限制最大高度

​限制高度

​全高度

模式

默认模式

分屏模式

分屏模式选项

自定义模式

Checkout 流程

Deposit 流程

Refuel 模式

ModeOptions 接口

变体

紧凑型变体

宽屏型变体

链侧边栏

抽屉型变体

控制抽屉

WidgetDrawer 接口

受控抽屉

高度

默认

限制最大高度

限制高度

全高度