Add Comments

ReportEngine/renderers/chart_to_svg.py

@@ -797,6 +797,7 @@ class ChartToSVGConverter:
             colors = self._get_colors(datasets)
 
             def _safe_radius(raw) -> float:
+                """将输入半径安全转为浮点并设置最小阈值，避免气泡完全消失"""
                 try:
                     val = float(raw)
                     return max(val, 0.5)

ReportEngine/renderers/html_renderer.py

@@ -1764,6 +1764,7 @@ class HTMLRenderer:
     ) -> str:
         """为词云提供表格兜底，避免WordCloud渲染失败后页面空白"""
         def _collect_items(raw: Any) -> list[dict]:
+            """将多种词云输入格式（数组/对象/元组/纯文本）规整为统一的词条列表"""
             collected: list[dict] = []
             if isinstance(raw, list):
                 for item in raw:
@@ -1812,6 +1813,7 @@ class HTMLRenderer:
             return ""
 
         def _format_weight(value: Any) -> str:
+            """统一格式化权重，支持百分比/数值与字符串回退"""
             if isinstance(value, (int, float)) and not isinstance(value, bool):
                 if 0 <= value <= 1.5:
                     return f"{value * 100:.1f}%"

ReportEngine/renderers/pdf_renderer.py

@@ -667,6 +667,7 @@ class PDFRenderer:
                 fallback_pattern = rf'<div class="chart-fallback"([^>]*data-widget-id="{re.escape(widget_id)}"[^>]*)>'
 
                 def _hide_fallback(m: re.Match) -> str:
+                    """为匹配到的图表fallback添加隐藏类，防止PDF中重复渲染"""
                     tag = m.group(0)
                     if 'svg-hidden' in tag:
                         return tag
@@ -712,6 +713,7 @@ class PDFRenderer:
             fallback_pattern = rf'<div class="chart-fallback"([^>]*data-widget-id="{re.escape(widget_id)}"[^>]*)>'
 
             def _hide_fallback(m: re.Match) -> str:
+                """匹配词云表格兜底并打上隐藏标记，避免SVG/图片重复显示"""
                 tag = m.group(0)
                 if 'svg-hidden' in tag:
                     return tag