配置

导出

名称	类型	说明
`WidgetIccandle`	组件	图表浮层 + 结果 iframe
`WidgetIccandleProps`	类型	`WidgetIccandle` 的 props
`WidgetIccandleChartRefs`	类型	高亮 K 线 / 生成 K 线指标的 refs
`WidgetLanguage`	类型	支持的语言代码
`withPlayChart`	函数	包装 TradingView datafeed 以注入回放 K 线
`getCustomIndicators`	函数	返回 iC Candle 自定义指标（生成 K 线）
`getGeneratedCandlesMaskColor`	函数	生成 K 线的主题感知遮罩颜色

WidgetIccandle props

Prop	类型	必需	说明
`chartWidget`	`IChartingLibraryWidget \| null`	是	实时 TradingView widget（就绪前为 `null`）。
`children`	`ReactNode \| ((chartRefs) => ReactNode)`	是	图表 UI，或接收 `WidgetIccandleChartRefs` 的 render prop。
`theme`	`"light" \| "dark" \| "system"`	否	扫描器与 iframe 主题。`"system"` 跟随 `prefers-color-scheme`。
`language`	`WidgetLanguage`	否	UI 与 iframe 语言。可选：`en`、`zh`、`vi`、`th`、`ko`、`ja`、`mn`、`ru`。默认 `en`。
`onCloseResult`	`() => void`	否	嵌入端发送 `close-result` 时调用。
`iframeLoaded`	`boolean`	否	为 `false` 时，在结果 iframe 就绪前禁用扫描 / 追踪操作。默认扫描器行为为可用。

IChartingLibraryWidget 必须从你的 Charting Library 类型定义导入 — 本包不重新导出 TradingView 类型。

WidgetIccandleChartRefs

字段	说明
`highlightBarsRef`	用于高亮 / 选择叠加的 K 线
`generatedCandlesBackgroundStudyIdRef`	生成 K 线背景指标的 study id
`generatedCandlesStudyIdRef`	生成 K 线指标的 study id

withPlayChart(datafeed)

图表回放 / 预测所必需。包装 TradingView datafeed 的 subscribeBars，使组件可以：

注入回放 K 线 — 当嵌入端发送 play-chart 或 replay 时，写入实时 tick 流。
阻止实时 tick — 回放期间屏蔽实盘更新，避免覆盖预测 K 线。

签名

withPlayChart(datafeed: IBasicDataFeed): IBasicDataFeed

参数	类型	说明
`datafeed`	`IBasicDataFeed`	已就绪的 datafeed 实例（须提供 `onReady`）。

用法

import { withPlayChart } from "@iccandle/reactjs-widget";

datafeed: withPlayChart(myDatafeed),

说明

返回值仍是普通 datafeed；仅包装了 subscribeBars。
需与 getCustomIndicators 一起使用 — 缺一不可，否则回放 / 预测叠加无法生效。

getCustomIndicators(theme?)

注册 iC Candle 自定义指标，用于在主系列上绘制生成 / 预测 K 线。返回 TradingView CustomIndicator[] 的 Promise，供 custom_indicators_getter 使用。

签名

getCustomIndicators(theme?: "light" | "dark"): Promise<readonly CustomIndicator[]>

参数	类型	默认	说明
`theme`	`"light" \| "dark"`	`"light"`	面板遮罩颜色，用于在预测时间点盖住底层 K 线。须与图表主题一致。

返回的指标

指标名称	作用
`Generated Candles Background - By iC Candle`	隐藏的遮罩层，在预测时间戳处覆盖真实 K 线。
`Generated Candles - By iC Candle`	可见 OHLC 叠加（上涨 `#00dfb9` / 下跌 `#ffb84d`），绘制预测 K 线。

当嵌入端发送回放 / 预测数据时，WidgetIccandle 通过 chartRefs（generatedCandlesBackgroundStudyIdRef、generatedCandlesStudyIdRef）创建并驱动这些指标。

用法

import { getCustomIndicators } from "@iccandle/reactjs-widget";

const options: ChartingLibraryWidgetOptions = {
  // ...
  datafeed: withPlayChart(yourDatafeed),
  custom_indicators_getter: () => getCustomIndicators("light"),
};

保持 getCustomIndicators(theme) 与图表主题一致（并尽量与 WidgetIccandle 的 theme prop 一致）。若需在其他处使用同一遮罩色，可用 getGeneratedCandlesMaskColor(theme)（浅色 #ffffff / 深色 #131722）。

与 withPlayChart 配合

辅助函数	作用
`withPlayChart`	允许组件向 datafeed 推送 K 线，并在回放期间屏蔽实时 tick。
`getCustomIndicators`	以自定义指标绘制预测 K 线视觉效果（遮罩 + 彩色 OHLC）。

结果 iframe 的回放 / 预测功能需要两者同时配置。

认证与存储

键	用途
`iccandle_token`	扫描缓存、形态追踪及相关 API 的 Bearer 令牌。由嵌入端通过 `sign-in-success` 写入。
`search-filter`	扫描器高级选项（symbols、top_k、period、probability）。
`tv:selected-news-events`	用作时间轴标记的新闻事件 JSON 数组。
`tv:clicked-news-event`	最近点击的日历事件，用于标记高亮。
`tv:latest-symbol`	最近的图表品种（演示应用 / 回退使用）。

postMessage 桥接

仅接受来自结果源（https://embed-iccandle-app.iccandle.ai）的消息。

方向	Type / action	效果
嵌入 → 父页面	`play-chart`	在图表上注入 / 清除回放 K 线
嵌入 → 父页面	`loading`	切换扫描器加载 UI
嵌入 → 父页面	`sign-in-success`	从 `payload.id_token` 持久化 `iccandle_token`
嵌入 → 父页面	`close-result`	清除回放状态；调用 `onCloseResult`
嵌入 → 父页面	`pattern_selected` / `custom_pattern_selected`	为对比形态绘制日期范围
嵌入 → 父页面	`clear_pattern_selected` / `clear_custom_pattern_selected`	移除形态日期范围
嵌入 → 父页面	`eventClicked`	居中图表、绘制事件线、显示标记
嵌入 → 父页面	`replay`	开始 / 停止事件回放 K 线
嵌入 → 父页面	`back` / `back-to-similar-events`	清除事件线 / 回放
嵌入 → 父页面	`nav-click`	在 `/news` 隐藏扫描器；否则恢复
父页面 → 嵌入	`parent-origin`	Stripe 返回用的宿主 origin
父页面 → 嵌入	`payment-success`	结账后刷新订阅状态

可选：时间轴标记（新闻/事件）

若 datafeed 实现了 getTimescaleMarks，可将存储的事件显示为标记：

getTimescaleMarks: async (
  symbolInfo,
  from,
  to,
  onResult,
) => {
  const marks = [];
  try {
    const allNewsEvents = JSON.parse(
      localStorage.getItem("tv:selected-news-events") || "[]",
    );

    allNewsEvents?.forEach(({ id, timestamp, event_name, currency }) => {
      if (!id || !Number.isFinite(timestamp) || timestamp <= 0) return;
      if (marks.some((m) => String(m.id) === String(id))) return;

      marks.push({
        id,
        time: timestamp / 1000,
        color: "green",
        label: event_name.slice(0, 1) || "N",
        tooltip: [event_name],
        ...(currency ? { imageUrl: `/images/symbols/${currency}.svg` } : {}),
        showLabelWhenImageLoaded: true,
      });
    });
  } catch {
    /* ignore */
  }
  onResult(marks);
};

请按你的应用与 TradingView 类型调整路径与类型。

主题

扫描器 UI 在 .iccandle-selector-widget 上使用 CSS 变量：

--iccandle-primary
--iccandle-primary-gradient-end
--iccandle-background
--iccandle-border
--iccandle-text
--iccandle-secondary
--iccandle-font

浅色与深色默认值在打包样式表中。theme prop 会切换 .iccandle-dark 类并转发到 iframe。

行为摘要

订阅图表就绪、周期、品种变更与绘图事件。
管理 date_range 多点绘图，供用户调整 K 线窗口（默认：25 根）。
将 K 线提交到 https://scan-service.iccandle.ai/cacheCandle，再用查询参数（ws、tk、et、symbol、tf、cid、筛选、主题）导航结果 iframe。
在 https://embed-iccandle-app.iccandle.ai 托管结果 iframe，并通过 postMessage 同步。

许可

MIT。TradingView Charting Library 受 TradingView 自有许可证约束。

导出​

WidgetIccandle props​

WidgetIccandleChartRefs​

withPlayChart(datafeed)​

签名​

用法​

说明​

getCustomIndicators(theme?)​

签名​

返回的指标​

用法​

与 withPlayChart 配合​

认证与存储​

postMessage 桥接​

可选：时间轴标记（新闻/事件）​

主题​

行为摘要​

许可​

导出