IChartWidgetApi的理解

文档地址：https://www.tradingview.com/charting-library-docs/latest/api/interfaces/Charting_Library.IChartWidgetApi
以下是对这份文档的理解：
一、概述
这是关于 “IChartWidgetApi” 的接口文档，它似乎是一个用于与图表进行交互的主要 API。可以通过特定的 widget（可能是 “IChartingLibraryWidget”）的方法来获取这个接口实例，如 “chart” 或 “activeChart” 方法。
二、方法详解
applyLineToolsState：
功能：将线工具状态应用于图表，以恢复保存的绘图内容。需要特定的功能集（“saveload_separate_drawings_storage”）启用。
参数：一个 “LineToolsAndGroupsState” 类型的对象，表示线工具状态。
返回值：一个 Promise，当操作完成后 resolve，无具体返回值。
applyStudyTemplate：
功能：将研究模板应用于图表。
参数：一个对象，代表研究模板。
返回值：无。
availableZOrderOperations：
功能：获取指定实体集的可用 Z 序操作对象。
参数：一个只读的实体 ID 数组。
返回值：“AvailableZOrderOperations” 类型的对象。
barTimeToEndOfPeriod：
功能：获取给定 Unix 时间戳对应的柱线时间到周期结束的时间。
参数：一个数字，表示日期时间戳。
返回值：一个数字，表示转换后的时间。
bringForward：
功能：将源在 Z 序中向上移动一层。
参数：一个只读的实体 ID 数组。
返回值：无。
bringToFront：
功能：将源移动到 Z 序的顶部。
参数：一个只读的实体 ID 数组。
返回值：无。
canZoomOut：
功能：检查图表是否可以缩小。
返回值：如果可以缩小则返回 true，否则返回 false。
cancelSelectBar：
功能：取消任何活动的柱线选择请求。
返回值：无。
chartType：
功能：返回主序列样式类型。
返回值：“SeriesType” 类型的值。
clearMarks：
功能：清除图表上的标记。
参数：可选的 “ClearMarksMode” 类型参数，用于指定要清除的标记类型。如果未指定，则清除柱线和时间轴上的所有标记。
返回值：无。
createAnchoredShape：
功能：创建一个新的锚定图形。
参数：一个 “PositionPercents” 类型的对象表示位置，以及一个 “CreateAnchoredShapeOptions” 类型的对象表示创建选项。
返回值：新图形的实体 ID。
createExecutionShape：（已弃用）
功能：在图表上创建一个新的交易执行图形。
参数：可选的 “UndoOptions” 类型参数。
返回值：一个用于与执行图形交互的 API 对象。
createMultipointShape：
功能：创建一个新的多点图形。
参数：一个 “ShapePoint” 数组表示点，以及一个 “CreateMultipointShapeOptions” 类型的对象表示创建选项。
返回值：新图形的实体 ID，如果创建成功，否则为 null。
createOrderLine：（已弃用）
功能：在图表上创建一个新的交易订单图形。
参数：可选的 “UndoOptions” 类型参数。
返回值：一个用于与订单图形交互的 API 对象。
createPositionLine：（已弃用）
功能：在图表上创建一个新的交易位置图形。
参数：可选的 “UndoOptions” 类型参数。
返回值：一个用于与位置图形交互的 API 对象。
createShape：
功能：创建一个新的单点图形。
参数：一个 “ShapePoint” 类型的对象表示点，以及一个 “CreateShapeOptions” 类型的对象表示创建选项。
返回值：新图形的实体 ID，如果创建成功，否则为 null。
createStudy：
功能：向图表添加指标或用于比较的符号。
参数：指标名称、可选的强制覆盖、锁定、输入、覆盖和创建选项等参数。
返回值：一个 Promise，解析为创建的研究的实体 ID。
createStudyTemplate：
功能：将当前研究模板保存为一个对象。
参数：一个 “CreateStudyTemplateOptions” 类型的对象表示模板选项。
返回值：一个研究模板对象。
crossHairMoved：
功能：获取一个订阅对象，用于监听十字光标在图表上移动的事件。
返回值：一个订阅对象，订阅函数接收 “CrossHairMovedEventParams” 类型的参数。
dataReady：
功能：提供一个回调函数，当图表数据加载完成时调用。如果在调用此方法时数据已经加载，则立即调用回调函数。
参数：可选的回调函数。
返回值：一个布尔值，表示数据是否已准备好。
endOfPeriodToBarTime：
功能：获取周期结束时间到柱线时间。
参数：一个数字，表示日期时间戳。
返回值：一个数字，表示转换后的时间。
executeActionById：
功能：执行一个特定的动作。
参数：一个 “ChartActionId” 类型的动作 ID。
返回值：无。
exportData：
功能：导出当前图表的数据。
参数：可选的 “ExportDataOptions” 类型的对象表示导出选项。
返回值：一个 Promise，解析为导出的数据。
getAllPanesHeight：
功能：获取所有窗格高度的数组。
返回值：一个数字数组。
getAllShapes：
功能：获取图表上所有绘图的 ID 和名称数组。
返回值：一个 “EntityInfo” 类型的数组。
getAllStudies：
功能：获取图表上所有研究的 ID 和名称数组。
返回值：一个 “EntityInfo” 类型的数组。
getCheckableActionState：
功能：获取可检查动作的状态。
参数：一个 “ChartActionId” 类型的动作 ID。
返回值：如果动作不存在或不可检查则返回 null，动作被选中则返回 true，否则返回 false。
getLineToolsState：
功能：获取包含活动图表上绘图的线工具状态。需要特定的功能集（“saveload_separate_drawings_storage”）启用。
返回值：“LineToolsAndGroupsState” 类型的对象。
getPanes：
功能：获取一个与图表窗格交互的 API 对象数组。
返回值：一个 “IPaneApi” 类型的数组。
getPriceToBarRatio：
功能：获取图表的价格与柱线比例。
返回值：一个数字表示比例，如果未定义则为 null。
getSeries：
功能：获取主序列的 API 对象。
返回值：一个 “ISeriesApi” 类型的对象。
getShapeById：
功能：通过 ID 获取一个绘图。
参数：一个实体 ID。
返回值：一个与绘图交互的 API 对象。
getStudyById：
功能：通过 ID 获取一个研究。
参数：一个实体 ID。
返回值：一个与研究交互的 API 对象。
getTimeScale：
功能：获取与时间轴交互的 API 对象。
返回值：一个 “ITimeScaleApi” 类型的对象。
getTimezoneApi：
功能：获取与图表时区交互的 API 对象。
返回值：一个 “ITimezoneApi” 类型的对象。
getVisibleRange：
功能：获取当前可见的时间范围。
返回值：一个 “VisibleTimeRange” 类型的对象。
isMaximized：
功能：检查图表是否最大化。
返回值：如果最大化则返回 true，否则返回 false。
isPriceToBarRatioLocked：
功能：获取图表价格与柱线比例是否锁定的状态。
返回值：一个布尔值。
isSelectBarRequested：
功能：检查柱线选择模式是否激活。
返回值：如果激活则返回 true，否则返回 false。
loadChartTemplate：
功能：加载并应用一个图表模板。
参数：模板名称。
返回值：一个 Promise，无具体返回值。
marketStatus：
功能：获取一个只读的观察值，可用于读取 / 订阅图表的市场状态。
返回值：一个 “IWatchedValueReadonly” 类型的对象。
maximizeChart：
功能：将当前选中的图表最大化。
返回值：无。
onChartTypeChanged：
功能：获取一个订阅对象，用于监听图表类型变化的事件。
返回值：一个订阅对象，订阅函数接收新的图表类型作为参数。
onDataLoaded：
功能：获取一个订阅对象，用于监听图表加载新数据的事件。
返回值：一个订阅对象，订阅函数无参数。
onHoveredSourceChanged：
功能：获取一个订阅对象，用于监听十字光标悬停的研究或序列 ID 变化的事件。
返回值：一个订阅对象，订阅函数接收悬停的实体 ID 作为参数，如果没有悬停的研究或序列则为 null。
onIntervalChanged：
功能：获取一个订阅对象，用于监听图表分辨率（间隔）变化的事件。
返回值：一个订阅对象，订阅函数接收新的分辨率和时间范围参数作为参数。
onSymbolChanged：
功能：获取一个订阅对象，用于监听图表符号变化的事件。
返回值：一个订阅对象，订阅函数无参数。
onVisibleRangeChanged：
功能：获取一个订阅对象，用于监听图表可见范围变化的事件。
返回值：一个订阅对象，订阅函数接收新的可见时间范围作为参数。
priceFormatter：
功能：返回一个带有 “format” 函数的对象，可用于格式化价格。
返回值：一个 “INumberFormatter” 类型的对象。
refreshMarks：
功能：强制图表重新请求所有柱线标记和时间轴标记。
返回值：无。
reloadLineToolsFromServer：
功能：手动触发图表从服务器重新请求线工具。需要特定的功能集（“saveload_separate_drawings_storage”）启用。
返回值：无。
removeAllShapes：
功能：从图表中删除所有绘图。
返回值：无。
removeAllStudies：
功能：从图表中删除所有研究。
返回值：无。
removeEntity：
功能：从图表中删除一个实体（如绘图或研究）。
参数：实体 ID 和可选的撤销选项。
返回值：无。
requestSelectBar：
功能：切换图表到柱线选择模式。
返回值：一个 Promise，解析为用户选择的柱线的时间戳。如果柱线选择已请求或被取消，则拒绝。
resetData：
功能：强制图表重新请求数据，例如在网络连接问题时。
返回值：无。
resolution：
功能：获取当前分辨率（间隔）。
返回值：一个 “ResolutionString” 类型的值。
restoreChart：
功能：将当前选中的图表恢复到初始大小。
返回值：无。
selection：
功能：获取一个与选择交互的 API 对象。
返回值：一个 “ISelectionApi” 类型的对象。
sendBackward：
功能：将源在 Z 序中向下移动一层。
参数：一个只读的实体 ID 数组。
返回值：无。
sendToBack：
功能：将实体移动到 Z 序的底部。
参数：一个只读的实体 ID 数组。
返回值：无。
setAllPanesHeight：
功能：设置每个窗格的高度。
参数：一个数字数组表示高度。
返回值：无。
setChartType：
功能：更改图表类型。
参数：新的图表类型和可选的回调函数。
返回值：无，返回一个 Promise，解析为一个布尔值，表示图表类型是否已设置成功。
setPriceToBarRatio：
功能：设置图表的价格与柱线比例。
参数：新的比例和可选的撤销选项。
返回值：无。
setPriceToBarRatioLocked：
功能：锁定或解锁图表的价格与柱线比例。
参数：一个布尔值表示锁定状态和可选的撤销选项。
返回值：无。
setResolution：
功能：更改图表的分辨率（间隔）。
参数：新的分辨率和可选的设置选项或回调函数。
返回值：一个 Promise，解析为一个布尔值，表示分辨率是否已设置成功。
setScrollEnabled：
功能：启用或禁用图表的滚动。
参数：一个布尔值表示启用或禁用状态。
返回值：无。
setSymbol：
功能：更改图表的符号。
参数：新的符号和可选的设置选项或回调函数。
返回值：无。
setTimeFrame：
功能：设置图表的时间范围。
参数：一个 “RangeOptions” 类型的对象表示时间范围和分辨率。
返回值：无。
setVisibleRange：
功能：滚动和 / 或缩放图表以使其时间范围可见。
参数：一个要设置为可见的时间范围和可选的设置选项。
返回值：一个 Promise，当范围设置完成后 resolve。
setZoomEnabled：
功能：启用或禁用图表的缩放。
参数：一个布尔值表示启用或禁用状态。
返回值：无。
shapesGroupController：
功能：获取一个与绘图组交互的 API 对象。
返回值：一个 “IShapesGroupControllerApi” 类型的对象。
showPropertiesDialog：
功能：显示一个研究或绘图的属性对话框。
参数：一个实体 ID，表示研究或绘图的 ID。
返回值：无。
symbol：
功能：获取当前符号的名称。
返回值：一个字符串。
symbolExt：
功能：获取当前符号的扩展信息对象。
返回值：一个 “SymbolExt” 类型的对象。
zoomOut：
功能：缩小图表，与点击 “缩小” 按钮效果相同。
返回值：无。
三、总结
这个接口提供了丰富的方法来与图表进行各种交互操作，包括设置图表类型、分辨率、符号，创建和管理绘图、研究等实体，监听各种事件以及导出数据等功能。开发人员可以根据具体需求使用这些方法来实现对图表的定制和交互。需要注意的是，一些方法可能已弃用，并且一些方法需要特定的功能集启用。同时，方法的参数和返回值类型需要准确理解和使用，以确保正确地与图表进行交互。