使用 KLineChart 这个轻量级的前端图表库

在本篇指南中，我们将一步步演示如何从 StockTV API 获取美股K线数据，并使用 KLineChart 这个轻量级的前端图表库，构建一个具备实时更新能力的K线图 Demo。

🧰 准备工作

在开始编码前，你需要完成两项简单的准备工作。

获取 API 密钥 ：首先，你需要访问 StockTV 的官方平台（例如 pao.stocktv.top）注册账号并申请 API 密钥（KEY）。这个密钥是所有数据请求的"通行证"``。
引入必要的 JavaScript 库 ：在前端页面中，你需要通过 <script> 标签引入 KLineChart 库，并以模块化方式引入 DolphinDB 的 JavaScript API（本例中用于建立 WebSocket 连接和数据通信）``。

html 复制代码

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>美股K线图实战Demo</title>
    <!-- 引入KLineChart -->
    <script src="https://cdn.dolphindb.cn/vendors/klinecharts/dist/umd/klinecharts.min.js"></script>
</head>
<body>
    <div id="k-line-chart" style="height: 600px;"></div>

    <script type="module">
        // 模块化引入DolphinDB JavaScript API
        import { DDB } from 'https://cdn.dolphindb.cn/assets/api.js';
        // 你的代码将在这里编写
    </script>
</body>
</html>

📡 获取美股K线数据

一切就绪后，我们通过 StockTV API 获取数据。以下关键接口将用于本次演示``。

接口功能	请求方法	核心参数说明
查询股票列表 (获取股票ID)	`GET /stock/stocks`	`countryId`: 国家ID (美国为1), `symbol`: 股票代码 (如"AAPL") ``
获取历史K线数据	`GET /stock/kline`	`pid`: 股票唯一ID, `interval`: K线周期 (如P1D代表日线), `key`: 你的API密钥 ``

在 JavaScript 中，我们可以使用 fetch API 来获取数据。下面的示例演示如何获取苹果公司（AAPL）的日K线数据。

javascript 复制代码

// 配置参数
const API_KEY = 'YOUR_API_KEY_HERE'; // 请替换为你的真实API密钥
const symbol = 'AAPL'; // 股票代码
const interval = 'P1D'; // K线周期：日线

async function fetchKLineData() {
    // 1. 根据股票代码查询其唯一产品ID (pid)
    const listUrl = `https://api.stocktv.top/stock/stocks?countryId=1&symbol=${symbol}&key=${API_KEY}`;
    const listResponse = await fetch(listUrl);
    const listData = await listResponse.json();
    
    if (listData.code !== 200 || listData.data.length === 0) {
        console.error('未找到该股票:', listData.message);
        return;
    }
    
    const stockPid = listData.data[0].id; // 获取股票的pid

    // 2. 使用pid请求历史K线数据
    const klineUrl = `https://api.stocktv.top/stock/kline?pid=${stockPid}&interval=${interval}&key=${API_KEY}`;
    const klineResponse = await fetch(klineUrl);
    const klineData = await klineResponse.json();
    
    if (klineData.code === 200) {
        console.log('获取到K线数据:', klineData.data);
        return klineData.data; // 返回数据用于绘图
    } else {
        console.error('获取K线数据失败:', klineData.message);
        return null;
    }
}

⚙️ 初始化K线图表与数据适配

获取到数据后，需要将其格式转换为 KLineChart 可识别的标准结构，并初始化图表``。

KLineChart 标准数据格式

javascript 复制代码

{
    timestamp: 1725004800000, // 时间戳 (毫秒)
    open: 239.42,             // 开盘价
    high: 239.6,              // 最高价
    low: 239.42,               // 最低价
    close: 239.6,             // 收盘价
    volume: 1241700           // 成交量 (可选)
}

初始化图表并载入数据

StockTV API 返回的数据字段名（如 time）可能与 KLineChart 的要求（timestamp）不完全一致，需要进行映射``。

javascript 复制代码

// 初始化K线图容器
const chart = klinecharts.init('k-line-chart');

async function initChart() {
    const apiData = await fetchKLineData();
    if (!apiData) return;

    // 数据格式转换：将API返回的字段名映射为KLineChart要求的字段名
    const klineChartData = apiData.map(item => ({
        timestamp: item.time,   // 将 'time' 映射为 'timestamp'
        open: item.open,
        high: item.high,
        low: item.low,
        close: item.close,
        volume: item.volume     // 成交量字段名通常一致
    }));

    // 使用转换后的数据渲染图表
    chart.applyNewData(klineChartData);
    console.log('K线图初始化完成！');
}

// 执行初始化
initChart();

🔄 实现实时数据更新

对于金融应用，实时性至关重要。KLineChart 提供了 updateData 方法用于增量更新单根K线，applyNewData 方法用于全量刷新数据``。实现实时更新主要有两种方案：

方案	原理	适用场景
定时轮询 (Polling)	使用 `setInterval` 定时调用 `fetchKLineData` 获取最新数据，然后使用 `chart.updateData` 更新图表。	数据更新频率不高、对实时性要求不极致的场景。实现简单。
WebSocket 推送	建立与实时数据服务器的 WebSocket 连接，服务器在数据变化时主动推送。前端在收到消息后调用 `chart.updateData`。	高实时性要求的场景，如量化交易。效率更高，延迟更低。

下面的代码展示了定时轮询方案的实现：

javascript 复制代码

// 定时轮询更新函数
async function startPolling() {
    setInterval(async () => {
        const latestData = await fetchLatestKLineData(); // 此函数应只请求最近一条数据
        if (latestData) {
            // 使用updateData方法增量更新图表最后一条K线
            chart.updateData(latestData);
        }
    }, 5000); // 每5秒轮询一次，可根据需要调整间隔
}

// 初始化图表后启动轮询
initChart().then(() => {
    startPolling();
});

🎨 自定义样式与技术指标

KLineChart 支持丰富的样式自定义和技术指标，可以让你的图表更专业。

自定义图表样式
你可以在初始化图表时或通过 setStyleOptions 方法修改外观，比如设置涨跌颜色``。

javascript 复制代码

// 设置样式选项
chart.setStyleOptions({
    candle: {
        type: 'candle_solid', // 蜡烛图类型
        bar: {
            upColor: '#26A69A', // 上涨颜色
            downColor: '#EF5350', // 下跌颜色
        },
        priceMark: { // 价格标记
            high: { show: true },
            low: { show: true }
        }
    },
    grid: { // 网格线
        show: true
    }
});

添加技术指标
使用 createTechnicalIndicator 方法可以轻松添加各种技术指标，例如移动平均线（MA）``。

javascript 复制代码

// 在图表主图区域添加一个5周期移动平均线(MA)
const paneId = chart.createTechnicalIndicator('MA', false, { id: "candle_pane" });

💡 完整示例与注意事项

将以上步骤整合，一个完整的 HTML 文件大致结构如下。请注意，将 YOUR_API_KEY_HERE 替换为你从 StockTV 获取的真实 API 密钥是成功运行的关键。

html 复制代码

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>美股K线图Demo</title>
    <script src="https://cdn.dolphindb.cn/vendors/klinecharts/dist/umd/klinecharts.min.js"></script>
</head>
<body>
    <div id="k-line-chart" style="height: 600px; width: 100%;"></div>

    <script type="module">
        import { DDB } from 'https://cdn.dolphindb.cn/assets/api.js';

        const API_KEY = 'YOUR_API_KEY_HERE'; // 重要：请替换！
        const symbol = 'AAPL';
        // ... 这里嵌入前面编写的 fetchKLineData, initChart, 样式设置等函数 ...

        // 页面加载完成后启动
        window.onload = initChart;
    </script>
</body>
</html>

⚠️ 重要注意事项

API密钥安全：切勿将你的真实 API 密钥直接硬编码在前端代码中并上传到公开仓库。对于生产环境，应通过你自己的后端服务器进行转发请求以保护密钥``。
频率限制：遵守 StockTV API 的调用频率限制，避免过于频繁的请求导致失败``。
错误处理：完善的错误处理（如网络请求失败、API返回错误码）能提升应用健壮性。

希望这个实战指南能帮助你快速上手！如果你在尝试过程中遇到任何问题，可以查阅 StockTV 的官方文档或在技术社区交流。