Communitygithub.com

chambaz/solanaui

將 SolanaUI 元件整合至 Solana 應用程式中。適用於建構交換介面、永續合約交易頁面、借貸儀表板、NFT 市場、投資組合檢視、質押頁面或任何 Solana DeFi 使用者介面。提供 30 個生產就緒的 React 元件,附帶 TypeScript 屬性、佈局模式與整合指南。

solanaui 是什麼?

SolanaUI 是一個專為 Solana 生態系統設計的 React 元件庫,它建構在 shadcn/ui、Radix UI 和 Tailwind CSS 之上。所有元件都是純展示性的,透過屬性接收資料並發出回呼,完全沒有區塊鏈依賴、錢包適配器或 SDK 匯入,讓開發者可以輕鬆地將它們連接到自己習慣的資料層。這個技能支援在 Cursor、Claude Code 等開發環境中使用,適用於建構交換、永續合約、借貸、NFT 市場和質押等各種 Solana DeFi 介面。它提供了 30 個生產就緒的元件,如 SwapBox、TradeBox、OrderBook、PositionTable 等,每個元件都有完整的 TypeScript 介面定義和整合範例。安裝非常簡單,只需將 SolanaUI 註冊表加入 components.json,然後透過 pnpm dlx shadcn@latest add 命令安裝所需元件即可。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

solanaui 是做什麼的?

一個專注於 Solana 的 React 元件庫,建構在 shadcn/ui、Radix UI 和 Tailwind CSS 之上。所有元件都是純展示性的——它們透過屬性接收資料並發出回呼。它們沒有區塊鏈依賴、沒有錢包適配器、也沒有 SDK 匯入。您將它們串接到您自己的資料層中。

使用時機

在建構 Solana 應用程式介面時使用 SolanaUI 元件。這些元件處理 UI 層——呈現代幣圖示、格式化價格、顯示表格和圖表——而您的程式碼則處理資料擷取、錢包連接和交易邏輯。

典型的整合方式:從您的 API 或鏈上來源擷取資料,將其轉換以符合元件的屬性介面,然後傳入。掛鉤回呼(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";

整合模式

連接到資料來源

元件透過屬性接受純資料。將您的資料對應到屬性形狀:

// 您的資料來源(API、鏈上、狀態管理等)
const positions = usePositions(); // 您的 Hook

// 對應到元件屬性形狀
<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)

單一輸入操作表單,用於質押、借貸、流動性池存款、跨鏈橋。是 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)

用於未平倉部位的止盈/止損訂單表單。雙止盈輸入(價格 + 獲利百分比),雙止損輸入(價格 + 虧損百分比)。傳入 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 部位的卡片,包含代幣圖示、數量、美元價值、APY 以及可選的操作頁尾。

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

PositionTable (position-table)

未平倉交易部位表格,包含類型(多/空)、資產圖示、數量、槓桿、進場/標記價格以及彩色盈虧。內建止盈/止損編輯和關閉操作欄位,附帶對話框 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)

用於流動性池配對或多代幣組的堆疊重疊代幣圖示。超過最大值時顯示 +N 標記。

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

TokenInput (token-input)

數值輸入,整合代幣選擇器、錢包餘額、Half/Max 按鈕和美元價值顯示。格式化時包含千分位分隔符。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 提供支援的 K 線圖,支援深色/淺色主題。

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?: string;
}

相關技能