Lightweight Charts 技能

适用场景

当你在使用 lightweight-charts 进行以下任何工作时，激活此技能可获得精准、版本正确的指导：

场景	说明
📈 创建图表与系列	Line / Area / Bar / Candlestick / Histogram 等各类图表
⏱ 时间与价格轴配置	时间格式、时区显示、双价格轴、自动缩放
🔄 实时 / 历史数据	WebSocket 推流、增量更新、历史数据加载与拼接
🏷 标记与工具提示	买卖标记、十字光标、自定义 Tooltip / Legend
🎨 逐条 / 逐点着色	K 线颜色、成交量颜色、自定义数据点样式
🧩 自定义插件与原语	Pane Primitive、Series Primitive、Custom Series、水印
📐 坐标转换与交互	像素 ↔ 价格 / 时间 / 逻辑索引的双向转换
🖥 多窗格布局	主图 + 副图（如价格 + 成交量）、窗格高度控制
🌐 框架集成	React / Vue / Web Components / Next.js SSR / 纯 HTML
📱 移动端包装器	iOS / Android 原生封装
🔀 非金融场景	期权链、传感器数据等自定义水平轴
🔄 v4 → v5 迁移	旧 API 到新 API 的逐项替换指导

核心能力

1. 精准的 v5 API 指导

• 所有代码示例严格遵循 v5 API 规范（chart.addSeries(SeriesType, options) 等）
• 自动识别并纠正 v4 及更早版本的过时写法（如 addLineSeries、series.setMarkers）
• 提供完整的 v4 → v5 替换对照表，避免复制粘贴旧代码导致的报错

2. 八大层级心智模型

技能将 lightweight-charts 的架构拆解为 8 个依赖层级，帮助你快速定位问题所在：

Chart → Series → Scales → Data Model → Interaction → Layout → Extension → Wrappers

大多数 Bug 源于层级混淆，技能会明确指出你的问题属于哪一层。

3. 常见踩坑预警（Foot-guns）

内置 20+ 条高频踩坑断言，覆盖：

• ⚠️ UTCTimestamp 是秒不是毫秒
• ⚠️ 不存在 timeScale.timezone 选项，时区需用 Intl.DateTimeFormat 实现
• ⚠️ 数据必须严格升序且唯一，重复时间戳会被静默替换
• ⚠️ setData 会重置可视范围，实时推送应使用 update()
• ⚠️ v5 标记是独立原语（createSeriesMarkers），不是 series.setMarkers
• ⚠️ 渲染器接口是 IPrimitivePaneRenderer，不是 IPanePrimitivePaneRenderer
• ⚠️ Next.js 必须客户端渲染，不能在服务端组件中导入图表
• ⚠️ 空白点只传 time，不要用 value: null 制造间隙

4. 即拿即用的代码模板

提供 12+ 个经过验证的标准代码片段：

模板	用途
实时数据更新	WebSocket 逐条推送 K 线
双价格轴	左右轴同时显示
成交量副图	主图 + 独立窗格
逐条着色	K 线 / 成交量按涨跌变色
系列标记	买卖箭头标注
时区显示	纽约 / 东京等时区格式化
文字水印	图表中央叠加水印
空白间隙	数据缺失时的视觉留白
多图表同步	两个独立图表联动滚动
坐标转换	点击位置 → 价格 / 时间
Next.js 组件	'use client' + dynamic 完整方案
插件脚手架	Primitive 最小实现

5. 智能版本与环境检测

• 自动区分 npm 消费端应用 与 上游源码仓库，选择正确的类型定义查找路径
• 识别用户是否误用了 Python 第三方包装器（lightweight_charts，下划线），避免给出错误的 JS 建议
• 根据用户的框架（React / Vue / 纯 HTML / SSR）匹配对应的集成方案

6. 问题诊断路由

内置 问题 → API → 避坑 的快速分诊表，例如：

用户问："我的图表每次新数据到来都跳到最右边" → 诊断：数据层 + 时间轴层 → 大概率是 setData 替代了 update → 给出修复方案

技术特色

• 🔍 本地类型优先：所有 API 名称以项目内 typings.d.ts 为准，不凭空编造
• 📦 Tree-shaking 感知：v5 系列类型需显式导入，技能会提醒正确的 import 语句
• 🎯 最小代码原则：每个代码块只演示一个功能，不混合多个 API
• 🛡 防幻觉机制：如果无法验证某个 API 是否存在，会明确告知而非猜测

适用人群

角色	价值
前端开发者	快速上手 lightweight-charts v5，避免版本混淆
量化 / 金融工程师	构建实时行情看板、K 线图、技术指标面板
全栈开发者	Next.js / Nuxt 等 SSR 框架中正确集成图表
插件开发者	自定义绘制工具、指标叠加、非金融图表扩展
迁移维护者	从 v3 / v4 平滑升级到 v5

快速开始示例

import { createChart, CandlestickSeries } from 'lightweight-charts';

const chart = createChart(document.getElementById('chart')!, { autoSize: true });
const candles = chart.addSeries(CandlestickSeries, {});

candles.setData([
  { time: 1700000000, open: 1, high: 2, low: 0.5, close: 1.5 },
  { time: 1700003600, open: 1.5, high: 1.8, low: 1.1, close: 1.2 },
]);

💡 注意：time 是 Unix 秒级时间戳，不是毫秒。使用 Math.floor(Date.now() / 1000)。

本技能基于 lightweight-charts v5 API 规范编写，覆盖官方文档、类型定义及社区高频问题。