4-3、Widget 方法

Widget方法

---

以下是widget支持的方法列表。您可以使用widget构造函数返回给您的widget对象来调用它们。

Remark: 请注意，只有在onChartReady回调触发后才可以调用这些方法。

widget.onChartReady(function() {
    // 现在可以调用其他widget的方法了
});

Methods

• 订阅图表事件

  • onChartReady(callback)

  • headerReady()

  • onGrayedObjectClicked(callback)

  • onShortcut(shortcut, callback)

  • subscribe(event, callback)

  • unsubscribe(event, callback)

• 图表动作

  • chart()

  • getLanguage()

  • setSymbol(symbol, interval, callback)

  • remove()

  • closePopupsAndDialogs()

  • selectLineTool(drawingId)

  • selectedLineTool()

  • takeScreenshot()

  • takeClientScreenshot()

  • lockAllDrawingTools()

  • hideAllDrawingTools()

  • magnetEnabled

  • magnetMode

  • startFullscreen

  • exitFullscreen

• 保存/加载图表

  • save(callback)

  • load(state)

  • getSavedCharts(callback)

  • loadChartFromServer(chartRecord)

  • saveChartToServer(onCompleteCallback, onFailCallback, saveAsSnapshot, options)

  • removeChartFromServer(chartId, onCompleteCallback)

• 自定义UI控件

  • onContextMenu(callback)

  • createButton(options)

• 对话框

  • showNoticeDialog(params)

  • showConfirmDialog(params)

  • showLoadChartDialog()

  • showSaveAsChartDialog()

• Getters

  • symbolInterval(callback)

  • mainSeriesPriceFormatter()

  • getIntervals()

  • getStudiesList()

  • undoRedoState()

  • getTheme()

• 定制

  • changeTheme(themeName)

  • addCustomCSSFile(url)

  • applyOverrides(overrides)

  • applyStudiesOverrides(overrides)

• 交易终端专属

  • watchList()

  • news()

• 多图表布局

  • chart(index)

  • activeChart()

  • chartsCount()

  • layout()

  • setLayout(layout)

  • layoutName()

  • symbolSync()

  • intervalSync()

  • crosshairSync()

  • timeSync()

订阅图表事件

onChartReady(callback)

1. callback: function()

当图表初始化并准备就绪时，图表库将调用提供的回调。 你可以从这一刻安全地调用所有其他方法。

headerReady()

返回一个Promise对象，该对象应该在图表库头部widget API准备就绪时用于处理其他事件（例如: createButton）。

onGrayedObjectClicked(callback)

1. callback: function(subject)

   1. subject: object{type, name}

      1. type:drawing|study

      2. name: string, 被点击的主题名称

每次用户点击灰色的对象时，图表库都会调用此回调函数。例：

new TradingView.widget({
    drawings_access: {
        type: "black",
        tools: [
            { name: "Regression Trend" },
            { name: "Trend Angle", grayed: true },
        ]
    },
    studies_access: {
        type: "black",
        tools: [
            { name: "Aroon" },
            { name: "Balance of Power", grayed: true },
        ]
    },
    <...> // 其他widget设置
});

widget.onChartReady(function() {
    widget.onGrayedObjectClicked(function(data) {
        // 当您尝试创建能量均衡指标或趋势形状时
        // 此方法将被调用

        alert(data.name + " is grayed out!");
    })
});

onShortcut(shortcut, callback)

1. shortcut

2. callback: function(data)

每当按下快捷键时，图表库将会调用此回调。

例:

widget.onShortcut("alt+s", function() {
  widget.chart().executeActionById("symbolSearch");
});

subscribe(event, callback)

1. event:

Event name	Library Version	Description
toggle_sidebar		显示/隐藏 绘图工具栏
indicators_dialog		显示 指标对话框
toggle_header		显示/隐藏 图表头
edit_object_dialog		显示 图表/指标属性对话框
chart_load_requested		即将加载新图表
chart_loaded
mouse_down
mouse_up
drawing	1.7	绘图将添加到图表中。参数包含一个带有 value 字段的对象，该字段与绘图名称相对应。
study	1.7	指标将添加到图表中。参数包含一个带有 value 字段的对象，该字段与指标名称相对应。
undo	1.7
redo	1.7
undo_redo_state_changed	1.14	Undo/Redo状态已更改。参数包含一个具有Undo/Redo堆栈状态的对象。该对象与UndoRedoState方法的返回值具有相同的结构。
reset_scales	1.7	重置比例按钮被点击
compare_add	1.7	显示比较对话框
add_compare	1.7	添加了一个商品的比较
load_study template	1.7	一个指标模板被加载
onTick		最新k线被更新
onAutoSaveNeeded		用户修改了图表, Chart change 表示可以撤销用户的任何操作。回调函数不可以在5秒内多次调用, 详见: auto_save_delay
onScreenshotReady		服务器返回屏幕截图URL
onMarkClick		用户点击K线标记。标记ID将作为参数传递
onTimescaleMarkClick		用户点击时间刻度标记。标记ID将作为参数传递
onSelectedLineToolChanged		选择的线条工具已更改
study_event	1.15	指标从图表中删除。回调函数接收2个参数: 指标id和event类型 (当前这个参数唯一可能的值是remove)
series_event	16	与系列有关的事件。回调函数接收1个参数: event类型（当前，此参数唯一可能的值为price_scale_changed）
drawing_event	1.15	隐藏，显示，移动，移除或单击绘图。 回调函数接收2个参数: 指标id和event类型。event类型的可能值是hide，show、move、remove、click
study_properties_changed	1.14	指标属性已更改。实体ID将作为参数传递。
series_properties_changed	1.15	主数据列属性发生变化
panes_height_changed	1.15	窗格大小已更改。
panes_order_changed	1.15	窗格订单发生变化。
layout_about_to_be_changed		图表的数量或位置即将改变
layout_changed		图表的数量或位置已更改
activeChartChanged		活动的图表已变更

2.callback: function(arguments)

当GUIevent发生时，图表库将调用callback。 每个事件都可以有不同的参数。

unsubscribe(event, callback)

取消订阅特定事件 (即上表中的事件之一) 。

图表动作

chart()

返回图表对象，可用于调用图表方法

getLanguage()

从版本17开始。

返回Widget的语言

setSymbol(symbol, interval, callback)

1. symbol: string

2. interval: string

3. callback: function()

使图表更改其商品和周期。新商品的数据到达后调用回调。

remove()

从您的页面中删除widget。

closePopupsAndDialogs()

调用此方法会关闭上下文菜单或对话框（如果已显示）。

selectLineTool(drawingId)

1. drawingId: 可以为一个标识符 或

   1. cursor

   2. dot

   3. arrow_cursor

   4. eraser

   5. measure

   6. zoom

   7. brush

选择与绘图按钮上的单击相同的形状或光标。

selectedLineTool()

返回所选形状或光标的标识符（见上文）。

takeScreenshot()

此方法创建图表的快照并将其上传到服务器。

完成后, 调用 onScreenshotReady 回调函数。

快照的 URL 将作为参数传递给回调函数。

takeClientScreenshot(options)

此方法获取图表布局的快照，并将其作为 Promise 中的 HTML 画布元素返回。

options 是一个 optional 对象，具有以下字段：

• backgroundColor：背景颜色

• borderColor: 图表边框颜色

• font：图例文本字体系列

• fontSize：图例文本字体大小

• legendMode: vertical 或 horizontal

• hideResolution：如果图表的真实分辨率被隐藏

lockAllDrawingTools()

此方法返回一个 WatchedValue 对象, 可用于读取/设置/监视 "锁定所有绘图工具" 按钮的状态。

hideAllDrawingTools()

此方法返回 WatchedValue 对象, 该对象可用于读取/设置/监视 "隐藏所有绘图工具" 按钮的状态。

magnetEnabled()

此方法返回 WatchedValue 对象, 该对象可用于读取/设置/监视 "磁铁" 按钮的状态。

magnetMode()

此方法返回 WatchedValue 对象, 该对象可用于读取/设置/监视 "磁铁" 的模式

可用模式:

• 0 - 弱磁模式

• 1 - 强磁模式

startFullscreen()

此方法进入全屏模式。

exitFullscreen()

此方法退出全屏模式。

保存/加载图表

save(callback)

1. callback: function(object)

将图表状态保存到JS对象。图表库将调用您的回调函数并将状态对象作为参数传递。

此调用是低级保存/加载API的一部分。

load(state)

1. state: object

从state对象加载图表。 此调用是低级保存/加载API的一部分。

getSavedCharts(callback)

1. callback: function(objects)

objectsis an array of:

1. id

2. name

3. image_url

4. modified_iso

5. short_symbol

6. interval

返回当前用户在服务器上保存的图表描述列表。

loadChartFromServer(chartRecord)

1. chartRecord是您使用getSavedCharts(callback) 返回的对象

从服务器加载并显示图表。

saveChartToServer(onCompleteCallback, onFailCallback, saveAsSnapshot, options)

1. onCompleteCallback: function()

2. onFailCallback: function()

3. saveAsSnapshot: should be alwaysfalse

4. options: object{ chartName }

   1. chartName: 图表名称。应指定新图表并重命名。

   2. defaultChartName: 图表的默认名称。 如果当前图表没有名称，它将被使用。

将当前图表保存到服务器。

removeChartFromServer(chartId, onCompleteCallback)

1. chartId:调用getSavedCharts(callback)后获得的id

2. onCompleteCallback: function()

从服务器移除图表。

自定义UI控件

onContextMenu(callback)

1. callback: function(unixtime, price). 此回调将返回一个值（见下文）。

每当用户在图表上打开文菜单时，图表库就会调用回调函数。 传递给回调函数的参数包含图表上单击点的unix时间和价格。

您必须返回具有以下格式的对象数组，才能在菜单中添加或删除项目。

{
    position: 'top' | 'bottom',
    text: 'Menu item text',
    click: <onItemClicked callback>
}

• position: 项目在菜单中的位置

• text: 菜单项文本

• click: 当用户选择您的菜单项时将被调用

添加分隔符使用减号。 例:{ text: "-", position: "top" }.

要从菜单中删除现有项目，请在项目文本前面使用减号。 例:{ text: "-Objects Tree..." }

例:

widget.onChartReady(function() {
    widget.onContextMenu(function(unixtime, price) {
        return [{
            position: "top",
            text: "First top menu item, time: " + unixtime + ", price: " + price,
            click: function() { alert("First clicked."); }
        },
        { text: "-", position: "top" },
        { text: "-Objects Tree..." },
        {
            position: "top",
            text: "Second top menu item 2",
            click: function() { alert("Second clicked."); }
        }, {
            position: "bottom",
            text: "Bottom menu item",
            click: function() { alert("Third clicked."); }
        }];
    });

createButton(options)

1. options: object { align: "left" }

   • align: right | left. default: left

在图表的顶部工具栏中创建一个新的DOM元素，并为此按钮返回HTMLElement。 您可以使用它在图表上添加自定义控件。

**注意：**必须在headerReady返回的 Promise 为resolved之后使用。

例：

widget.headerReady().then(function() {
    var button = widget.createButton();
    button.setAttribute('title', 'My custom button tooltip');
    button.addEventListener('click', function() { alert("My custom button pressed!"); });
    button.textContent = 'My custom button caption';
});

对话框

从 1.6 版本开始

showNoticeDialog(params)

1. params: 对象:

   1. title: 标题

   2. body: 正文

   3. callback: 当按下ok按钮时调用的函数。

此方法显示一个对话框，其中包含自定义标题和文本以及“确定”按钮。

showConfirmDialog(params)

1. params: 对象:

   1. title: 标题

   2. body: 正文

   3. callback(result): 当按下ok按钮时调用的函数。 result点击ok时为true, 否则为false。

此方法显示一个带有自定义标题和文本以及"确定"、"取消"按钮的对话框。

showLoadChartDialog()

显示加载图表对话框。

showSaveAsChartDialog()

显示另存为...图表对话框。

Getters

symbolInterval()

图表库返回一个包含symbol和interval的对象。

mainSeriesPriceFormatter()

返回一个带有format方法的对象，用来批量格式化价格。 被引入在1.5.

getIntervals()

返回支持的周期数组。被引入在1.7.

getStudiesList()

返回全部技术指标数组，您可以通过它们创建技术指标指示器。

undoRedoState()

返回具有Undo/Redo堆栈状态的对象。 该对象具有以下属性:

• enableUndo: boolean类型, 表示撤消操作是否可用。

• undoText: 下一个撤消操作的名称。如果撤消堆栈为空，则它的值为undefined。

• enableRedo: boolean类型, 表示恢复操作是否可用。

• redoText: 下一个恢复操作的名称。如果恢复堆栈为空，则它的值为undefined。

getTheme()

从版本16开始。

此方法返回图表主题名称。

console.log(widget.getTheme());

定制

changeTheme(themeName)

该方法在版本1.13中引入

1. themeName 可以为 "Light" | "Dark"

此方法可更改图表主题而不重新加载图表。

您还可以使用Widget构造函数中的theme来创建具有自定义主题的图表。

addCustomCSSFile(url)

1. url 绝对或相对路径的 static 文件夹

该方法在版本1.3中引入。从1.4开始，使用custom_css_url替代。

applyOverrides(overrides)

该方法在版本1.5中引入

1. overrides为一个对象，和overrides相同。

此方法将 覆盖 图表属性，而无需重新加载图表。

applyStudiesOverrides(overrides)

该方法在版本1.9中引入

1. overrides 为一个对象，和studies_overrides相同。

此方法将 覆盖 指标的指标样式或输入参数，而无需重新加载图表。

交易终端专属

以下方法只在交易终端可用.

watchList()

该方法在版本1.9中引入

返回一个对象来操作观察列表。 该对象具有以下方法：

1. defaultList()- 允许您获取默认的商品列表。

2. getList(id?: string)- 允许您获取商品列表。 如果未传递id 则返回当前列表。 如果没有监视列表则返回 null 。

3. setActiveList(id: string) - 允许您通过 id 创建当前活动列表。

4. getActiveListId() - 允许您获取当前列表的ID。如果没有活动列表则返回null 。

5. getAllLists() - 允许您获取所有列表。如果没有监视列表则返回null 。

6. setList(symbols: string[])- 允许您将商品列表设置到观察列表中。 它将替换整个列表。已过时。将在 1.13版本中删除。请改用 updateList。

7. updateList(listId: string, symbols: string[]) - 允许您编辑商品列表。

8. renameList(listId: string, newName: string) - 允许您将列表重命名为 newName.

9. createList(listName?: string, symbols?: string[]) - 允许您创建具有listName 名称的符号列表。如果未传递 listName 参数或者没有监视列表，则返回 null。

10. saveList(list: SymbolList) - 允许您保存一个商品列表， list 是具有以下key的集合对象:

```js

id: string;
title: string;
symbols: string[];
```

如果没有监视列表或者已有一个等价列表，则返回`false` 否则返回 `true` 。

11. deleteList(listId: string) - 允许您删除商品列表。 12. onListChanged()- 当在监视列表中的商品更改时, 可以使用此方法进行通知。您可以使用此方法返回的 Subscription对象进行订阅和取消订阅。

1. onActiveListChanged() - 当选择了不同的监视列表时, 可以使用此方法进行通知。您可以使用此方法返回的 Subscription对象进行订阅和取消订阅。

2. onListAdded() - - 当新的列表添加到监视列表中时, 可以使用此方法进行通知。您可以使用此方法返回的 Subscription对象进行订阅和取消订阅。

3. onListRemoved() - 当监视列表中删除商品列表时, 可以使用此方法进行通知。您可以使用此方法返回的 Subscription对象进行订阅和取消订阅。

4. onListRenamed() - - 当监视列表中重命名商品列表时, 可以使用此方法进行通知。您可以使用此方法返回的 Subscription对象进行订阅和取消订阅。

news()

从版本 21 开始。

返回一个使用用于控制新闻小部件的对象解析的 Promise。 该对象具有以下方法：

1. refresh() - 允许您按需刷新新闻列表。

const widget = new TradingView.widget(/* options */);

widget.onChartReady(() => {
    widget.news().then(newsApi => {
        // newsApi 可以使用了。
    });
});

多图表布局

chart(index)

1. index: 从0开始的图表索引，默认为0。

返回chart对象，用于调用Chart-Methods

activeChart()

返回当前chart对象，用于调用Chart-Methods

chartsCount()

返回当前布局的图表数目。

layout()

返回当前布局模式。 可能的值：4, 6, 8, s, 2h, 2-1, 2v, 3h, 3v, 3s, 1-2, 3r, 4h, 4v, 4s, 1-3, 2-2, 1-4, 5s, 6c, 8c.

setLayout(layout)

1. layout: 可能的值:4, 6, 8, s, 2h, 2-1, 2v, 3h, 3v, 3s, 1-2, 3r, 4h, 4v, 4s, 1-3, 2-2, 1-4, 5s, 6c, 8c.

变更当前图表布局。

layoutName()

返回当前布局名称。 如果尚未保存当前布局，则返回undefined。

symbolSync()

返回一个 WatchedValue 对象，该对象可用于读取/设置/监视图表之间的上去同步状态。

if (widget.symbolSync().value()) {
    // Do something
}

intervalSync()

返回一个 WatchedValue 对象，该对象可用于读取/设置/监视图表之间的间隔同步状态。

widget.intervalSync().setValue(true);

crosshairSync()

返回一个 WatchedValue 对象，该对象可用于读取/设置/监视图表之间十字准线同步的状态。

widget.crosshairSync().setValue(true);

timeSync()

返回一个 WatchedValue 对象，该对象可用于读取/设置/监视图表之间的时间同步状态。

widget.timeSync().setValue(true);

也可以看看

• 图表方法

• 定制概述

• Widgetg构造函数

• 存储与加载图表

• 指标覆盖

• 覆盖