Communitygithub.com

chambaz/solanaui

将 SolanaUI 组件集成到 Solana 应用中。适用于构建兑换界面、永续合约交易页面、借贷仪表盘、NFT 市场、投资组合视图、质押页面或任何 Solana DeFi UI。提供 30 个生产就绪的 React 组件,附带 TypeScript 属性、布局模式和集成指南。

solanaui 是什么?

SolanaUI 是一个专注于 Solana 的 React 组件库,构建在 shadcn/ui、Radix UI 和 Tailwind CSS 之上。所有组件都是纯展示性的——它们通过 props 接收数据并触发回调,没有区块链依赖、钱包适配器或 SDK 导入,让开发者能自由地将它们连接到自己的数据层。该库包含 30 个生产就绪的组件,覆盖了从兑换框(SwapBox)、订单簿(OrderBook)、价格图表(PriceChart)到质押表单(ActionBox)、NFT 卡片、交易表格和投资组合视图等所有常见 DeFi UI 模式。每个组件都定义了清晰的 TypeScript 接口,并提供详细的集成指南,包括数据映射、回调处理和令牌图标使用。SolanaUI 支持所有主流 AI 编码代理平台(如 Claude Code、Cursor、Codex),通过 shadcn/ui 注册表机制简化安装,自动处理必需的 UI 原语依赖。开发者只需运行 `pnpm dlx shadcn@latest add @solanaui/swap-box` 即可安装组件,将其导入为 `@/components/sol/` 下的本地组件,然后通过 props 传入数据、通过回调连接应用逻辑,无需处理区块链交互的复杂性。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add chambaz/solanaui

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

solanaui 是做什么的?

一个专注于 Solana 的 React 组件库,构建在 shadcn/ui、Radix UI 和 Tailwind CSS 之上。所有组件都是纯展示性的——它们通过 props 接收数据并触发回调。它们没有区块链依赖、没有钱包适配器、也没有 SDK 导入。您可以将它们连接到自己的数据层。

何时使用

在构建 Solana 应用界面时使用 SolanaUI 组件。这些组件处理 UI 层——渲染令牌图标、格式化价格、显示表格和图表——而您的代码则处理数据获取、钱包连接和交易逻辑。

典型的集成方式:从您的 API 或链上来源获取数据,将其转换为匹配组件 prop 接口的形式,然后传入。挂钩到回调(onSubmit、onSelect、onValueChange)以触发您的应用程序逻辑。

安装

需要在您的项目中初始化 shadcn/ui(必须存在 components.json)。如果尚未初始化,请先运行 pnpm dlx shadcn@latest init。

将 SolanaUI 注册表添加到您的 components.json 中:

{
  "registries": {
    "@solanaui": "https://solanaui.dev/r/{name}.json"
  }
}

然后安装组件:

pnpm dlx shadcn@latest add @solanaui/swap-box

任何必需的 shadcn/ui 原语(Card、Dialog、Button 等)都会作为注册表依赖项自动解析。组件还依赖于 @/lib/utils 中的 cn() 工具函数。

导入约定

import { SwapBox } from "@/components/sol/swap-box";
import { PoolTable } from "@/components/sol/pool-table";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";

集成模式

连接到数据源

组件通过 props 接受纯数据。将您的数据映射到 prop 形状:

// 您的数据源(API、链上、状态管理等)
const positions = usePositions(); // 您的 hook

// 映射到组件 prop 形状
<PositionTable
  positions={positions.map(p => ({
    symbol: p.market.baseSymbol,
    icon: p.market.baseIconUrl,       // 使用您自己的图标 URL
    side: p.direction,
    size: formatNumber(p.size),
    value: formatUsd(p.notionalValue),
    leverage: `${p.leverage}x`,
    entryPrice: formatUsd(p.entryPrice),
    markPrice: formatUsd(p.currentPrice),
    pnl: formatPnl(p.unrealizedPnl),
    pnlPercent: formatPercent(p.unrealizedPnlPercent),
    pnlTrend: p.unrealizedPnl >= 0 ? "up" : "down",
  }))}
  onClosePosition={(pos) => closePosition(pos.symbol)}
  onEditTpSl={(pos, values) => updateTpSl(pos.symbol, values)}
/>

令牌图标

组件接受图标 URL 作为字符串。使用您的项目已有的任何图标源——您自己的 CDN、令牌注册表或元数据服务。

如果您需要用于原型设计的占位图标,这些公共 CDN URL 可以工作:

  • SOL:https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png
  • USDC:https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png
  • BONK:https://arweave.net/hQiPZOsRZXGXBJd_82PhVdlM_hACsT_q6wqwf5cSY7I
  • JitoSOL:https://storage.googleapis.com/token-metadata/JitoSOL-256.png
  • mSOL:https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So/logo.png

处理回调

组件为用户操作触发回调。将这些回调连接到您的应用程序逻辑:

<SwapBox
  tokens={availableTokens}
  defaultFromToken="USDC"
  defaultToToken="SOL"
  fromBalance={wallet.usdcBalance}
  details={quoteDetails}
  submitLabel="Swap"
  // 您的兑换执行逻辑
  onSubmit={() => executeSwap(fromToken, toToken, amount)}
/>

<ActionBox
  tokens={supportedTokens}
  label="Stake"
  balance={wallet.solBalance}
  details={stakingDetails}
  submitLabel="Stake SOL"
  onSubmit={() => submitStakeTransaction(selectedToken, amount)}
/>

组件目录(30 个组件)

ActionBox (action-box)

用于质押、借贷、LP 存入、桥接的单输入操作表单。是 TradeBox 的多功能对应组件。

interface ActionBoxProps {
  tokens: { icon: string; symbol: string }[];
  defaultToken?: string;
  balance?: string;
  label?: string;
  details?: { label: string; value: string; className?: string }[];
  submitLabel?: string;
  onSubmit?: () => void;
  className?: string;
}

ActivityFeed (activity-feed)

按时间顺序排列的活动列表,带有图标、时间戳(Date 对象)和值。使用 date-fns 的 formatDistanceToNow 显示相对时间。

interface ActivityFeedProps {
  items: { icon?: string; title: string; description?: string; timestamp: Date; value?: string }[];
  className?: string;
}

AddressDisplay (address-display)

截断的 Solana 地址,支持复制到剪贴板和可选的浏览器链接。explorerUrl 是基础 URL;地址会自动追加。

interface AddressDisplayProps {
  address: string; truncate?: boolean; truncateChars?: [number, number];
  copyable?: boolean; explorerUrl?: string; className?: string;
}

AuthCard (auth-card)

登录卡片,带有可选的电子邮件输入、社交登录按钮和钱包提供商按钮。

interface AuthCardProps {
  title?: string; description?: string; showEmail?: boolean;
  socialProviders?: { name: string; icon: React.ReactNode }[];
  walletProviders?: { name: string; icon: React.ReactNode }[];
}

HealthBar (health-bar)

渐变进度条(红到绿),带有彩色百分比值。

interface HealthBarProps { value: number; label?: string; showValue?: boolean; className?: string }

LeverageSlider (leverage-slider)

用于选择交易杠杆的滑块,带有最小/最大快捷按钮。

interface LeverageSliderProps {
  min?: number; max?: number; step?: number; value?: number[];
  defaultValue?: number[]; onValueChange?: (value: number[]) => void; className?: string;
}

NFTCard (nft-card)

展示 NFT 图片、名称、集合和价格的卡片,带有加载/错误状态。

interface NFTCardProps {
  name: string; image: string; collection?: string;
  price?: string; currency?: string; className?: string;
}

OrderBook (order-book)

交易订单簿,包含买/卖盘档位、数量、累计总额、价差、中间价和深度条。

interface OrderBookProps {
  bids: { price: number; size: number }[];
  asks: { price: number; size: number }[];
  className?: string;
}

OrderForm (order-form)

针对未平仓仓位的 TP/SL 订单表单。双 TP 输入(价格 + 增益百分比),双 SL 输入(价格 + 损失百分比)。传递 entryPrice 可在价格和百分比字段之间自动同步。

interface OrderFormProps {
  title?: string; description?: string; entryPrice?: number;
  details?: { label: string; value: string; className?: string }[];
  onSubmit?: (values: { tpPrice: string; tpPercent: string; slPrice: string; slPercent: string }) => void;
  className?: string;
}

PoolCard (pool-card)

适用于单令牌或多令牌池的多功能卡片。显示堆叠图标、可选价格、描述、指标网格、迷你线图以及子元素插槽。

interface PoolCardProps {
  tokens: { icon: string; symbol: string }[]; name?: string; price?: string; description?: string;
  metrics?: { label: string; value: string; highlight?: boolean; className?: string }[];
  series?: { time: string; value: number }[]; children?: React.ReactNode; className?: string;
}

PoolTable (pool-table)

数据表格,每行包含令牌图标(一个或多个)、用户定义的列、可排序以及可选的行操作。适用于池列表、令牌表、验证器表。

interface PoolTableProps {
  columns: { key: string; label: string; className?: string }[];
  rows: { icons: { src: string; alt?: string }[]; name?: string; data: Record<string, string> }[];
  actions?: React.ReactNode[]; className?: string;
}

PositionCard (position-card)

展示 DeFi 仓位的卡片,包含令牌图标、数量、USD 值、APY 以及可选的操作底部栏。

interface PositionCardProps {
  symbol: string; icon: string; amount: string; value: string;
  apy?: string; trend?: "up" | "down"; children?: React.ReactNode; className?: string;
}

PositionTable (position-table)

未平仓交易仓位表格,包含类型(做多/做空)、资产图标、规模、杠杆、入场/标记价格以及带颜色的盈亏。内置 TP/SL 编辑和关闭操作列,带有对话框 UI。

interface PositionTablePosition {
  symbol: string; icon: string; side: "long" | "short";
  size: string; value: string; leverage: string;
  entryPrice: string; markPrice: string; liquidationPrice?: string;
  pnl: string; pnlPercent?: string; pnlTrend?: "up" | "down";
}
interface PositionTableProps {
  positions: PositionTablePosition[];
  onEditTpSl?: (position: PositionTablePosition, values: { tpPrice: string; tpPercent: string; slPrice: string; slPercent: string }) => void;
  onClosePosition?: (position: PositionTablePosition) => void;
  className?: string;
}

PriceChart (price-chart)

用于令牌价格或投资组合价值历史的面积图,带有坐标轴、网格、渐变填充和工具提示。

interface PriceChartProps {
  title?: string; description?: string;
  series: { time: string; value: number }[]; className?: string;
}

SparklineChart (sparkline-chart)

极简内联迷你线图,自动正负着色和百分比变化标签。

interface SparklineChartProps { series: { time: string; value: number }[]; className?: string }

StatCard (stat-card)

统计数据显示卡片,包含标签、值、可选图标和可选的趋势徽章。

interface StatCardProps {
  label: string; value: string; change?: string;
  trend?: "up" | "down"; icon?: React.ReactNode; className?: string;
}

SwapBox (swap-box)

双面令牌兑换表单,带有翻转按钮、详情行和提交操作。翻转按钮就地交换选定的令牌(标签保持固定)。

interface SwapBoxProps {
  tokens: { icon: string; symbol: string }[];
  defaultFromToken?: string; defaultToToken?: string;
  fromBalance?: string; toBalance?: string; fromLabel?: string; toLabel?: string;
  details?: { label: string; value: string; className?: string }[];
  submitLabel?: string; onSubmit?: () => void; className?: string;
}

TokenCombobox (token-combobox)

可搜索的下拉菜单,用于选择令牌,带有图标和复选标记选择。

interface TokenComboboxProps {
  tokens: { icon: string; symbol: string }[];
  defaultValue?: string; onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}

TokenCommand (token-command)

Cmd+K 命令对话框,用于搜索和选择令牌。传递 tokens(平铺列表)或 groups(分段列表),但不能同时传递两者。

type TokenCommandProps = {
  onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
} & (
  | { tokens: { icon: string; symbol: string }[]; groups?: never }
  | { groups: { heading: string; tokens: { icon: string; symbol: string }[] }[]; tokens?: never }
)

TokenIcon (token-icon)

圆形令牌图标图片,带有加载骨架和错误回退。

type TokenIconProps = { src: string; alt: string; width?: number; height?: number; className?: string }

TokenIconGroup (token-icon-group)

为 LP 对或多令牌组堆叠重叠的令牌图标。在超过最大值时显示 +N 徽章。

interface TokenIconGroupProps {
  tokens: { src: string; alt?: string }[]; size?: number; overlap?: number; max?: number; className?: string;
}

TokenInput (token-input)

数字输入框,集成了令牌选择器、钱包余额、一半/最大按钮和 USD 值显示。使用千位分隔符格式化。onValueChange 接收原始未格式化字符串。

interface TokenInputProps {
  tokens: { icon: string; symbol: string }[]; defaultToken?: string; balance?: string;
  value?: string; usdValue?: string; onValueChange?: (value: string) => void;
  onTokenSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}

TradeBox (trade-box)

永续合约/保证金交易表单,带有多头/空头切换、令牌输入、杠杆滑块、详情行和提交。对于非交易操作,请使用 ActionBox。

interface TradeBoxProps {
  tokens: { icon: string; symbol: string }[]; defaultToken?: string; balance?: string;
  labels?: [string, string]; defaultSide?: string;
  leverageMin?: number; leverageMax?: number; leverageDefault?: number; leverageStep?: number;
  details?: { label: string; value: string; className?: string }[];
  submitLabel?: string; onSubmit?: () => void; className?: string;
}

TradeButtons (trade-buttons)

用于选择交易方向(多头/空头或买入/卖出)的切换组,带有颜色编码状态。

interface TradeButtonsProps {
  defaultValue?: string; value?: string; onValueChange?: (value: string) => void;
  labels?: [string, string]; className?: string;
}

TradeChart (trade-chart)

由 TradingView lightweight-charts 驱动的蜡烛图,支持深色/浅色主题。

interface TradeChartProps {
  data: { time: string | number; open: number; high: number; low: number; close: number }[];
  visibleBars?: number; className?: string;
}

TrendBadge (trend-badge)

小型彩色徽章,带有趋势图标,表示正(绿色)或负(红色)变化。

interface TrendBadgeProps { trend?: "up" | "down"; children: React.ReactNode; className?: string }

TxnTable (txn-table)

交易表格,包含截断的签名链接、相对时间戳(Date 对象,通过 date-fns)、操作徽章和令牌数量。

interface TxnTableProps {
  transactions: {
    signature: string; timestamp: Date; action: string; token: string;
    tokenIcon?: string; amount: string; value?: string; explorerUrl?: string;
  }[];
  className?: strin
}

相关技能