黄金 1 分钟 K 线图

四、接入真实行情 API

真实场景中需要对接行情数据源。下面以支持 REST + WebSocket 的行情 iTick API 为例，展示接入方法。你可以替换成任何提供类似接口的服务（如自己的后端、第三方数据商等）。

4.1 历史 K 线：REST API 拉取

iTick 的行情 API 提供了期货历史 K 线接口：

GET https://api.itick.org/future/kline?symbol=GC®ion=US&kType=1&limit=100

返回格式示例：

{
  "code": 0,
  "data": [
    {
      "t": 1704067200000,
      "o": 2040.5,
      "h": 2060.2,
      "l": 2020.8,
      "c": 2055.3,
      "v": 12500
    }
  ]
}

前端调用时，建议通过自己的后端代理，避免暴露 API 密钥。后端示例（Node.js + Express）：

app.get("/api/kline", async (req, res) => {
  const { symbol, region, kType, limit } = req.query;
  const response = await fetch(
    `https://api.itick.org/future/kline?symbol=${symbol}®ion=${region}&kType=${kType}&limit=${limit}`,
    { headers: { token: process.env.API_KEY } }
  );
  const data = await response.json();
  res.json(data);
});

前端调用并转换为 Lightweight Charts 所需格式：

fetch("/api/kline?symbol=GC®ion=US&kType=1&limit=100")
  .then((res) => res.json())
  .then((data) => {
    if (data.code === 0 && data.data) {
      const klineData = data.data.map((item) => ({
        time: Math.floor(item.t / 1000), // 毫秒时间戳 → 秒
        open: item.o,
        high: item.h,
        low: item.l,
        close: item.c,
      }));
      candlestickSeries.setData(klineData);
      chart.timeScale().fitContent();
    }
  });

注意：不同的 API 返回的时间戳单位可能不同（毫秒/秒），需要根据实际情况转换。

4.2 实时推送：WebSocket 订阅 K 线更新

同样以后端代理 WebSocket 为例，或者直接在前端连接行情网关（需确保 API Key 不暴露）。以下直接展示前端连接某行情 WebSocket 的示例（假设该服务允许前端直接使用临时 token）：

let ws = null;
function connectWebSocket() {
  ws = new WebSocket("wss://api.itick.org/future");
  ws.onopen = () => {
    // 发送认证（具体格式依 API 而定）
    ws.send(JSON.stringify({ action: "auth", token: "your_temp_token" }));
  };
  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    if (msg.code === 1 && msg.msg === "Connected Successfully") {
      console.log("连接成功");
    }
    // 认证成功后订阅 K 线频道
    if (msg.code === 1 && msg.resAc === "auth") {
      ws.send(
        JSON.stringify({
          ac: "subscribe",
          params: "GC$US,SI$US", // 格式为：{symbol}${region}
          types: "kline@1", // 可选：depth, quote, tick, kline@1
        })
      );
    }
    // 处理 K 线推送
    if (msg.type === "kline@1") {
      const candle = msg.data;
      candlestickSeries.update({
        time: Math.floor(candle.t / 1000),
        open: candle.o,
        high: candle.h,
        low: candle.l,
        close: candle.c,
      });
    }
  };
  ws.onclose = () => setTimeout(() => connectWebSocket(), 3000);
  ws.onerror = (err) => console.error("WebSocket error", err);
}
connectWebSocket();

安全提醒：任何 API 密钥、token 都不应直接写在前端代码中。上述示例仅为演示逻辑，实际生产环境应通过后端代理或短期令牌方式保护敏感信息。

五、进阶功能：成交量副图与性能优化

5.1 添加成交量柱状图

Lightweight Charts 支持多系列叠加，可轻松添加成交量副图：

const volumeSeries = chart.addSeries(LightweightCharts.HistogramSeries, {
  color: "#26a69a",
  priceFormat: { type: "volume" },
  priceScaleId: "", // 独立右侧轴
});
// 假设从 API 获取的数据中包含成交量 v
volumeSeries.setData(
  apiData.map((item) => ({
    time: Math.floor(item.t / 1000),
    value: item.v,
    color: item.close >= item.open ? "#26a69a" : "#ef5350",
  }))
);

5.2 技术指标（MACD / RSI）

Lightweight Charts 本身不提供指标计算，可以：

• 使用 ta.js 或 tulind 在前端计算。
• 将计算结果作为 LineSeries 叠加到图表。

const macdLine = chart.addSeries(LightweightCharts.LineSeries, {
  color: "#FF9800",
});
macdLine.setData(macdValues);

若需要完整的技术指标内置支持，可考虑使用 react-stockcharts 或 KLineChart。

5.3 性能优化建议

• 数据更新：大量历史数据使用 setData，单根实时 K 线使用 update。
• 视口管理：不需要一次性渲染几十万根 K 线，利用库自带的数据采样。
• 窗口 resize：绑定 resize 事件并调用 chart.applyOptions({ width })。

六、总结

本文介绍了如何用 Lightweight Charts 在 10 分钟内搭建一个贵金属 K 线图前端看板，并给出了接入真实行情数据的通用方法（REST 拉取历史 + WebSocket 实时更新）。关键技术点包括：

• 对比主流 K 线图表库的优缺点，根据场景选型。
• Lightweight Charts 核心用法： createChart、 CandlestickSeries、 setData / update。
• 模拟数据快速原型，以及如何替换为真实 API。
• 成交量副图、指标叠加等扩展思路。
• 安全警示：API 密钥绝不能写在前端，必须后端代理。

GitHub： https://github.com/itick-org/