3-2、JS Api · tradingView開發文檔

# 3-2、JS Api # [JS Api](#js-api) - - - - - - **這是啥?** 一套JS方法（以實現指定的公共接口）。 **我該怎么使用它?**: 您應該創建一個JS對象，它將以某種方式接收數據，并響應圖表庫的請求。在圖表庫中實現了數據緩存（歷史和商品信息）。當您創建一個實現接口的對象時，只需將它傳遞給圖表庫[Widget的構造函數](Widget-Constructor.html)。 # [Methods](#methods) 1. [onReady](#onreadycallback) 2. [searchSymbols](#searchsymbolsuserinput-exchange-symboltype-onresultreadycallback) 3. [resolveSymbol](#resolvesymbolsymbolname-onsymbolresolvedcallback-onresolveerrorcallback) 4. [getBars](#getbarssymbolinfo-resolution-from-to-onhistorycallback-onerrorcallback-firstdatarequest) 5. [subscribeBars](#subscribebarssymbolinfo-resolution-onrealtimecallback-subscriberuid-onresetcacheneededcallback) 6. [unsubscribeBars](#unsubscribebarssubscriberuid) 7. [calculateHistoryDepth](#calculatehistorydepthresolution-resolutionback-intervalback) 8. [getMarks](#getmarkssymbolinfo-startdate-enddate-ondatacallback-resolution) 9. [getTimescaleMarks](#gettimescalemarkssymbolinfo-startdate-enddate-ondatacallback-resolution) 10. [getServerTime](#getservertimecallback) ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[交易終端專屬](#%E4%BA%A4%E6%98%93%E7%BB%88%E7%AB%AF%E4%B8%93%E5%B1%9E): 1. [getQuotes](#getquotessymbols-ondatacallback-onerrorcallback) 2. [subscribeQuotes](#subscribequotessymbols-fastsymbols-onrealtimecallback-listenerguid) 3. [unsubscribeQuotes](#unsubscribequoteslistenerguid) 4. [subscribeDepth](#subscribedepthsymbolinfo-callback-string) 5. [unsubscribeDepth](#unsubscribedepthsubscriberuid) ### [onReady(callback)](#onreadycallback) ``` 1.callback: function(configurationData) i.configurationData: object (見下文) ``` 此方法旨在提供填充配置數據的對象。這些數據會影響圖表的行為表現，所以它被調用在[服務端定制](Customization-Overview.html#customization-done-through-data-stream)。圖表庫要求您使用回調函數來傳遞datafeed的 `configurationData`參數。 configurationData是一個對象，現在支持以下屬性: ##### [exchanges](#exchanges) 一個交易所數組。 Exchange是一個對象`{value, name, desc}`。 `value`將被作為`exchange`參數傳遞給 [searchSymbols](#searchsymbolsuserinput-exchange-symboltype-onresultreadycallback)。 `exchanges = []`會導致商品查詢列表中看不到交易所過濾器。使用`value = ""`來創建通配符篩選器（所有的交易所）。 ##### [symbols\_types](#symbolstypes) 一個商品類型過濾器數組。該商品類型過濾器是個對象`{name, value}`。`value`將被作為`symbolType`參數傳遞給[searchSymbols](#searchsymbolsuserinput-exchange-symboltype-onresultreadycallback)。 `symbolsTypes`= \[\] 會導致商品查詢列表中看不到商品類型過濾器。使用`value= ""`來創建通配符篩選器（所有的商品類型）。 ##### [supported\_resolutions](#supportedresolutions) 一個表示服務器支持的周期數組，周期可以是數字或字符串。如果周期是一個數字，它被視為分鐘數。字符串可以是“\*D”，“\*W”，“\_M”（\_的意思是任何數字）。格式化詳細參照:[文章](Resolution.html)。 `resolutions = undefined` 或 `resolutions = []` 時，周期擁有默認內容。例:`[1, 15, 240, "D", "6M"]`您將在周期中得到 "1 分鐘, 15 分鐘, 4 小時, 1 天, 6 個月" 。 ##### [supports\_marks](#supportsmarks) 布爾值來標識您的 datafeed 是否支持在K線上顯示標記。 ##### [supports\_timescale\_marks](#supportstimescalemarks) 布爾值來標識您的 datafeed 是否支持時間刻度標記。 ##### [supports\_time](#supportstime) 將此設置為`true`假如您的datafeed提供服務器時間（unix時間）。它用于調整時間刻度上的價格比例。 ##### futures\_regex 如果您想在商品搜索中對期貨進行分組，請設置它。這個正則表達式會將儀器名稱分為兩部分：根和期滿。實例 regex: : `/^(.+)([12]!|[FGHJKMNQUVXZ]\d{1,2})$/`. 它將應用于類型為期貨的圖表。 ### [searchSymbols(userInput, exchange, symbolType, onResultReadyCallback)](#searchsymbolsuserinput-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`的細節 [在這里](Symbology.html#ticker) ### [resolveSymbol(symbolName, onSymbolResolvedCallback, onResolveErrorCallback)](#resolvesymbolsymbolname-onsymbolresolvedcallback-onresolveerrorcallback) 1. `symbolName`: string類型，商品名稱或`ticker`if provided. 2. `onSymbolResolvedCallback`: function([SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84)) 3. `onResolveErrorCallback`: function(reason) 方法介紹：通過商品名稱解析商品信息([SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84))。 ### [getBars(symbolInfo, resolution, from, to, onHistoryCallback, onErrorCallback, firstDataRequest)](#getbarssymbolinfo-resolution-from-to-onhistorycallback-onerrorcallback-firstdatarequest) 1. `symbolInfo`:[SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84) 商品信息對象 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`和`to`與`onHistoryCallback`方法返回的K線時間范圍是否一致，沒有數據時請返回`noData = true` `nextTime`歷史中下一個K線柱的時間。只有在請求的時間段內沒有數據時，才應該被設置。 `noData`只有在請求的時間段內沒有數據時，才應該被設置。 **Remark**:`bar.time`為以毫秒開始的Unix時間戳（UTC標準時區）。 **Remark**:`bar.time`對于日K線預期一個交易日 (未開始交易時) 以 00:00 UTC為起點。圖表庫會根據商品的交易（[Session](Symbology.html#session)）時間進行匹配。 **Remark**:`bar.time`對于月K線為這個月的第一個交易日，除去時間的部分。 ### [subscribeBars(symbolInfo, resolution, onRealtimeCallback, subscriberUID, onResetCacheNeededCallback)](#subscribebarssymbolinfo-resolution-onrealtimecallback-subscriberuid-onresetcacheneededcallback) 1. `symbolInfo`:object [SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84) 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)](#unsubscribebarssubscriberuid) 1. `subscriberUID`:object 方法介紹：取消訂閱K線數據。在調用`subscribeBars`方法時,圖表庫將跳過與`subscriberUID`相同的對象。 ### [calculateHistoryDepth(resolution, resolutionBack, intervalBack)](#calculatehistorydepthresolution-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)](#getmarkssymbolinfo-startdate-enddate-ondatacallback-resolution) 1. `symbolInfo`:[SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84) 商品信息對象 2. `startDate`: unix 時間戳, 最左邊請求的K線時間 3. `endDate`: unix 時間戳, 最右邊請求的K線時間 4. `onDataCallback`: function(標記數字`marks`) 5. `resolution`: string 方法介紹：圖書館調用這個函數來獲得可見的K線范圍的標記。圖表預期每調用一次`getMarks`就會調用一次`onDataCallback`。 `mark`為具有以下屬性的對象: - **id**: 唯一標識id 。當用戶點擊標記時，將傳遞給相應的回調:[respective callback](Widget-Methods.html#onbarmarkclickedcallback) - **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](JS-Api.html#supports_marks). ### [getTimescaleMarks(symbolInfo, startDate, endDate, onDataCallback, resolution)](#gettimescalemarkssymbolinfo-startdate-enddate-ondatacallback-resolution) 1. `symbolInfo`:[SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84) object 2. `startDate`: unix時間戳 (UTC). Leftmost visible bar's time. 3. `endDate`: unix時間戳 (UTC). Rightmost visible bar's time. 4. `onDataCallback`: function(array of`mark`s) 5. `resolution`: string 圖表庫調用此函數獲取可見K線范圍的時間刻度標記。圖表預期您每個調用getTimescaleMarks會調用一次onDataCallback。 mark為具有以下屬性的對象: - **id**: 唯一標識id 。當用戶點擊標記時，將傳遞給相應的回調:[respective callback](Widget-Methods.html#onbarmarkclickedcallback) - **time**: unix time, UTC - **color**:`red`|`green`|`blue`|`yellow`| ... | #000000 - **label**: 印在標記上的文字。單字符 - **tooltip**: 字符串串數組。數組的每個元素都是工具提示的單獨行內容。每個K線只允許一個標記。不允許標記脫離K線。 **Remark**: 只有當您聲明您的后端是支持標記時才會調用這個函數。[upporting marks](JS-Api.html#supports_timescale_marks). ### [getServerTime(callback)](#getservertimecallback) 1. `callback`: function(unixTime) 當圖表需要知道服務器時間時，如果配置標志`supports_time`設置為`true`，則調用此函數。圖表庫預期只調用一次回調。所提供的時間沒有毫秒。例子：1445324591。它是用來顯示倒數的價格范圍。 ## ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[交易終端專屬](#%E4%BA%A4%E6%98%93%E7%BB%88%E7%AB%AF%E4%B8%93%E5%B1%9E) ### ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[getQuotes(symbols, onDataCallback, onErrorCallback)](#getquotessymbols-ondatacallback-onerrorcallback) 1. `symbols`: 商品名稱數組 2. `onDataCallback`: function(array of`data`) 1. `data`:[商品報價數據](Quotes.html#symbol-quote-data) 3. `onErrorCallback`: function(reason) 當圖表需要報價數據時，將調用此函數。圖表庫預期在收到所有請求數據時調用onDataCallback。 ### ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[subscribeQuotes(symbols, fastSymbols, onRealtimeCallback, listenerGUID)](#subscribequotessymbols-fastsymbols-onrealtimecallback-listenerguid) 1. `symbols`: 很少更新的商品數組（建議頻率為每分鐘一次）。這些商品在觀察列表中，但它們目前不可見。 2. `fastSymbols`: 頻繁更新的商品數組（一次在10秒或更快） 3. `onRealtimeCallback`: function(array of`data`) 1. `data`:[商品報價數據](Quotes.html#symbol-quote-data) 4. `listenerGUID`: 監聽的唯一標識符交易終端當需要接收商品的實時報價時調用此功能。圖表預期您每次要更新報價時都會調用`onRealtimeCallback`。 ### ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[unsubscribeQuotes(listenerGUID)](#unsubscribequoteslistenerguid) 1. `listenerGUID`: 監聽的唯一標識符交易終端當不需要再接收商品的實時報價時調用此函數。當圖表庫遇到`listenerGUID`相同的對象會跳過`subscribeQuotes`方法。 ### ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[subscribeDepth(symbolInfo, callback): String](#subscribedepthsymbolinfo-callback-string) 1. `symbolInfo`:[SymbolInfo](Symbology.html#%E5%95%86%E5%93%81%E4%BF%A1%E6%81%AF%E7%BB%93%E6%9E%84) 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），用于取消訂閱數據。 ### ![](https://box.kancloud.cn/2869f58f691f1e2af0bf569197459ff8_20x20.png)[unsubscribeDepth(subscriberUID)](#unsubscribedepthsubscriberuid) 1. `subscriberUID`: String 交易終端當不希望接收此監聽時調用此函數。