直方图数据

直方图数据不是 K 线。它把一段时间内的成交或报价数据按价格分布聚合，返回每个价格档位对应的数量。它适合观察“这段时间主要成交集中在哪些价格附近”，而不是画时间序列图。

接口关系

目标	方法 / 回调
请求直方图	`reqHistogramData()`
接收直方图数组	`histogramData()`
取消请求	`cancelHistogramData()`

和历史 K 线的区别

对比项	历史 K 线	直方图数据
关注点	时间顺序	价格分布
返回单位	一根根 bar	一个个价格档位
常见字段	`date/open/high/low/close/volume`	`price/size`
适合用途	回测、图表、指标	价格分布、成交集中区

AAPL 参考输出

AAPL 发送 3 个直方图请求：

REQUEST_SENT=reqId=4301;symbol=AAPL;useRTH=True;period=1 week
REQUEST_SENT=reqId=4302;symbol=AAPL;useRTH=False;period=1 week
REQUEST_SENT=reqId=4303;symbol=AAPL;useRTH=True;period=1 day
CONNECTED=True
CONTRACT=AAPL STK SMART NASDAQ USD
INFO_CODES=2104,2106,2158
CALLBACK_RECEIVED=reqId=4301;name=aapl_rth_1_week;value=True
HISTOGRAM_ROWS=reqId=4301;name=aapl_rth_1_week;count=2951
HISTOGRAM=reqId=4301;price=296.0;size=180840
HISTOGRAM=reqId=4301;price=297.0;size=60640
CALLBACK_RECEIVED=reqId=4302;name=aapl_all_1_week;value=True
HISTOGRAM_ROWS=reqId=4302;name=aapl_all_1_week;count=2999
HISTOGRAM=reqId=4302;price=296.0;size=190480
CALLBACK_RECEIVED=reqId=4303;name=aapl_rth_1_day;value=True
HISTOGRAM_ROWS=reqId=4303;name=aapl_rth_1_day;count=0
NON_INFO_ERROR_COUNT=0

这个结果说明连接、合约和请求发送链路正常。1 week 返回了非空价格分布，1 day 收到了回调但数组为空。写程序时要区分三种状态：非空数组、空数组、超时无回调。空数组是明确结果，不应自动当成失败无限重试。

使用建议

直方图适合做辅助分析，不适合替代 K 线回测。策略如果需要时间顺序，仍应使用 reqHistoricalData()；如果只关心一段时间内价格集中区域，再考虑直方图。