JS Api

这是啥? 一套JS方法（特定的公共接口）。
我该怎么使用它?: 您应该创建一个JS对象，它将以某种方式接收数据，并响应Charting Library请求。

在图表库中实现了数据缓存（历史和商品信息）。当您创建一个实现接口的对象时，只需将它传递给图表库Widget的构造函数。

Methods

1. onReady
2. searchSymbols
3. resolveSymbol
4. getBars
5. subscribeBars
6. unsubscribeBars
7. calculateHistoryDepth
8. getMarks
9. getTimescaleMarks
10. getServerTime

交易终端专属:

1. getQuotes
2. subscribeQuotes
3. unsubscribeQuotes
4. subscribeDepth
5. unsubscribeDepth

onReady(callback)

1.callback: function(configurationData)
    i.configurationData: object (见下文)

此方法旨在提供填充配置数据的对象。这些数据会影响图表的行为表现，所以它被调用在服务端定制。

图表库要求您使用回调函数来传递datafeed的configurationData参数。

configurationData是一个对象，现在支持以下属性:

exchanges

一个交易所数组。 Exchange是一个对象{value, name, desc}。

value将被作为exchange参数传递给 searchSymbols (见下文)。

exchanges= []会导致商品查询列表中看不到交易所过滤器。使用value= ""来创建通配符筛选器（所有的交易所）。

symbols_types

一个商品类型过滤器数组。该商品类型过滤器是个对象{name, value}。value将被作为symbolType参数传递给searchSymbolsB。

symbolsTypes= [] 会导致商品查询列表中看不到商品类型过滤器。 使用value= ""来创建通配符筛选器（所有的商品类型）。

supported_resolutions

一个表示服务器支持的分辨率数组，分辨率可以是数字或字符串。 如果分辨率是一个数字，它被视为分钟数。 字符串可以是“*D”，“*W”，“_M”（_的意思是任何数字）。格式化详细参照:文章。

resolutions=undefined 或 [] 时，分辨率拥有默认内容 (见：http://tradingview.com/e/)。

例:[1, 15, 240, "D", "6M"]您将在分辨率中得到 “1 分钟, 15 分钟, 4 小时, 1 天, 6 个月” 。

supports_marks

布尔值来标识您的 datafeed 是否支持在K线上显示标记。

supports_timescale_marks

布尔值来标识您的 datafeed 是否支持时间刻度标记。

supports_time

将此设置为true假如您的datafeed提供服务器时间（unix时间）。 它用于调整时间刻度上的价格比例。

futures_regex 如果您想在商品搜索中对期货进行分组，请设置它。 这个 REGEX 应该将仪器名称分为两部分：根和期满。 实例 regex: : /^(.+)([12]!|[FGHJKMNQUVXZ]\d{1,2})$/. 它将应用于类型为期货的图表。

searchSymbols(userInput, exchange, symbolType, onResultReadyCallback)

1. userInput: string，用户在商品搜索框中输入的文字。
2. exchange:string，请求的交易所（由用户选择）。空值表示没有指定。
3. symbolType: string，请求的商品类型：指数、股票、外汇等等（由用户选择）。空值表示没有指定。
4. onResultReadyCallback: function(result)
   1. result: 数组 (见下文)

方法介绍：提供一个匹配用户搜索的商品列表。result为预期的商品 ，像下面这样:

[
    {
        "symbol": <商品缩写名>,
        "full_name": <商品全称 -- 例: BTCE:BTCUSD>,
        "description": <商品描述>,
        "exchange": <交易所名>,
        "ticker": <商品代码, 可选>,
        "type": "stock" | "futures" | "bitcoin" | "forex" | "index"
    }, {
        //    .....
    }
]

如果没有找到商品，则应该使用空数组来调用回调。查看更多关于ticker值的细节 在这里

resolveSymbol(symbolName, onSymbolResolvedCallback, onResolveErrorCallback)

1. symbolName: string类型，商品名称 或ticker
   if provided.
2. onSymbolResolvedCallback: function(SymbolInfo)
3. onResolveErrorCallback: function(reason)

方法介绍：通过商品名称解析商品信息(SymbolInfo)。

getBars(symbolInfo, resolution, from, to, onHistoryCallback, onErrorCallback, firstDataRequest)

1. symbolInfo:SymbolInfo 商品信息对象
2. resolution: string （分辨率）
3. from: unix 时间戳, 最左边请求的K线时间
4. to: unix 时间戳, 最右边请求的K线时间
5. onHistoryCallback: function(数组bars,meta={ noData = false })
   1. bars: Bar对象数组{time, close, open, high, low, volume}[]
   2. meta: object{noData = true | false, nextTime = unix time}
6. onErrorCallback: function(reason：错误原因)
7. firstDataRequest: 布尔值，以标识是否第一次调用此商品/分辨率的历史记录。当设置为true时
   你可以忽略to参数（这取决于浏览器的Date.now()) 并返回K线数组直到当前K线（包括它）。

方法介绍：通过日期范围获取历史K线数据。图表库希望通过onHistoryCallback仅一次调用，接收所有的请求历史。而不是被多次调用。

发生不断自动刷新图表问题时，请检查from与onHistoryCallback方法返回的bars时间是否一致，没有数据时请返回noData = true

nextTime历史中下一个K线柱的时间。 只有在请求的时间段内没有数据时，才应该被设置。

noData只有在请求的时间段内没有数据时，才应该被设置。

Remark:bar.time为以毫秒开始的Unix时间戳（UTC标准时区）。

Remark:bar.time对于日K线预期一个交易日 (未开始交易时) 以 00:00 UTC为起点。 图表库会根据商品的交易（Session）时间进行匹配。

Remark:bar.time对于月K线为这个月的第一个交易日，除去时间的部分。

subscribeBars(symbolInfo, resolution, onRealtimeCallback, subscriberUID, onResetCacheNeededCallback)

1. symbolInfo:object SymbolInfo
2. resolution: string 分辨率
3. onRealtimeCallback: function(bar)
   1. bar: object{time, close, open, high, low, volume}
4. subscriberUID: object
5. onResetCacheNeededCallback(从1.7开始): function()将在bars数据发生变化时执行

方法介绍：订阅K线数据。图表库将调用onRealtimeCallback方法以更新实时数据。

Remark: 当您调用onRealtimeCallback且K线时间等于最近一条K线时间时，那么这条最近的K线将被您传入的K线所替换。 例:

1. 最近一条K线为 {1419411578413, 10, 12, 9, 11}
2. 调用 onRealtimeCallback({1419411578413, 10, 14, 9, 14})
3. 图表库通过时间1419411578413找出K线，已存在并且是最近的那一个
4. 图表库替换K线，因此现在最近一条K线为 {1419411578413, 10, 14, 9, 14}

Remark 2: 是否可以更新最近的K线或追加一条新的，取决于onRealtimeCallback。 如果您调用此功能尝试更新历史记录中的一个K线时，则会收到错误消息。

Remark 3: 现在，在图表接收到数据后，没有办法改变历史上的K线。

unsubscribeBars(subscriberUID)

1. subscriberUID:object

方法介绍：取消订阅K线数据。在调用subscribeBars方法时,图表库将跳过与subscriberUID相同的对象。

calculateHistoryDepth(resolution, resolutionBack, intervalBack)

1. resolution: 请求商品的分辨率
2. resolutionBack: 期望历史周期刻度。支持的值:D|M
3. intervalBack: 数量

方法介绍：图表库在它要请求一些历史数据的时候会调用这个函数，让你能够覆盖所需的历史深度。

通过传递的参数，可以让您知道要获得什么样的K线数据。 以下是几个例子:

• calculateHistoryDepth("D", "M", 12)
  调用: 图表库请求12个月的日线数据
• calculateHistoryDepth(60, "D", 15)
  调用: 图表库请求15天的60分钟数据

如果你不想重写处理方法，这个函数应该返回undefined。如果你想要重写，它应该返回一个对象{resolutionBack, intervalBack}。

例子:

假设实现为

Datafeed.prototype.calculateHistoryDepth = function(resolution, resolutionBack, intervalBack) {
    if (period == "1D") {
        return {
            resolutionBack: 'M',
            intervalBack: 6
        };
    }
}

以上代码为当图表库将要求分辨率为1D，历史为6个月的深度。 在其他情况下，历史深度将具有其他默认值。

getMarks(symbolInfo, startDate, endDate, onDataCallback, resolution)

1. symbolInfo:SymbolInfo 商品信息对象
2. startDate: unix 时间戳, 最左边请求的K线时间
3. endDate: unix 时间戳, 最右边请求的K线时间
4. onDataCallback: function(标记数字marks)
5. 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.

getTimescaleMarks(symbolInfo, startDate, endDate, onDataCallback, resolution)

1. symbolInfo:SymbolInfo object
2. startDate: unix时间戳 (UTC). Leftmost visible bar’s time.
3. endDate: unix时间戳 (UTC). Rightmost visible bar’s time.
4. onDataCallback: function(array ofmarks)
5. 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.

getServerTime(callback)

1. callback: function(unixTime)

当图表需要知道服务器时间时，如果配置标志supports_time设置为true，则调用此函数。图表库预期只调用一次回调。所提供的时间没有毫秒。例子：1445324591。它是用来显示倒数的价格范围。

交易终端专属" class="reference-link">交易终端专属

getQuotes(symbols, onDataCallback, onErrorCallback)" class="reference-link">getQuotes(symbols, onDataCallback, onErrorCallback)

1. symbols: 商品名称数组
2. onDataCallback: function(array ofdata)
   1. data:商品报价数据
3. onErrorCallback: function(reason)

当图表需要报价数据时，将调用此函数。图表库预期在收到所有请求数据时调用onDataCallback。

subscribeQuotes(symbols, fastSymbols, onRealtimeCallback, listenerGUID)" class="reference-link">subscribeQuotes(symbols, fastSymbols, onRealtimeCallback, listenerGUID)

1. symbols: 很少更新的商品数组（建议频率为每分钟一次）。这些商品在观察列表中，但它们目前不可见。
2. fastSymbols: 频繁更新的商品数组（一次在10秒或更快）
3. onRealtimeCallback: function(array ofdata)
   1. data:商品报价数据
4. listenerGUID: 监听的唯一标识符

交易终端当需要接收商品的实时报价时调用此功能。图表预期您每次要更新报价时都会调用onRealtimeCallback。

unsubscribeQuotes(listenerGUID)" class="reference-link">unsubscribeQuotes(listenerGUID)

1. listenerGUID: 监听的唯一标识符

交易终端当不需要再接收商品的实时报价时调用此函数。当图表库遇到listenerGUID相同的对象会跳过subscribeQuotes方法。

subscribeDepth(symbolInfo, callback): String" class="reference-link">subscribeDepth(symbolInfo, callback): String

1. symbolInfo:SymbolInfo object
2. callback: function(depth)
   1. depth: object{snapshot, asks, bids}
      1. snapshot: Boolean - 如果true时asks和bids具有全部深度，否则只包含更新的级别。
      2. asks: 买盘数组{price, volume}
      3. bids: 卖盘数组{price, volume}

交易终端当要接收商品的实时level 2 信息（DOM）时，调用此函数。 图表预期您每次要更新深度数据时都会调用回调。

此方法应返回唯一标识（subscriberUID），用于取消订阅数据。

unsubscribeDepth(subscriberUID)" class="reference-link">unsubscribeDepth(subscriberUID)

1. subscriberUID: String

交易终端当不希望接收此监听时调用此函数。