自定义 Widget

LI.FI Widget 支持视觉自定义，让你能够匹配 Web 应用的设计。widget 的布局保持一致，但你可以修改颜色、字体、边框圆角、容器样式，禁用或隐藏部分 UI，等等。从调整以下部分选项开始自定义 widget：

interface WidgetConfig {
  // sets default appearance - light, dark, or system
  appearance?: Appearance;
  // disables parts of the UI
  disabledUI?: DisabledUIConfig;
  // hides parts of the UI
  hiddenUI?: HiddenUIConfig;
  // makes parts of the UI required
  requiredUI?: RequiredUIConfig;
  // sets default UI behaviors
  defaultUI?: DefaultUI;
  // tweaks container, components, colors, fonts, border-radius
  theme?: WidgetTheme;
}

主题

通过自定义主题，你可以确保 LI.FI Widget 匹配你应用的外观和体验，提供无缝的用户体验。

在 Widget Playground 中实时预览主题更改——在侧边栏中打开 Theme，然后点击 Edit theme。

theme 配置选项允许你自定义 widget 外观的各个方面，包括颜色、排版、形状和组件样式。

容器

container 选项自定义 widget 的主容器。 routesContainer 和 chainSidebarContainer 选项分别为路由和链侧边栏展开区域应用自定义样式（在 wide 变体中可用）。在下面的示例中，我们调整了所有容器的 boxShadow 和边框圆角属性。

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

export const WidgetPage = () => {
  const widgetConfig: WidgetConfig = useMemo(
    () => ({
      theme: {
        container: {
          boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
          borderRadius: '16px',
        },
        chainSidebarContainer: {
          boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
          borderRadius: '16px',
        },
        routesContainer: {
          boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
          borderRadius: '16px',
        },
      },
    }),
    []
  );

  return <LiFiWidget integrator="Your dApp/company name" config={widgetConfig} />;
};

Before

After

配色方案

colorSchemes 选项为浅色和深色模式定义了独立的调色板。这让你可以为每种外观模式独立自定义颜色。

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

export const WidgetPage = () => {
  const widgetConfig: WidgetConfig = useMemo(
    () => ({
      theme: {
        colorSchemes: {
          light: {
            palette: {
              primary: { main: '#7B3FE4' },
              secondary: { main: '#F5B5FF' },
              background: {
                default: '#ffffff',
                paper: '#f8f8fa',
              },
              text: {
                primary: '#000000',
                secondary: '#747474',
              },
            },
          },
          dark: {
            palette: {
              primary: { main: '#9B6FE4' },
              secondary: { main: '#D59FFF' },
              background: {
                default: '#121212',
                paper: '#212121',
              },
              text: {
                primary: '#ffffff',
                secondary: '#bbbbbb',
              },
            },
          },
        },
      },
    }),
    []
  );

  return <LiFiWidget integrator="Your dApp/company name" config={widgetConfig} />;
};

形状与排版

shape 选项定义了 widget 中所有元素的边框圆角覆盖：

borderRadius - 卡片和容器的主要边框圆角
borderRadiusSecondary - 按钮和输入框的次要边框圆角
borderRadiusTertiary - 特定元素的第三级边框圆角

typography 选项自定义字体设置，例如字体族。

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

export const WidgetPage = () => {
  const widgetConfig: WidgetConfig = useMemo(
    () => ({
      theme: {
        colorSchemes: {
          light: {
            palette: {
              primary: { main: '#7B3FE4' },
              secondary: { main: '#F5B5FF' },
            },
          },
        },
        shape: {
          borderRadius: 12,
          borderRadiusSecondary: 12,
          borderRadiusTertiary: 24,
        },
        typography: {
          fontFamily: 'Inter, sans-serif',
        },
        container: {
          boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
          borderRadius: '16px',
        },
      },
    }),
    []
  );

  return <LiFiWidget integrator="Your dApp/company name" config={widgetConfig} />;
};

Before

After

组件

components 选项允许你自定义 widget 中特定组件的样式。当前可用组件列表：

MuiAppBar - 用作 widget 顶部的页头/导航组件。
MuiAvatar - 用于显示代币/链头像。
MuiButton - 用于 widget 中的各种按钮。
MuiCard - 用于 widget 中的卡片元素。有三种默认卡片变体：
- outlined - 默认变体，卡片带有细边框。
- elevation - 卡片带有阴影的变体。
- filled - 卡片以颜色填充的变体（palette.background.paper 属性）。
MuiDrawer - 当 variant 设为 'drawer' 时用于抽屉容器。
MuiIconButton - 用于 widget 中的图标按钮。
MuiInputCard - 用于 widget 中的输入卡片。
MuiNavigationTabs - 用于 split 模式中的导航标签。
MuiNavigationTab - 用于单个导航标签项。
MuiTabs - 用于 widget 中的标签导航（在 split 模式中可用）。
MuiCheckbox - 用于 widget 中的复选框元素。

使用 components 选项，每个组件都可以通过 MUI 的 styleOverrides 属性进行自定义，从而对其样式实现细粒度控制。

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { tabsClasses } from '@mui/material';
import { useMemo } from 'react';

export const WidgetPage = () => {
  const widgetConfig: WidgetConfig = useMemo(
    () => ({
      theme: {
        colorSchemes: {
          light: {
            palette: {
              primary: { main: '#006Eff' },
              secondary: { main: '#FFC800' },
              background: {
                default: '#ffffff',
                paper: '#f8f8fa',
              },
              text: {
                primary: '#00070F',
                secondary: '#6A7481',
              },
              grey: {
                200: '#EEEFF2',
                300: '#D5DAE1',
                700: '#555B62',
                800: '#373F48',
              },
            },
          },
        },
        shape: {
          borderRadius: 12,
          borderRadiusSecondary: 12,
          borderRadiusTertiary: 24,
        },
        container: {
          boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
          borderRadius: '16px',
        },
        components: {
          MuiCard: {
            defaultProps: { variant: 'filled' },
          },
          // Used only for 'split' mode and can be safely removed if not used
          MuiNavigationTabs: {
            styleOverrides: {
              root: {
                backgroundColor: '#f8f8fa',
                [`.${tabsClasses.indicator}`]: {
                  backgroundColor: '#ffffff',
                },
              },
            },
          },
        },
      },
    }),
    []
  );

  return <LiFiWidget integrator="Your dApp/company name" config={widgetConfig} />;
};

预配置主题

LI.FI Widget 包含若干预配置主题，为自定义提供了起点。这些主题演示了颜色、形状和组件样式的各种配置，让你了解如何为 widget 设置样式以适应不同的设计需求。除了默认主题外，还提供以下预配置主题：

import { 
  azureLightTheme, 
  jumperTheme,
  watermelonLightTheme, 
  windows95Theme 
} from '@lifi/widget';

Azure Light

一款干净、专业的主题，采用蓝色主色调。

Azure compact

Azure wide

Watermelon Light

一款俏皮的主题，采用粉色/珊瑚色主色调。

Watermelon compact

Watermelon wide

Windows 95

一款复古主题，模仿经典的 Windows 95 美学，具有锐利的边角和独特的阴影。

Windows 95 compact

Windows 95 wide

自定义预配置主题

你可以通过展开这些预配置主题并覆盖特定属性来进一步自定义它们：

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

const widgetConfig: WidgetConfig = {
  theme: {
    ...azureLightTheme,
    container: {
      ...azureLightTheme.container,
      borderRadius: '24px',
    },
  },
};

外观

widget 开箱即支持完整的深色模式。appearance 选项可设置为：

'light' - 始终使用浅色模式
'dark' - 始终使用深色模式
'system' - 匹配用户的系统设置（默认）

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

export const WidgetPage = () => {
  const widgetConfig: WidgetConfig = useMemo(
    () => ({
      appearance: 'dark',
    }),
    []
  );

  return <LiFiWidget integrator="Your dApp/company name" config={widgetConfig} />;
};

Before

After

禁用的 UI 元素

disabledUI 属性允许你指定应在 widget 中禁用哪些 UI 元素。禁用 UI 元素有助于防止用户与 widget 中某些对你的特定实现可能不必要或不希望被交互的部分进行交互。

interface DisabledUIConfig {
  // Disables the input field for the token amount
  fromAmount?: boolean;
  // Disables the button for the source token selection
  fromToken?: boolean;
  // Disables the button for specifying the destination address
  toAddress?: boolean;
  // Disables the button for the destination token selection
  toToken?: boolean;
}

隐藏的 UI 元素

hiddenUI 属性允许你指定应在 widget 中隐藏哪些 UI 元素。这有助于通过移除对你的使用场景可能不相关的元素来定制用户界面以适应你的特定需求。

interface HiddenUIConfig {
  // Hides the connected wallets section in address book
  addressBookConnectedWallets?: boolean;
  // Hides the "All Networks" option in chain selectors
  allNetworks?: boolean;
  // Hides the appearance settings UI (light/dark mode switch)
  appearance?: boolean;
  // Hides the bridges settings UI
  bridgesSettings?: boolean;
  // Hides the chain selection UI
  chainSelect?: boolean;
  // Hides the chain sidebar in the wide variant
  chainSidebar?: boolean;
  // Hides the contact support button
  contactSupport?: boolean;
  // Hides the close button in the drawer variant
  drawerCloseButton?: boolean;
  // Hides the button for the source token selection
  fromToken?: boolean;
  // Hides the gas refuel message UI
  gasRefuelMessage?: boolean;
  // Hides the toggle to hide tokens with small balances
  hideSmallBalances?: boolean;
  // Hides the transaction history UI
  history?: boolean;
  // Hides the insufficient gas message UI
  insufficientGasMessage?: boolean;
  // Hides the integrator-specific step details UI
  integratorStepDetails?: boolean;
  // Hides the language selection UI
  language?: boolean;
  // Hides the low address activity confirmation dialog
  lowAddressActivityConfirmation?: boolean;
  // Hides the 'Powered by LI.FI' branding - not recommended :)
  poweredBy?: boolean;
  // Hides the button to reverse/swap the from and to tokens
  reverseTokensButton?: boolean;
  // Hides the price impact indicator on route cards
  routeCardPriceImpact?: boolean;
  // Hides the token description in routes
  routeTokenDescription?: boolean;
  // Hides the search bar in the tokens list
  searchTokenInput?: boolean;
  // Hides the button for specifying the destination address
  toAddress?: boolean;
  // Hides the button for the destination token selection
  toToken?: boolean;
  // Hides the wallet menu UI
  walletMenu?: boolean;
}

以下示例展示了如何在 UI 中隐藏外观和语言设置：

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

export const WidgetPage = () => {
  const widgetConfig: WidgetConfig = useMemo(
    () => ({
      hiddenUI: { language: true, appearance: true },
    }),
    []
  );

  return <LiFiWidget integrator="Your dApp/company name" config={widgetConfig} />;
};

Before

After

必填的 UI 元素

requiredUI 属性允许你指定 widget 中哪些 UI 元素应为必填项。这意味着用户必须与这些元素进行交互，widget 才能继续进行交换/桥接。

interface RequiredUIConfig {
  // Shows a message when the account is a smart account that may have
  // different addresses on other chains
  accountDeployedMessage?: boolean;
  // Makes the destination address required for interaction
  toAddress?: boolean;
}

必填目标地址

当开发者想要构建一个只能将预先配置的钱包地址列表设为目标地址的流程时，将目标地址设为必填会很有用。详情请参阅配置精选的钱包地址列表。如果你对适用于你服务的其他自定义选项感兴趣，请通过我们的合作伙伴页面联系我们。如你所见，widget 自定义相当简单直接。随着我们不断增加新的自定义选项，我们期待看到你会构思出怎样的组合。

入门

基本设置

高级

Widget Light (iframe)

其他

自定义 Widget

主题

容器

Before

After

配色方案

形状与排版

Before

After

组件

预配置主题

Azure Light

Azure compact

Azure wide

Watermelon Light

Watermelon compact

Watermelon wide

Windows 95

Windows 95 compact

Windows 95 wide

自定义预配置主题

外观

Before

After

禁用的 UI 元素

隐藏的 UI 元素

Before

After

必填的 UI 元素

必填目标地址

​主题

​容器

Before

After

​配色方案

​形状与排版

Before

After

​组件

​预配置主题

​Azure Light

Azure compact

Azure wide

​Watermelon Light

Watermelon compact

Watermelon wide

​Windows 95

Windows 95 compact

Windows 95 wide

​自定义预配置主题

​外观

Before

After

​禁用的 UI 元素

​隐藏的 UI 元素

Before

After

​必填的 UI 元素

​必填目标地址

主题

容器

配色方案

形状与排版

组件

预配置主题

Azure Light

Watermelon Light

Windows 95

自定义预配置主题

外观

禁用的 UI 元素

隐藏的 UI 元素

必填的 UI 元素

必填目标地址