交易深度图组件 depth-chart.js 使用全指南

快速、轻量、无依赖的 depth-chart.js 让你三分钟把“市场深度可视化”放进网页，股票、加密资产统统适用。

1. depth-chart.js 是什么？

depth-chart.js 是一款面向浏览器端的 市场深度可视化组件。它用原生绘制买卖盘口图，并支持鼠标滚轮缩放、十字线定位、双重主题切换以及完全自定义配色，体积不足 20 KB，零依赖。
关键特征：

CPU 友好：10 万级数据帧率依旧不低于 60 FPS
主题可拆：官方提供浅色 / 深色主题，可自行调节每一条线、每一块填充色
易落库：支持 jQuery / React / Vue / Angular / 纯 HTML，真正“即插即用”

2. 三步上手：最快加载 demo

STEP 1 引入脚本

<canvas id="depth-chart" width="600" height="300"></canvas>
<script src="./lib/uikit.umd.js"></script>

STEP 2 组织数据

const dataset = {
  bids: [
    ["29650", "1.5"],
    ["29640", "2.3"]
    // …更高买价在前
  ],
  asks: [
    ["29655", "1.2"],
    ["29660", "0.9"]
    // …更低卖价在前
  ]
};

STEP 3 实例化

new uikit.DepthChart({
  el: '#depth-chart',
  dataset,
  theme: uikit.Theme.dark() // 也可 light()
});

页面刷新后就能看到左右两块渐变填充的 市场深度图。

3. 深度图常见配置项

名称	类型	默认	说明
el	String / Element	-	Canvas 选择器
dataset	Object	-	bids、asks 二维数组
theme	Object	light()	颜色、线宽、字号均可覆盖
zoomStep	Number	0.15	单次滚轮缩放比例
cursor	Boolean	true	是否显示十字光标

👉 想要更精细的交互配置？这里是官方最佳实践合集

3.1 自定义主题示例

const custom = uikit.Theme.dark()
  .set('bidColor', '#0A74FF')        // 买墙蓝色
  .set('askColor', '#FF3B30')        // 卖墙红色
  .set('axisTextColor', '#B6C4D2');  // 坐标文字
new uikit.DepthChart({ el, dataset, theme: custom });

3.2 与行情系统联动的最佳姿势

轮询：fetch('/depth?symbol=BTCUSDT') 每 1 秒刷新
WebSocket：推送增量时，仅更新 bids / asks 相应价位，重绘频率可降 50 % 以上
缓存：本地 Map<price, amount>，避免数据抖动造成的闪烁

4. 源码进阶：从 0 构建私有版本

需要更高自由度？直接修改源码。

下载：curl -L http://sc.hubwiz.com/codebag/uikit-depth/uikit-depth-1.0.0.tar.gz -o depth.tar.gz && tar zxvf depth.tar.gz
安装依赖：cd uikit-depth && npm i
改动：src/DepthChart.js 负责渲染管线，src/Theme.js 负责样式
重新打包：npm run build 就会在 lib/uikit.umd.js 生成最新库文件

建议把位图渲染、坐标系计算、主题定义三个模块拆成独立文件，再按需 Tree-shaking，可将最终包压到 14 KB。

FAQ：最常见问题一次说清

Q1：数据量级达到百万条会不会卡？
A：组件采用 canvas 位图渲染，在大数据场景下比 SVG 快 5–10 倍；只绘制可视区内的 3000 点即可保持 60 FPS。

Q2：能否去掉深色 / 浅色按钮，只给用户一个主题？
A：可以。把 theme: uikit.Theme.light() 改成你自己写死的一套自定义主题即可，文件大小不变。

Q3：在 React 项目中如何优雅更新数据？
A：把 dataset 作为 state，当新数据到达后调用 chart.update(dataset)，整个组件不会重渲染，仅 canvas 局部重绘。

Q4：Depth-chart.js 支持移动端手势吗？
A：目前只支持鼠标滚轮、单击/拖动。若需双指缩放可监听 touchstart / touchmove 自行在 JS 控制 chart.setZoom()。

Q5：可以在同一个页面放多个深度图吗？
A：完全可以，只需保证每个 canvas 有独立 ID，并在实例化时区分即可，多个互不影响。

Q6：组件开源协议？能否商用？
A：MIT License，可闭源商用；修改后无需开源，但请保留顶部的版权注释。

5. 真实场景落地案例

交易所后台：把 BNB/BUSD、BTC/USDT 等二十余个交易对的实时深度集中在同一面板上，交易运营团队 5 秒内即可发现异常大单。
行情大屏：4K 电视上每 30 秒轮播不同交易对，使用 CSS @media 自动切换浅色 / 深色。
量化研究：研究员把深度图与成交量热力图并排放置，快速找到 限价墙 与 价格脆弱 区，平均提升回测效率 30 %。

在一周实战中，某团队仅用 700 行业务代码就把官方 Demo 升级为：一键切换品种、Websocket 推送、可导出深度 CSV，完全贴合其量化策略需求。

从今天起，用 depth-chart.js 给你的产品加上“一眼看穿盘口”的能力。
其余繁琐与性能优化，它已经替你做好。祝你交易顺利、代码优雅！