AlphaFuturesProMax/docs/06-前端组件文档.md

智能期货期权分析系统 - 前端组件文档

组件总览

组件名称	文件路径	功能描述	复杂度
Navbar	components/Navbar.tsx	顶部导航栏	⭐⭐
MarketOverview	components/MarketOverview.tsx	市场概览仪表盘	⭐⭐⭐
HotEvents	components/HotEvents.tsx	热点事件分析	⭐⭐⭐
ProductCard	components/ProductCard.tsx	品种卡片	⭐⭐
ProductDetail	components/ProductDetail.tsx	品种详情页	⭐⭐⭐⭐
KLineChart	components/KLineChart.tsx	K线图表	⭐⭐⭐⭐⭐
RiskAlerts	components/RiskAlerts.tsx	风险提醒	⭐⭐

---

Navbar 导航栏

Props

interface NavbarProps {
  activeTab: string;      // 当前激活的标签
  onTabChange: (tab: string) => void;  // 标签切换回调
}

功能特性

• 固定顶部导航
• 响应式设计（桌面/移动端）
• 实时时钟显示
• 滚动时添加阴影效果

使用示例

import { Navbar } from '@/components/Navbar';

function App() {
  const [activeTab, setActiveTab] = useState('overview');
  
  return (
    <Navbar 
      activeTab={activeTab} 
      onTabChange={setActiveTab} 
    />
  );
}

---

MarketOverview 市场概览

Props

interface MarketOverviewProps {
  data: MarketOverview;
}

interface MarketOverview {
  heatIndex: number;        // 市场热度指数
  heatChange: number;       // 热度变化
  upCount: number;          // 上涨品种数
  downCount: number;        // 下跌品种数
  capitalFlow: number;      // 资金流向
  volatilityIndex: number;  // 波动率指数
  volatilityChange: number; // 波动率变化
}

功能特性

• 数字滚动动画
• 迷你趋势图
• 涨跌颜色区分
• 卡片悬停效果

使用示例

import { MarketOverviewPanel } from '@/components/MarketOverview';

const data = {
  heatIndex: 78.5,
  heatChange: 5.2,
  upCount: 156,
  downCount: 89,
  capitalFlow: 28.5,
  volatilityIndex: 23.8,
  volatilityChange: -1.2,
};

<MarketOverviewPanel data={data} />

---

HotEvents 热点事件

Props

interface HotEventsProps {
  events: HotEvent[];
}

interface HotEvent {
  id: string;
  title: string;
  time: string;
  summary: string;
  affectedProducts: string[];
  impact: 'bullish' | 'bearish' | 'neutral';
  impactLevel: 1 | 2 | 3 | 4 | 5;
  analysis: string;
  risks: string[];
}

功能特性

• 事件列表与详情联动
• 影响等级星级显示
• 利多/利空标签
• 响应式布局

使用示例

import { HotEventsPanel } from '@/components/HotEvents';

const events = [
  {
    id: '1',
    title: '地缘政治风险升级',
    time: '2025-03-02',
    summary: '美以袭伊朗，海上油阀被关',
    affectedProducts: ['原油', '黄金'],
    impact: 'bullish',
    impactLevel: 5,
    analysis: '地缘政治风险急剧升温...',
    risks: ['冲突升级', '供应中断'],
  },
];

<HotEventsPanel events={events} />

---

ProductCard 品种卡片

Props

interface ProductCardProps {
  product: FuturesProduct;
  onClick?: () => void;
}

interface FuturesProduct {
  id: string;
  name: string;
  code: string;
  category: string;
  price: number;
  change: number;
  changePercent: number;
  trendScore: number;
  successRate: number;
  cycles: {
    m5: TrendDirection;
    m15: TrendDirection;
    m30: TrendDirection;
    m60: TrendDirection;
  };
  keyLevels: {
    resistance: number[];
    support: number[];
  };
  recommendation: 'long' | 'short' | 'wait';
  recommendationReason: string;
}

功能特性

• 多周期趋势标签
• 成功率进度条
• 关键点位显示
• 悬停放大效果

使用示例

import { ProductCard } from '@/components/ProductCard';

const product = {
  id: '1',
  name: '原油',
  code: 'SC',
  price: 528.6,
  change: 12.1,
  changePercent: 2.35,
  // ... 其他字段
};

<ProductCard 
  product={product} 
  onClick={() => console.log('clicked')} 
/>

---

ProductDetail 品种详情

Props

interface ProductDetailProps {
  product: FuturesProduct;
  onBack: () => void;
}

功能特性

• 周期切换（5/15/30/60分钟）
• K线图展示
• 技术指标汇总
• 交易建议
• 多周期一致性分析

子组件

PeriodButton

周期切换按钮

interface PeriodButtonProps {
  label: string;
  isActive: boolean;
  onClick: () => void;
}

IndicatorCard

指标卡片

interface IndicatorCardProps {
  title: string;
  value: string;
  status: string;
  signal?: 'positive' | 'negative' | 'neutral';
}

KeyLevelRow

关键点位行

interface KeyLevelRowProps {
  label: string;
  value: number;
  type: 'resistance' | 'support';
}

使用示例

import { ProductDetail } from '@/components/ProductDetail';

<ProductDetail 
  product={product} 
  onBack={() => setSelectedProduct(null)} 
/>

---

KLineChart K线图表

Props

interface KLineChartProps {
  klineData: KLineData[];      // K线数据
  macdData: MACDData[];        // MACD数据
  resistance: number[];        // 压力位数组
  support: number[];           // 支撑位数组
  height?: number;             // 图表高度，默认500
}

interface KLineData {
  time: string;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}

interface MACDData {
  time: string;
  dif: number;
  dea: number;
  macd: number;
}

功能特性

• 三图联动（K线+成交量+MACD）
• 鼠标悬停十字光标
• 压力位/支撑位标注
• 移动平均线（MA5/MA10/MA20）
• 数据缩放与平移
• 自定义Tooltip

ECharts配置

图表使用ECharts实现，主要配置包括：

const option: echarts.EChartsOption = {
  // 三个grid分别对应K线、成交量、MACD
  grid: [
    { top: '5%', height: '50%' },    // K线
    { top: '58%', height: '15%' },   // 成交量
    { top: '76%', height: '18%' },   // MACD
  ],
  
  // 三个x轴联动
  xAxis: [
    { type: 'category', gridIndex: 0 },
    { type: 'category', gridIndex: 1 },
    { type: 'category', gridIndex: 2 },
  ],
  
  // 三个y轴
  yAxis: [
    { scale: true, gridIndex: 0 },
    { scale: true, gridIndex: 1 },
    { scale: true, gridIndex: 2 },
  ],
  
  // 数据系列
  series: [
    { type: 'candlestick', name: 'K线' },
    { type: 'line', name: 'MA5' },
    { type: 'line', name: 'MA10' },
    { type: 'line', name: 'MA20' },
    { type: 'bar', name: '成交量' },
    { type: 'bar', name: 'MACD' },
    { type: 'line', name: 'DIF' },
    { type: 'line', name: 'DEA' },
  ],
};

使用示例

import { KLineChart } from '@/components/KLineChart';

const klineData = [
  { time: '2025-03-03T10:00:00Z', open: 525, high: 528, low: 524, close: 527, volume: 12580 },
  // ... 更多数据
];

const macdData = [
  { time: '2025-03-03T10:00:00Z', dif: 0.52, dea: 0.41, macd: 0.22 },
  // ... 更多数据
];

<KLineChart
  klineData={klineData}
  macdData={macdData}
  resistance={[535, 542]}
  support={[518, 510]}
  height={500}
/>

---

RiskAlerts 风险提醒

Props

interface RiskAlertsProps {
  alerts: RiskAlert[];
}

interface RiskAlert {
  id: string;
  title: string;
  affectedProducts: string[];
  riskLevel: 'high' | 'medium' | 'low';
  description: string;
  suggestion: string;
  time: string;
}

功能特性

• 风险等级颜色区分
• 影响品种标签
• 操作建议显示

使用示例

import { RiskAlertsPanel } from '@/components/RiskAlerts';

const alerts = [
  {
    id: '1',
    title: '中东地缘风险急剧升温',
    affectedProducts: ['原油', '黄金'],
    riskLevel: 'high',
    description: '美以与伊朗冲突升级',
    suggestion: '控制仓位，设置止损',
    time: '2025-03-02 14:30',
  },
];

<RiskAlertsPanel alerts={alerts} />

---

自定义Hooks

useMarketData

市场数据订阅Hook（待实现）

function useMarketData(symbols: string[]) {
  const [data, setData] = useState<Map<string, TickData>>(new Map());
  
  useEffect(() => {
    // WebSocket连接
    const ws = new WebSocket('wss://api.example.com/ws');
    
    ws.onmessage = (event) => {
      const tick = JSON.parse(event.data);
      setData(prev => new Map(prev).set(tick.symbol, tick));
    };
    
    return () => ws.close();
  }, [symbols]);
  
  return data;
}

useKLineData

K线数据获取Hook（待实现）

function useKLineData(symbol: string, period: string) {
  const [data, setData] = useState<KLineData[]>([]);
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    setLoading(true);
    fetch(`/api/v1/products/${symbol}/kline?period=${period}`)
      .then(res => res.json())
      .then(result => {
        setData(result.data);
        setLoading(false);
      });
  }, [symbol, period]);
  
  return { data, loading };
}

---

样式规范

Tailwind自定义配置

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        background: '#09090b',
        primary: '#7dd75a',
        secondary: '#0d5d1b',
        accent: '#e6e6e6',
        up: '#7dd75a',
        down: '#ef4444',
        neutral: '#a1a1aa',
        warning: '#f59e0b',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
};

常用样式组合

/* 卡片样式 */
.card {
  @apply p-4 rounded-xl border border-[#27272a] bg-[#0d0d10];
}

/* 悬停效果 */
.card-hover {
  @apply hover:border-[#7dd75a]/50 transition-all duration-300;
}

/* 上涨文字 */
.text-up {
  @apply text-[#7dd75a];
}

/* 下跌文字 */
.text-down {
  @apply text-[#ef4444];
}