orderly-ui-components

Orderly Network：UI 组件

使用 Orderly 预构建的 React 组件构建交易界面。SDK 提供基础组件库（@orderly.network/ui）、细分交易组件（ui-order-entry、ui-positions，…）、高级功能页面（trading、portfolio、markets）以及应用脚手架（ui-scaffold）。

导入方式很重要。 组件位于特定软件包中——不要从 @orderly.network/react 导入所有内容（该软件包并不存在）。提供程序请使用 @orderly.network/react-app，基础组件请使用 @orderly.network/ui，页面级组件请使用对应的功能软件包。请参阅下方的软件包表格。

适用场景

• 快速构建交易 UI
• 使用预构建的样式化组件
• 实现标准交易界面模式

前置条件

• React 18+
• 已安装 @orderly.network/react-app、@orderly.network/ui
• 使用 OrderlyAppProvider 包裹应用
• 已配置 Tailwind CSS（在 app/ 上设置 content glob）

组件所在位置

组件	软件包	备注
OrderlyAppProvider	@orderly.network/react-app	应用提供程序（此处唯一需要导出的内容）
TradingPage	@orderly.network/trading	完整交易页面（图表 + 订单簿 + 下单组件）
OrderBook、LastTrades	@orderly.network/trading	订单簿 + 最近成交
OrderEntryWidget	@orderly.network/ui-order-entry	下单表单（OrderEntry 是无头变体）
PositionsWidget	@orderly.network/ui-positions	持仓表
TradingView	@orderly.network/ui	图表封装
Table、Modal、Sheet	@orderly.network/ui	基础组件
Scaffold	@orderly.network/ui-scaffold	应用布局（导航、页脚、账户菜单）
AuthGuard	@orderly.network/ui-connector	限制只有通过身份验证/交易后才能访问内容

@orderly.network/ui-orderbook 和 @orderly.network/ui-chart 并不存在。订单簿位于 @orderly.network/trading；图表是 @orderly.network/ui 中的 TradingView。

提供程序层级

WalletConnectorProvider（或 Privy）应当包裹 OrderlyAppProvider，而不是反过来。无需额外添加 TradingPageProvider 或 SymbolProvider——TradingPage 会在内部管理自己的交易对上下文。

import { OrderlyAppProvider } from '@orderly.network/react-app';
import { WalletConnectorProvider } from '@orderly.network/wallet-connector';

function App() {
  return (
    <WalletConnectorProvider evmInitial={…} solanaInitial={…}>
      <OrderlyAppProvider brokerId="your_broker_id" networkId="mainnet">
        <YourApp />
      </OrderlyAppProvider>
    </WalletConnectorProvider>
  );
}

不要自行添加 QueryClientProvider、ModalProvider 或 TooltipProvider——OrderlyAppProvider 会在内部设置这些提供程序。

交易页面（推荐）

如需完整的交易界面，请使用 TradingPage——它会为你组合图表、订单簿、下单组件和持仓。这也是参考模板使用的方式；仅当需要自定义布局时，才手动组装下方的组件。

import { TradingPage } from '@orderly.network/trading';

function PerpSymbol({ symbol }: { symbol: string }) {
  return <TradingPage symbol={symbol} />;
}

TradingPage 接受 tradingViewConfig（图表）、sharePnLConfig 和布局选项。请参阅 orderly-sdk-page-components。

下单组件

OrderEntryWidget 是独立组件（传入 symbol）。OrderEntry 是展示组件，接收脚本返回值（仅用于高级无头集成）。

import { OrderEntryWidget } from '@orderly.network/ui-order-entry';

function OrderEntryPanel({ symbol }: { symbol: string }) {
  return (
    <div className="rounded-lg p-4">
      <OrderEntryWidget symbol={symbol} />
    </div>
  );
}

没有 OrderEntryProvider。直接传入 symbol 属性。

持仓

import { PositionsWidget } from '@orderly.network/ui-positions';

function PositionsPanel({ symbol, onSymbolChange }: {
  symbol?: string;
  onSymbolChange?: (s: API.Symbol) => void;
}) {
  return (
    <PositionsWidget
      symbol={symbol}            // optional — filter to one symbol
      onSymbolChange={onSymbolChange}
      pnlNotionalDecimalPrecision={2}
      sharePnLConfig={…}         // optional PnL-share config
    />
  );
}

如需完整的投资组合（持仓 + 历史记录 + 订单 + 资产），建议使用 @orderly.network/portfolio 中的 OverviewModule/PositionsModule（请参阅 orderly-sdk-page-components）。

订单簿与成交

import { OrderBook, LastTrades } from '@orderly.network/trading';

function MarketData({ symbol }: { symbol: string }) {
  return (
    <>
      <OrderBook symbol={symbol} level={15} />
      <LastTrades symbol={symbol} />
    </>
  );
}

图表

import { TradingView } from '@orderly.network/ui';

function ChartPanel({ symbol }: { symbol: string }) {
  return (
    <div className="h-[500px]">
      <TradingView symbol={symbol} />
    </div>
  );
}

TradingView 从 TradingPage/provider 上的 tradingViewConfig 读取图表库路径；TradingView 库必须放在 public/tradingview/ 中（参见 orderly-sdk-dex-architecture）。

应用脚手架

@orderly.network/ui-scaffold 中的 Scaffold 会渲染响应式布局：顶部导航、左侧边栏（桌面端）、底部导航（移动端）、账户菜单和页脚。传入导航属性和用于导航的 routerAdapter。

import { Scaffold } from '@orderly.network/ui-scaffold';

function Layout({ children }: { children: React.ReactNode }) {
  return (
    <Scaffold
      mainNavProps={navConfig} // top navigation items
      bottomNavProps={bottomNavConfig} // mobile bottom nav
      footerProps={footerConfig}
      routerAdapter={{ to: (path) => navigate(path) }} // your router
    >
      {children}
    </Scaffold>
  );
}

钱包连接（UI）

没有独立导出的 WalletConnect 组件。可以命令式触发 SDK 的连接弹窗，或使用 AuthGuard 控制内容的显示：

import { modal } from '@orderly.network/ui';
import { WalletConnectorModalId, AuthGuard } from '@orderly.network/ui-connector';

function Header() {
  return <button onClick={() => modal.show(WalletConnectorModalId)}>Connect</button>;
}

function ProtectedOrders() {
  return (
    <AuthGuard>
      <PositionsWidget />
    </AuthGuard>
  );
}

基础组件（@orderly.network/ui）

数据表格

Table 使用列定义 API（dataIndex、render、title）：

import { Table, type Column } from '@orderly.network/ui';

type TradeRow = { id: string; price: number; size: number; side: 'BUY' | 'SELL' };

function TradesTable({ data }: { data: TradeRow[] }) {
  const columns: Column<TradeRow>[] = [
    {
      title: 'Price',
      dataIndex: 'price',
      render: (value, record) => (
        <span className={record.side === 'BUY' ? 'text-green-500' : 'text-red-500'}>
          {value.toFixed(2)}
        </span>
      ),
    },
    { title: 'Size', dataIndex: 'size', formatter: (v) => v.toFixed(4) },
    { title: 'Time', dataIndex: 'time' },
  ];

  return <Table columns={columns} dataSource={data} getKey={(r) => r.id} />;
}

Column<RecordType> 字段包括：title、dataIndex、render、formatter、width、align、fixed、onSort、className、getKey、hint。

模态框 / 抽屉 / Toast

import { Modal, Sheet, toast } from '@orderly.network/ui';

// Imperative toast (no provider needed — OrderlyAppProvider hosts it)
toast.success('Order placed');
toast.error('Order failed');

// Declarative modal & sheet use trigger/content composition
<Modal>
  <Modal.Trigger asChild>
    <button>Open</button>
  </Modal.Trigger>
  …
</Modal>;
<Sheet>
  <Sheet.Trigger asChild>
    <button>Open</button>
  </Sheet.Trigger>
  …
</Sheet>;

确切的组合子组件（例如 ModalTrigger）遵循 Radix 风格的命名；如果要以声明式方式构建，请检查已安装的 @orderly.network/ui 类型，确认准确名称。对于 Toast，建议使用命令式 toast 助手。

其他基础组件

Button、Input、Select、Tabs、Spinner、Tooltip、NoData、Flex、cn、useScreen——均来自 @orderly.network/ui。

样式

组件使用 Tailwind 实用类和 CSS 变量（可通过 themes 属性配置主题——参见 orderly-sdk-theming）。只需导入一次基础样式表：

/* app/styles/index.css */
@import '@orderly.network/ui/dist/styles.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

常见问题

• “Module not found: @orderly.network/react”——请使用 @orderly.network/react-app。react 不是一个软件包。
• 组件未渲染——确保应用由 OrderlyAppProvider（和一个钱包连接器）包裹；依赖交易对的小组件需要有效的 symbol。
• 缺少样式——导入 @orderly.network/ui/dist/styles.css，并将 Tailwind 的 content 指向 app/。
• “TradingPageProvider/SymbolProvider is not exported”——这些组件并不存在。TradingPage 会处理自身的上下文。

相关技能

• orderly-sdk-react-hooks - 这些组件所需数据的 Hook 参考
• orderly-sdk-page-components - 高层级页面组合
• orderly-sdk-dex-architecture - Provider 设置和项目结构
• orderly-sdk-theming - 通过 CSS 变量配置主题