orderly-sdk-theming

Orderly Network：SDK 主题

自定义 Orderly DEX 的视觉外观。将一个或多个主题传入 OrderlyAppProvider 的 themes 属性，即可为 SDK 设置主题。每个主题包含一组 CSS 变量（--oui-*）以及可选的 TradingView 图表颜色。

适用场景

• 为 DEX 打造品牌形象（颜色、徽标、网站图标）
• 提供多个主题（深色 + 浅色，或不同品牌变体）
• 调整 TradingView 图表样式以保持一致
• 自定义 PnL 分享海报

前提条件

• 已安装 @orderly.network/react-app、@orderly.network/ui
• 已挂载 OrderlyAppProvider

主题的工作原理

1. 定义一个主题对象数组（纯 TS，见下文）。
2. 将数组传入 <OrderlyAppProvider themes={themes}>。
3. Provider 会应用默认主题的 CSS 变量，并提供主题切换器。

SDK 不依赖任何特定的配置来源：主题只是数据。你可以在代码中直接定义、从模块导入，或从配置加载，按应用的偏好选择即可。

定义主题

主题是一个普通对象。定义 1–6 个主题，并将其中且仅其中一个标记为 isDefault：

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

const themes = [
  {
    id: '11111111-1111-4111-8111-111111111111', // unique UUID
    displayName: 'Dark', // shown in the theme switcher
    mode: 'dark', // "dark" | "light"
    isDefault: true, // exactly ONE theme sets this
    cssVars: {
      // optional: override --oui-* vars
      '--oui-color-primary': '#29dfa9',
      '--oui-color-base-1': '#0e0e10',
      '--oui-color-base-2': '#161618',
      '--oui-color-trading-profit': '#29dfa9',
      '--oui-color-trading-loss': '#f5618b',
      '--oui-gradient-brand-start': '#29dfa9',
      '--oui-gradient-brand-end': '#1aa37c',
    },
    tradingViewColorConfig: {
      // optional: chart colors
      chartBG: '#0e0e10',
      upColor: '#29dfa9',
      downColor: '#f5618b',
      pnlUpColor: '#29dfa9',
      pnlDownColor: '#f5618b',
      pnlZeroColor: '#8b8b8b',
      textColor: '#b8b8b8',
      qtyTextColor: '#8b8b8b',
      volumeUpColor: '#29dfa9',
      volumeDownColor: '#f5618b',
      closeIconColor: '#b8b8b8',
    },
  },
  {
    id: '22222222-2222-4222-8222-222222222222',
    displayName: 'Light',
    mode: 'light',
    cssVars: { '--oui-color-primary': '#1aa37c', '--oui-color-base-1': '#ffffff' },
  },
];

接入 Provider

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

function Provider({ children }) {
  return (
    <OrderlyAppProvider brokerId={brokerId} networkId="mainnet" themes={themes}>
      {children}
    </OrderlyAppProvider>
  );
}

主题对象架构

themes 需要采用以下结构。参考模板使用 zod 进行校验，但你也可以直接将其用作普通 TS 类型。

字段	类型	必填	备注
id	UUID 字符串	是	在所有主题中必须唯一
displayName	字符串（1–50 个字符）	是	显示在主题切换器中；不区分大小写，且必须唯一
mode	"dark" | "light"	是	基础模式
cssVars	Partial<ThemeCssVars>	否	覆盖 --oui-* 变量（见下方列表）
tradingViewColorConfig	Partial<TradingViewColorConfig>	否	图表颜色（见下文）
isDefault	boolean	否	必须且只能有一个主题设置此项

限制：主题数量为 1–6 个；id 必须唯一；displayName 必须唯一（不区分大小写）；必须且只能有一个默认主题。

export type DexThemeConfig = Array<{
  id: string;
  displayName: string;
  mode: 'dark' | 'light';
  cssVars?: Partial<ThemeCssVars>;
  tradingViewColorConfig?: TradingViewColorConfig;
  isDefault?: boolean;
}>;

CSS 变量（--oui-*）

在 cssVars 下覆盖任意变量。所有变量均为可选项；省略某个变量时，将保留 SDK 中与主题 mode 对应的默认值。

品牌 / 强调色： --oui-color-primary、--oui-color-primary-light、--oui-color-primary-darken、--oui-color-primary-contrast、--oui-color-link、--oui-color-link-light、--oui-color-secondary、--oui-color-tertiary、--oui-color-quaternary

语义色： --oui-color-danger（+ -light、-darken、-contrast）、--oui-color-success（+ …）、--oui-color-warning（+ …）

表面 / 文本： --oui-color-fill、--oui-color-fill-active、--oui-color-base-1 … --oui-color-base-10、--oui-color-base-foreground、--oui-color-base-static、--oui-color-base-static-contrast、--oui-color-line

交易盈亏： --oui-color-trading-profit、--oui-color-trading-profit-contrast、--oui-color-trading-loss、--oui-color-trading-loss-contrast

渐变： --oui-gradient-primary-{start,end}、--oui-gradient-secondary-*、--oui-gradient-success-*、--oui-gradient-danger-*、--oui-gradient-brand-{start,end,stop-start,stop-end,angle}、--oui-gradient-warning-*、--oui-gradient-neutral-*

形状与间距： --oui-rounded-sm、--oui-rounded、--oui-rounded-{md,lg,xl,2xl,full}、--oui-spacing-{xs,sm,md,lg,xl}、--oui-font-family

完整键集合为 typeof DARK_THEME_CSS_VARS（由 @orderly.network/ui 导出为 ThemeCssVars）。任意子集均有效。

TradingView 图表样式

图表颜色配置位于主题的 tradingViewColorConfig 中。图表配置本身（库路径）通过 tradingViewConfig 传递给 TradingPage。

TradingViewColorConfig 字段

字段	类型	说明
chartBG	hex	图表背景
upColor	hex	上涨蜡烛 / 线条
downColor	hex	下跌蜡烛 / 线条
pnlUpColor	hex	PnL 为正
pnlDownColor	hex	PnL 为负
pnlZeroColor	hex	PnL 为零
textColor	hex	坐标轴 / 标签文本
qtyTextColor	hex	数量文本
volumeUpColor	hex	成交量柱（上涨）
volumeDownColor	hex	成交量柱（下跌）
closeIconColor	hex 或 rgba	关闭按钮图标（支持 rgba）

<TradingPage
  symbol={symbol}
  tradingViewConfig={{
    scriptSRC: '/tradingview/charting_library/charting_library.js',
    library_path: '/tradingview/charting_library/',
    customCssUrl: '/tradingview/chart.css',
    // colorConfig is omitted when themes carry tradingViewColorConfig;
    // the chart then reads colors from the active theme.
  }}
/>

徽标和网站图标

通过 appIcons 属性将徽标传递给 OrderlyAppProvider，其类型为 AppLogos（@orderly.network/react-app）：

import type { AppLogos } from '@orderly.network/react-app';

const appIcons: AppLogos = {
  main: hasPrimaryLogo
    ? { component: <img src="/logo.webp" alt="logo" style={{ height: '42px' }} /> }
    : { img: '/orderly-logo.svg' }, // { img } for a plain URL
  secondary: { img: hasSecondaryLogo ? '/logo-secondary.webp' : '/orderly-logo-secondary.svg' },
};

<OrderlyAppProvider appIcons={appIcons} /* … */ />;

将资源放在 public/ 中（例如 public/logo.webp）。使用基础路径包装器，确保它们在子路径部署下也能正确解析。更新 public/favicon.webp 和 index.html 中用于网站图标的 <link> 标签。

PnL 分享海报

TradingPage 接受一个 sharePnLConfig：

const sharePnLConfig = {
  backgroundImages: posterBackgrounds, // URLs to your poster backgrounds
  color: 'rgba(255,255,255,0.98)',
  profitColor: 'rgba(41,223,169,1)',
  lossColor: 'rgba(245,97,139,1)',
  brandColor: 'rgba(255,255,255,0.98)',
  refLink: window.location.origin,
  refSlogan: brokerName, // your brand slogan
};

<TradingPage sharePnLConfig={sharePnLConfig} /* … */ />;

Tailwind

SDK 不附带 Tailwind 预设。将内容 glob 指向你的源代码，并且不要在 Tailwind 中定义品牌颜色——请改用 --oui-* CSS 变量。

// tailwind.config.ts
import type { Config } from 'tailwindcss';
export default {
  content: ['./app/**/{**,.client,.server}/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {
      fontFamily: { sans: ['Inter', 'ui-sans-serif', 'system-ui', 'sans-serif'] },
    },
  },
  plugins: [],
} satisfies Config;

/* global styles (imported once at app entry) */
@import '@orderly.network/ui/dist/styles.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

通过 SDK 元素的 oui-* 类名和 CSS 变量设置自定义样式：

.oui-card {
  border-radius: var(--oui-rounded-lg);
}

从配置加载主题（可选）

如果你想在不修改代码的情况下切换主题，可以将主题数组存储为 JSON，并在运行时加载。参考模板通过 Vite .env 变量和一个小型校验加载器实现了这一点：

# .env  (single line — shown pretty-printed for readability)
VITE_ORDERLY_THEME_CONFIG=[{"id":"…","displayName":"Dark","mode":"dark","isDefault":true,"cssVars":{...}}]

// resolves + zod-validates the JSON into a DexThemeConfig[]; falls back to a
// single synthesized default theme when the var is absent/invalid
const { themes } = resolveDexThemeConfig(import.meta.env.VITE_ORDERLY_THEME_CONFIG);

运行时配置间接层（public/config.js / window.__RUNTIME_CONFIG__）仅适用于多实例部署，即同一构建配合不同主题重复使用的场景——这是 Orderly One 的需求，相关说明见 orderly-one-dex。对于普通 DEX，静态主题数组（或 .env）就足够了。

相关技能

• orderly-sdk-dex-architecture - Provider 设置，说明如何接入 themes
• orderly-ui-components - 使用这些 CSS 变量的组件库
• orderly-sdk-install-dependency - 安装 UI 包