@quantlife/qlchart 0.0.1

package/python/qlchart/chart.py

@@ -0,0 +1,333 @@
+"""QLChartHTML - Python HTML 生成器
+
+生成独立HTML文件，内嵌 lightweight-charts standalone + 数据JSON。
+支持蜡烛图、折线图、直方图、标记等，可设置主题和图表选项。
+"""
+
+import json
+import os
+
+from jinja2 import Environment, FileSystemLoader
+
+
+class QLChartHTML:
+    """生成独立HTML文件，内嵌 lightweight-charts standalone + 数据JSON"""
+
+    def __init__(self, title: str = "QLChart"):
+        self._title = title
+        self._theme = "dark"
+        self._width: str = "100%"
+        self._height: str = "600px"
+        self._series_list: list = []
+        self._markers: list = []
+        self._options: dict = {}
+        self._lwc_version = "5.2.0"
+        self._js_mode = "cdn"
+        self._local_js_path = None
+        self._drawing_enabled = False
+        self._drawing_pair_id = ""
+        self._drawing_product = ""
+
+    def add_candlestick(self, data: list) -> "QLChartHTML":
+        """添加蜡烛图数据
+
+        Args:
+            data: K线数据列表，每条包含 time(秒或毫秒时间戳), open, high, low, close
+        """
+        transformed = self._transform_ohlc(data)
+        self._series_list.append({"type": "candlestick", "data": transformed})
+        return self
+
+    def add_line(self, data: list, color: str = "#2962FF",
+                 name: str = "") -> "QLChartHTML":
+        """添加折线图
+
+        Args:
+            data: 数据列表，每条包含 time(秒或毫秒时间戳), value
+            color: 线条颜色
+            name: 序列名称
+        """
+        transformed = self._transform_line(data)
+        self._series_list.append({
+            "type": "line",
+            "data": transformed,
+            "color": color,
+            "name": name,
+        })
+        return self
+
+    def add_histogram(self, data: list, color: str = "#26a69a",
+                      name: str = "Volume") -> "QLChartHTML":
+        """添加直方图
+
+        Args:
+            data: 数据列表，每条包含 time(秒或毫秒时间戳), value, color(可选)
+            color: 默认颜色
+            name: 序列名称
+        """
+        transformed = self._transform_line(data)
+        self._series_list.append({
+            "type": "histogram",
+            "data": transformed,
+            "color": color,
+            "name": name,
+        })
+        return self
+
+    def add_area(self, data: list, top_color: str = "rgba(41, 98, 255, 0.4)",
+                 bottom_color: str = "rgba(41, 98, 255, 0.0)",
+                 line_color: str = "#2962FF",
+                 name: str = "") -> "QLChartHTML":
+        """添加面积图
+
+        Args:
+            data: 数据列表，每条包含 time(秒或毫秒时间戳), value
+            top_color: 面积顶部颜色
+            bottom_color: 面积底部颜色
+            line_color: 边线颜色
+            name: 序列名称
+        """
+        transformed = self._transform_line(data)
+        self._series_list.append({
+            "type": "area",
+            "data": transformed,
+            "topColor": top_color,
+            "bottomColor": bottom_color,
+            "lineColor": line_color,
+            "name": name,
+        })
+        return self
+
+    def add_markers(self, markers: list) -> "QLChartHTML":
+        """添加标记（买卖信号等）
+
+        Args:
+            markers: 标记列表，每条包含 time, position(aboveBelow), shape, text, color
+        """
+        self._markers = markers
+        return self
+
+    def set_theme(self, theme: str = "dark") -> "QLChartHTML":
+        """设置主题
+
+        Args:
+            theme: "dark" 或 "light"
+        """
+        self._theme = theme
+        return self
+
+    def set_size(self, width: str = "100%", height: str = "600px") -> "QLChartHTML":
+        """设置图表尺寸
+
+        Args:
+            width: 宽度，如 "100%", "800px"
+            height: 高度，如 "600px", "100%"
+        """
+        self._width = width
+        self._height = height
+        return self
+
+    def set_options(self, options: dict) -> "QLChartHTML":
+        """设置图表选项
+
+        Args:
+            options: lightweight-charts ChartOptions 的子集
+        """
+        self._options = options
+        return self
+
+    def add_ma(self, data: list, period: int = 20, color: str = "#2962FF",
+                name: str = "MA") -> "QLChartHTML":
+        """快速添加移动平均线
+
+        Args:
+            data: K线数据列表（与add_candlestick相同格式）
+            period: MA周期
+            color: 线条颜色
+            name: 线条名称
+        """
+        ma_data = self._calculate_ma(data, period)
+        return self.add_line(ma_data, color=color, name=f"{name}{period}")
+
+    @staticmethod
+    def _calculate_ma(data: list, period: int) -> list:
+        """计算移动平均线"""
+        result = []
+        closes = [item.get("close", 0) for item in data]
+        for i, item in enumerate(data):
+            if i < period - 1:
+                continue
+            ma_value = sum(closes[i - period + 1:i + 1]) / period
+            result.append({
+                "time": item.get("time", 0),
+                "value": round(ma_value, 6),
+            })
+        return result
+
+    def add_boll(self, data: list, period: int = 20, std_dev: float = 2.0,
+                 color: str = "#FF6D00", name: str = "BOLL") -> "QLChartHTML":
+        """快速添加布林带（上轨+中轨+下轨）
+
+        Args:
+            data: K线数据列表
+            period: 周期
+            std_dev: 标准差倍数
+            color: 线条颜色
+            name: 名称前缀
+        """
+        upper, middle, lower = self._calculate_boll(data, period, std_dev)
+        self.add_line(upper, color=color, name=f"{name}Upper")
+        self.add_line(middle, color="#FF6D00", name=f"{name}Mid")
+        self.add_line(lower, color=color, name=f"{name}Lower")
+        return self
+
+    @staticmethod
+    def _calculate_boll(data: list, period: int, std_dev: float):
+        """计算布林带"""
+        closes = [item.get("close", 0) for item in data]
+        upper, middle, lower = [], [], []
+        for i in range(period - 1, len(data)):
+            window = closes[i - period + 1:i + 1]
+            ma = sum(window) / period
+            std = (sum((x - ma) ** 2 for x in window) / period) ** 0.5
+            time_val = data[i].get("time", 0)
+            middle.append({"time": time_val, "value": round(ma, 6)})
+            upper.append({"time": time_val, "value": round(ma + std_dev * std, 6)})
+            lower.append({"time": time_val, "value": round(ma - std_dev * std, 6)})
+        return upper, middle, lower
+
+    def add_signals(self, signals: list) -> "QLChartHTML":
+        """快速添加买卖信号标记
+
+        Args:
+            signals: 信号列表，每条包含 time, type("buy"/"sell"), text(可选)
+        """
+        markers = []
+        for signal in signals:
+            marker = {
+                "time": signal.get("time", 0),
+                "position": "belowBar" if signal.get("type") == "buy" else "aboveBar",
+                "color": "#26a69a" if signal.get("type") == "buy" else "#ef5350",
+                "shape": "arrowUp" if signal.get("type") == "buy" else "arrowDown",
+                "text": signal.get("text", "B" if signal.get("type") == "buy" else "S"),
+            }
+            markers.append(marker)
+        return self.add_markers(markers)
+
+    def add_volume_colored(self, data: list, name: str = "Volume") -> "QLChartHTML":
+        """添加带涨跌色的成交量直方图
+
+        Args:
+            data: K线数据列表，需要包含 open/close 字段来判断涨跌
+            name: 序列名称
+        """
+        volume_data = []
+        for item in data:
+            color = "#26a69a" if item.get("close", 0) >= item.get("open", 0) else "#ef5350"
+            volume_data.append({
+                "time": item.get("time", 0),
+                "value": item.get("volume", 0),
+                "color": color,
+            })
+        self._series_list.append({
+            "type": "histogram",
+            "data": volume_data,
+            "name": name,
+        })
+        return self
+
+    def set_js_mode(self, mode: str, local_path: str = None) -> "QLChartHTML":
+        """设置JS加载模式
+
+        Args:
+            mode: "cdn" | "inline" | "local"
+            local_path: 本地JS文件路径（mode="local"时使用）
+        """
+        self._js_mode = mode
+        self._local_js_path = local_path
+        return self
+
+    def enable_drawing(self, pair_id: str, product: str = "BTC") -> "QLChartHTML":
+        """启用绘图工具栏和LocalStorage持久化
+
+        Args:
+            pair_id: 交易对ID（用于LocalStorage Key生成）
+            product: 产品类型
+        """
+        self._drawing_enabled = True
+        self._drawing_pair_id = pair_id
+        self._drawing_product = product
+        return self
+
+    def to_html(self) -> str:
+        """生成完整HTML字符串"""
+        template_dir = os.path.join(os.path.dirname(__file__), "templates")
+        env = Environment(loader=FileSystemLoader(template_dir))
+        template = env.get_template("chart_template.html")
+
+        # inline模式：读取standalone.js文件内容
+        inline_js = ""
+        js_mode = self._js_mode
+        if js_mode == "inline":
+            standalone_path = os.path.join(os.path.dirname(__file__), "standalone.js")
+            if os.path.exists(standalone_path):
+                with open(standalone_path, "r", encoding="utf-8") as f:
+                    inline_js = f.read()
+            else:
+                # fallback到CDN模式
+                js_mode = "cdn"
+
+        return template.render(
+            title=self._title,
+            theme=self._theme,
+            width=self._width,
+            height=self._height,
+            series=json.dumps(self._series_list, default=str),
+            markers=json.dumps(self._markers, default=str),
+            options=json.dumps(self._options, default=str),
+            lwc_version=self._lwc_version,
+            js_mode=js_mode,
+            inline_js=inline_js,
+            local_js_path=self._local_js_path or "",
+            drawing_enabled=self._drawing_enabled,
+            drawing_pair_id=self._drawing_pair_id,
+            drawing_product=self._drawing_product,
+        )
+
+    def save(self, filepath: str) -> None:
+        """保存为HTML文件
+
+        Args:
+            filepath: 保存路径
+        """
+        html = self.to_html()
+        dir_path = os.path.dirname(filepath)
+        if dir_path and not os.path.exists(dir_path):
+            os.makedirs(dir_path, exist_ok=True)
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(html)
+
+    @staticmethod
+    def _transform_ohlc(data: list) -> list:
+        """转换OHLC数据：毫秒时间戳→秒"""
+        result = []
+        for item in data:
+            d = dict(item)
+            t = d.get("time", 0)
+            # 毫秒时间戳→秒
+            if isinstance(t, (int, float)) and t > 1e10:
+                d["time"] = int(t / 1000)
+            result.append(d)
+        return result
+
+    @staticmethod
+    def _transform_line(data: list) -> list:
+        """转换Line/Histogram数据：毫秒时间戳→秒"""
+        result = []
+        for item in data:
+            d = dict(item)
+            t = d.get("time", 0)
+            if isinstance(t, (int, float)) and t > 1e10:
+                d["time"] = int(t / 1000)
+            result.append(d)
+        return result

package/python/qlchart/templates/chart_template.html

@@ -0,0 +1,304 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ title }}</title>
+    {% if js_mode == 'cdn' %}
+    <script src="https://unpkg.com/lightweight-charts@{{ lwc_version }}/dist/lightweight-charts.standalone.production.js"></script>
+    {% elif js_mode == 'inline' %}
+    <script>{{ inline_js | safe }}</script>
+    {% elif js_mode == 'local' %}
+    <script src="{{ local_js_path }}"></script>
+    {% endif %}
+    {% if drawing_enabled %}
+    <script src="https://unpkg.com/lightweight-charts-drawing/dist/lwc-drawing.standalone.production.js"></script>
+    {% endif %}
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: {% if theme == 'dark' %}#1e1e1e{% else %}#ffffff{% endif %};
+            color: {% if theme == 'dark' %}#d1d4dc{% else %}#131722{% endif %};
+        }
+        .chart-header {
+            padding: 12px 16px;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            border-bottom: 1px solid {% if theme == 'dark' %}#2a2e39{% else %}#e0e3eb{% endif %};
+        }
+        .chart-header h2 {
+            font-size: 16px;
+            font-weight: 600;
+        }
+        .chart-container {
+            width: {{ width }};
+            height: {{ height }};
+            position: relative;
+        }
+        {% if drawing_enabled %}
+        #drawing-toolbar {
+            position: absolute;
+            top: 50px;
+            left: 10px;
+            z-index: 100;
+            display: flex;
+            flex-direction: column;
+            gap: 4px;
+            background: {% if theme == 'dark' %}#2a2e39{% else %}#f0f3fa{% endif %};
+            border-radius: 6px;
+            padding: 4px;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+        }
+        .dw-btn {
+            width: 32px;
+            height: 32px;
+            border: none;
+            border-radius: 4px;
+            background: transparent;
+            cursor: pointer;
+            font-size: 16px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            transition: background 0.15s;
+        }
+        .dw-btn:hover {
+            background: {% if theme == 'dark' %}#3a3f4b{% else %}#e0e3eb{% endif %};
+        }
+        .dw-btn.active {
+            background: #2962FF;
+            color: #fff;
+        }
+        {% endif %}
+    </style>
+</head>
+<body>
+    <div class="chart-header">
+        <h2>{{ title }}</h2>
+    </div>
+    <div id="qlchart-container" class="chart-container"></div>
+
+    {% if drawing_enabled %}
+    <div id="drawing-toolbar" style="display:none;">
+        <button data-tool="cursor" class="dw-btn active" title="光标">🖱️</button>
+        <button data-tool="trend-line" class="dw-btn" title="趋势线">📈</button>
+        <button data-tool="horizontal-line" class="dw-btn" title="水平线">➖</button>
+        <button data-tool="rectangle" class="dw-btn" title="矩形">⬜</button>
+        <button data-tool="fib-retracement" class="dw-btn" title="斐波那契回撤">📐</button>
+    </div>
+    {% endif %}
+
+    <script>
+    (function() {
+        const theme = {{ theme | tojson }};
+        const seriesData = {{ series | safe }};
+        const markersData = {{ markers | safe }};
+        const customOptions = {{ options | safe }};
+
+        // 主题配置
+        const darkTheme = {
+            layout: {
+                background: { color: '#1e1e1e' },
+                textColor: '#d1d4dc',
+            },
+            grid: {
+                vertLines: { color: '#2a2e39' },
+                horzLines: { color: '#2a2e39' },
+            },
+            crosshair: {
+                vertLine: { color: '#758696', width: 1, style: 3 },
+                horzLine: { color: '#758696', width: 1, style: 3 },
+            },
+            timeScale: {
+                borderColor: '#2a2e39',
+                timeVisible: true,
+                secondsVisible: false,
+            },
+            rightPriceScale: {
+                borderColor: '#2a2e39',
+            },
+        };
+
+        const lightTheme = {
+            layout: {
+                background: { color: '#ffffff' },
+                textColor: '#131722',
+            },
+            grid: {
+                vertLines: { color: '#e0e3eb' },
+                horzLines: { color: '#e0e3eb' },
+            },
+            crosshair: {
+                vertLine: { color: '#758696', width: 1, style: 3 },
+                horzLine: { color: '#758696', width: 1, style: 3 },
+            },
+            timeScale: {
+                borderColor: '#e0e3eb',
+                timeVisible: true,
+                secondsVisible: false,
+            },
+            rightPriceScale: {
+                borderColor: '#e0e3eb',
+            },
+        };
+
+        const themeOptions = theme === 'dark' ? darkTheme : lightTheme;
+
+        // 合并自定义选项
+        const chartOptions = { ...themeOptions, ...customOptions };
+
+        // 创建图表
+        const container = document.getElementById('qlchart-container');
+        const chart = LightweightCharts.createChart(container, chartOptions);
+
+        // 自适应尺寸
+        function resizeChart() {
+            const rect = container.getBoundingClientRect();
+            chart.applyOptions({ width: rect.width, height: rect.height });
+        }
+        window.addEventListener('resize', resizeChart);
+        resizeChart();
+
+        // Series类型映射（lightweight-charts v5.2 standalone）
+        const seriesCreators = {
+            candlestick: (opts) => chart.addCandlestickSeries(opts),
+            line: (opts) => chart.addLineSeries(opts),
+            histogram: (opts) => chart.addHistogramSeries(opts),
+            area: (opts) => chart.addAreaSeries(opts),
+            bar: (opts) => chart.addBarSeries(opts),
+            baseline: (opts) => chart.addBaselineSeries(opts),
+        };
+
+        let mainSeries = null;
+
+        // 创建所有序列
+        seriesData.forEach(function(item) {
+            const opts = {};
+            if (item.color) opts.color = item.color;
+            if (item.name) opts.title = item.name;
+            if (item.topColor) opts.topColor = item.topColor;
+            if (item.bottomColor) opts.bottomColor = item.bottomColor;
+            if (item.lineColor) opts.lineColor = item.lineColor;
+
+            const seriesType = item.type || 'candlestick';
+            const creator = seriesCreators[seriesType];
+
+            if (creator) {
+                const series = creator(opts);
+                series.setData(item.data || []);
+
+                // 第一个序列作为主序列
+                if (!mainSeries) {
+                    mainSeries = series;
+
+                    // 添加标记
+                    if (seriesType === 'candlestick' && markersData && markersData.length > 0) {
+                        series.setMarkers(markersData);
+                    }
+                }
+            }
+        });
+
+        // 自动缩放到数据范围
+        chart.timeScale().fitContent();
+
+        // ══════════════════════════════════════════════
+        // 绘图功能（仅 enable_drawing 启用时）
+        // ══════════════════════════════════════════════
+        {% if drawing_enabled %}
+        (function() {
+            const STORAGE_PREFIX = 'qlchart_dw_';
+            const STORAGE_VERSION = 1;
+            const pairId = '{{ drawing_pair_id }}';
+            const product = '{{ drawing_product }}';
+
+            // 生成存储Key（仅使用 pairId + product）
+            function simpleHash(str) {
+                let hash = 0;
+                for (let i = 0; i < str.length; i++) {
+                    const char = str.charCodeAt(i);
+                    hash = ((hash << 5) - hash) + char;
+                    hash |= 0;
+                }
+                return Math.abs(hash).toString(36);
+            }
+            const STORAGE_KEY = STORAGE_PREFIX + simpleHash(pairId + '_' + product);
+
+            // 显示工具栏
+            const toolbar = document.getElementById('drawing-toolbar');
+            if (toolbar) toolbar.style.display = 'flex';
+
+            // DrawingManager 初始化
+            let drawingManager = null;
+            if (typeof DrawingManager !== 'undefined') {
+                drawingManager = new DrawingManager();
+                drawingManager.attach(chart, mainSeries, container);
+            } else if (typeof window.lwc !== 'undefined' && window.lwc.DrawingManager) {
+                drawingManager = new window.lwc.DrawingManager();
+                drawingManager.attach(chart, mainSeries, container);
+            }
+
+            if (!drawingManager) {
+                console.warn('[QLChart] DrawingManager not available. Drawing toolbar disabled.');
+                return;
+            }
+
+            // 加载已保存的绘图
+            function loadDrawings() {
+                const json = localStorage.getItem(STORAGE_KEY);
+                if (!json) return;
+                try {
+                    const envelope = JSON.parse(json);
+                    if (envelope.drawings) {
+                        drawingManager.importDrawings(envelope.drawings);
+                    }
+                } catch (e) {
+                    console.error('[QLChart] Failed to load drawings:', e);
+                }
+            }
+
+            // 保存绘图（debounce）
+            let saveTimer = null;
+            function saveDrawings() {
+                if (saveTimer) clearTimeout(saveTimer);
+                saveTimer = setTimeout(function() {
+                    const drawings = drawingManager.exportDrawings();
+                    const envelope = {
+                        version: STORAGE_VERSION,
+                        drawings: drawings,
+                        updatedAt: Date.now(),
+                    };
+                    localStorage.setItem(STORAGE_KEY, JSON.stringify(envelope));
+                }, 300);
+            }
+
+            // 工具栏事件
+            document.querySelectorAll('.dw-btn').forEach(function(btn) {
+                btn.addEventListener('click', function() {
+                    document.querySelectorAll('.dw-btn').forEach(function(b) {
+                        b.classList.remove('active');
+                    });
+                    btn.classList.add('active');
+                    var tool = btn.dataset.tool;
+                    drawingManager.setActiveTool(tool === 'cursor' ? null : tool);
+                });
+            });
+
+            // 绘图变更自动保存
+            if (drawingManager.on) {
+                drawingManager.on('drawingCreated', saveDrawings);
+                drawingManager.on('drawingRemoved', saveDrawings);
+                drawingManager.on('drawingModified', saveDrawings);
+            }
+
+            // 初始加载
+            loadDrawings();
+        })();
+        {% endif %}
+
+    })();
+    </script>
+</body>
+</html>

package/python/requirements.txt

@@ -0,0 +1 @@
+Jinja2>=3.0

package/python/setup.py

@@ -0,0 +1,18 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="qlchart",
+    version="0.1.0",
+    description="QLChart Python HTML Generator - 生成基于 lightweight-charts 的独立HTML图表",
+    author="QuantLife",
+    author_email="dev@quantlife.ai",
+    packages=find_packages(),
+    include_package_data=True,
+    package_data={
+        "qlchart": ["templates/*.html"],
+    },
+    install_requires=[
+        "Jinja2>=3.0",
+    ],
+    python_requires=">=3.9",
+)

package/python/tests/__init__.py

@@ -0,0 +1 @@
+# empty file