3-2、JS Api
最后更新于
最后更新于
这是啥? 一套JS方法（以实现指定的公共接口）。 我该怎么使用它?: 您应该创建一个JS对象，它将以某种方式接收数据，并响应图表库的请求。
在图表库中实现了数据缓存（历史和商品信息）。当您创建一个实现接口的对象时，只需将它传递给图表库Widget的构造函数。
callback: function(configurationData)
configurationData: object (见下文)
此方法可以设置图表库支持的图表配置。这些数据会影响到图表支持的功能，所以它被称为服务端定制。
图表库要求您使用回调函数来传递datafeed的 configurationData参数。
configurationData是一个对象，现在支持以下属性:
交易所对象数组。 交易所对象的结构为: {value, name, desc}。
value将被作为exchange参数传递给 searchSymbols。
exchanges = []会导致商品查询列表中看不到交易所过滤器。value = ""来创建通配符筛选器（所有的交易所）。
商品类型对象数组。商品类型对象的结构为: {name, value}。value将被作为symbolType参数传递给searchSymbols。
symbolsTypes= [] 会导致商品查询列表中看不到商品类型过滤器。 使用value= ""来创建通配符筛选器（所有的商品类型）。
支持的周期数组，周期可以是数字或字符串。 如果周期是一个数字，它被视为分钟数。 字符串可以是“*D”，“*W”，“_M”（_的意思是任何数字）。格式化详细参照:文章。
resolutions = undefined 或 resolutions = [] 时，周期拥有widget中的默认内容。
例:[1, 15, 240, "D", "6M"]您将在周期中得到 "1 分钟, 15 分钟, 4 小时, 1 天, 6 个月" 。
用于货币转换的支持的货币数组。
示例：[“USD”，“EUR”，“GBP”]。
列出支持的单位组的对象。 每个组可以有多个单位对象。 每个单位对象应具有以下字段：
id: string. 唯一主键
name: string. 缩略名
description: string. 简介
例子:
布尔值来标识您的 datafeed 是否支持在K线上显示标记。
布尔值来标识您的 datafeed 是否支持时间刻度标记。
将此设置为true假如您的datafeed提供服务器时间（unix时间）。 它仅用于在价格刻度上显示倒计时。
如果要在商品搜索中对商品进行分组，请设置它。 值为一个对象，其中键是商品类型，值是正则表达式（每个正则表达式应该将一个期货名称分为两部分：合约种类和到期时间）。
例子:
它将应用于 type 为 futures 和 stock的商品。
userInput: string，用户在商品搜索框中输入的文字。
exchange:string，请求的交易所（由用户选择）。空值表示没有指定。
symbolType: string，请求的商品类型：index、stock、forex等等（由用户选择）。空值表示没有指定。
onResultReadyCallback: function(result)
result: 数组 (见下文)
方法介绍：提供一个匹配用户搜索的商品列表。result为预期的商品 ，像下面这样:
如果没有找到商品，则应该使用空数组来调用回调。查看更多关于ticker的细节 在这里
symbolName: string，商品名称 或ticker
onSymbolResolvedCallback: function(SymbolInfo)
onResolveErrorCallback: function(reason)
extension: 具有附加参数的可选对象。 它具有以下字段：
currencyCode: string, 如果设置了currency_codes配置字段并且在原始商品信息中提供了currency_code，则可以提供它来表示要转换的货币。
unitId: string. 如果 units 配置，它可以被提供来指示要转换的单位。 设置字段并在商品信息中提供 unit_id 。
方法介绍：通过商品名称解析商品信息(SymbolInfo)。
symbolInfo:SymbolInfo 商品信息对象
resolution: string （周期）
periodParams: 具有以下字段的对象:
from - unix 时间戳, 最左边请求的K线时间(K线时间 >= from)
countBack - 要加载的K线的确切数量，如果您的datafeed支持它（见下文），则将视为拥有比 from 更高的优先级。 如果用户请求特定时间段，则可以不指定。
to: unix 时间戳, 最右边请求的K线时间(K线时间 < to)
firstDataRequest: 布尔值，以标识是否第一次调用此商品/周期的历史记录。当设置为true时 你可以忽略to参数（这取决于浏览器的Date.now()) 并返回K线数组直到最新K线。
onHistoryCallback: function(数组bars,meta={ noData = false }) 历史数据的回调函数。每次请求只应被调用一次。 此函数有2个参数：
bars: Bar对象数组{time, close, open, high, low, volume}[]
meta: object{noData = true | false, nextTime = unix time}
onErrorCallback: function(reason：错误原因) 错误的回调函数。 此函数的唯一参数是文本错误消息。
方法介绍：当图表库需要由日期范围定义的历史K线片段时，将调用此函数。
Bar是具有以下字段的对象：
time: number UTC 时区的毫秒单位时间戳。time对于日K线的时间应为00:00 UTC(而非交易时段的开始时间)。图表库讲根据商品信息中的交易时段调整时间。每个月K线的时间是该月的第一个交易日，且无时间部分。
open: number K线开盘价
high: number K线最高价
low: number K线最低价
close: number K线收盘价
volume: number K线交易量
meta是具有以下字段的对象：
noData 布尔值, 只有在请求的时间段内没有数据时，才应该被设置。
nextTime unix 时间戳(UTC), 历史K线的下一K线时间。只有在请求的时间段内没有数据时，才应该被设置。
关于 periodParams
从 18 版本开始，图表库提供了 countBack 参数，可用于提高数据加载的性能。
from 参数过去并且现在仍然不准确，因为它没有完全考虑到交易品种的交易时段。计算不准确的原因是速度（准确的计算具有线性时间复杂度，而不准确的计算具有恒定的复杂度）。
countBack 图表需要的最小K线数（它可以稍微大一些），用来填充可见范围，以及 to 日期（这是最后加载的K线的日期） ，您只需一个请求即可轻松获取所需的数据。
建议考虑countBack的优先级高于from的优先级，即必须返回[from, to)范围内的数据，但K线数不应小于countBack。如果K线的数量少于 countBack，图表库将再次调用 getBars。
如果您的数据提供服务可以返回准确的K线数，最好在使用from日期的基础上，再使用countBack以提高效率：
示例 1：假设图表在请求中请求 300 根K线，范围为 [2019-06-01T00:00:00..2020-01-01T00:00:00]。 如果您在请求的时间段 ([2019-06-01T00:00:00..2020-01-01T00:00:00]) 中只有 250 根K线并且您返回这 250 根K线，则图表将再次请求在2019-06-01T00:00:00日期之前的数据，以在加载 50 根K线。
示例 2：假设图表在请求中请求 300 根K线，范围为 [2019-06-01T00:00:00..2020-01-01T00:00:00]。 如果您在请求的时间段内没有K线，也可以不需返回 {noData: true，和等于下一个可用数据的时间的nextTime}。您可以简单地返回 2020-01-01T00:00:00 之前的 300 根K线，即使该数据早于 from 日期。
symbolInfo:object SymbolInfo
resolution: string 周期
onRealtimeCallback: function(bar)
bar: object{time, close, open, high, low, volume}
subscriberUID: object
onResetCacheNeededCallback(从1.7开始): function()将在bars数据发生变化时执行
方法介绍：订阅K线数据。图表库将调用onRealtimeCallback方法以更新实时数据。
Remark: 当您调用onRealtimeCallback且K线时间等于最新K线时间时，那么这条最新K线将被您传入的K线所替换。 例:
最近一条K线为 {1419411578413, 10, 12, 9, 11}
调用 onRealtimeCallback({1419411578413, 10, 14, 9, 14})
图表库通过时间1419411578413找出K线，已存在并且是最近的那一个
图表库替换K线，因此现在最近一条K线为 {1419411578413, 10, 14, 9, 14}
Remark 2: 可以使用 onRealtimeCallback 更新最近的K线或添加新K线。 如果您调用此功能尝试更新历史记录中的一个K线时，则会收到错误消息。
Remark 3: 现在，在图表接收到数据后，没有办法改变历史上的K线。
subscriberUID:object
方法介绍：取消订阅K线数据。在调用subscribeBars方法时,图表库将跳过与subscriberUID相同的对象。
symbolInfo:SymbolInfo 商品信息对象
startDate: unix 时间戳, 最左边请求的K线时间
endDate: unix 时间戳, 最右边请求的K线时间
onDataCallback: function(标记数字marks)
resolution: string
方法介绍：图表库调用这个函数来获得可见的K线范围的标记。 图表预期每调用一次getMarks就会调用一次onDataCallback。
mark为具有以下属性的对象:
id: 唯一标识id 。当用户点击标记时，将传递给相应的回调:respective callback
time: unix time, UTC
color:red|green|blue|yellow|{ border: '#ff0000', background: '#00ff00' }
text: 标记弹出式文字。 支持HTML
label: 印在标记上的文字。单字符
labelFontColor: label的文字颜色
minSize: 标记的最小尺寸 (diameter, pixels)
每个K线允许几个标记（现在最多为10个）。不允许标记脱离K线。
Remark: 只有当您声明您的后端是支持标记时才会调用这个函数。supporting marks.
symbolInfo:SymbolInfo object
startDate: unix时间戳 (UTC). Leftmost visible bar's time.
endDate: unix时间戳 (UTC). Rightmost visible bar's time.
onDataCallback: function(array ofmarks)
resolution: string
图表库调用此函数获取可见K线范围的时间刻度标记。图表预期您每个调用getTimescaleMarks会调用一次onDataCallback。
mark为具有以下属性的对象:
id: 唯一标识id 。当用户点击标记时，将传递给相应的回调:respective callback
time: unix time, UTC
color:red|green|blue|yellow| ... | #000000
label: 印在标记上的文字。单字符
tooltip: 字符串串数组。数组的每个元素都是工具提示的单独行内容。
每个K线只允许一个标记。 不允许标记脱离K线。
Remark: 只有当您声明您的后端是支持标记时才会调用这个函数。upporting marks.
callback: function(unixTime)
当图表需要知道服务器时间时，如果配置标志supports_time设置为true，则调用此函数。图表库预期只调用一次回调。所提供的时间没有毫秒。例子：1445324591。它是用来显示倒数的价格范围。
可选的
currentResolution：字符串。 图表上当前选择的分辨率 1.from：unix时间戳（UTC）。 最左边可见K线的时间
to：unix 时间戳（UTC）。 最右侧可见K线的时间
symbolInfo: SymbolInfo 对象
图表库调用此函数来获取将用于计算成交量分布图指标的分辨率。通常，您可能希望实现此方法以更准确地计算指标。实现实际上取决于您可以传输到图表库的成交量以及datafeed中的数据深度。
备注：如果未提供此功能，则图表库使用 currentResolution。
symbols: 商品名称数组
onDataCallback: function(array ofdata)
data:商品报价数据
onErrorCallback: function(reason)
当图表需要报价数据时，将调用此函数。图表库预期在收到所有请求数据时调用onDataCallback。
symbols: 很少更新的商品数组（建议频率为每分钟一次）。这些商品在观察列表中，但它们目前不可见。
fastSymbols: 频繁更新的商品数组（一次在10秒或更快）
onRealtimeCallback: function(array ofdata)
data:商品报价数据
listenerGUID: 监听的唯一标识符
交易终端当需要接收商品的实时报价时调用此功能。图表预期您每次要更新报价时都会调用onRealtimeCallback。
listenerGUID: 监听的唯一标识符
交易终端当不需要再接收商品的实时报价时调用此函数。当图表库遇到listenerGUID相同的对象会跳过subscribeQuotes方法。
symbolInfo:SymbolInfo object
callback: function(depth)
depth: object{snapshot, asks, bids}
snapshot: Boolean - 如果true时asks和bids具有全部深度，否则只包含更新的级别。
asks: 买盘数组{price, volume}
bids: 卖盘数组{price, volume}
交易终端当要接收商品的实时level 2 信息（DOM）时，调用此函数。 图表预期您每次要更新深度数据时都会调用回调。
此方法应返回唯一标识（subscriberUID），用于取消订阅数据。
subscriberUID: String
交易终端当不希望接收此监听时调用此函数。
