ChartWidget 图表组件¶

ChartWidget 专门用于在邮件中展示各种图表和数据可视化内容。它不仅支持显示图片格式的图表，还提供了丰富的配置选项来增强图表的展示效果。

🎯 组件预览¶

Chart Component Preview

Generated: July 12, 2025 00:02:23

1. Chart Component Display

2024 Annual Sales Performance

Quarterly sales comparison showing steady growth trend

✨ 核心特性¶

📊 多种图表: 支持线图、柱状图、饼图等各种图表类型
🖼️ 图片展示: 支持网络图片、本地文件和Base64编码图片
📝 详细标注: 支持标题、描述和数据摘要等详细信息
📱 响应式: 自动适配不同设备的显示效果
📧 邮件兼容: 使用邮件客户端兼容的HTML和CSS实现 /

🚀 快速开始¶

基础用法¶

Python

from email_widget import Email
from email_widget.widgets import ChartWidget

# 创建基本图表
email = Email("数据报告")

chart = ChartWidget()
chart.set_image_url("https://example.com/sales_chart.png")
chart.set_title("月度销售趋势")
chart.set_description("显示最近6个月的销售数据变化")

email.add_widget(chart)

进阶用法¶

Python

# 带数据摘要的详细图表
performance_chart = ChartWidget()
performance_chart.set_image_url("performance_chart.png")
performance_chart.set_title("系统性能监控")
performance_chart.set_description("展示系统关键性能指标的实时状态")
performance_chart.set_data_summary("平均响应时间: 245ms | 峰值QPS: 12,500 | 错误率: 0.02%")
performance_chart.set_alt_text("系统性能监控图表")
performance_chart.set_max_width("800px")

email.add_widget(performance_chart)

📚 完整API文档: ChartWidget API

📊 图表类型示例¶

趋势线图表¶

Python

trend_chart = ChartWidget()
trend_chart.set_image_url("trend_line.png")
trend_chart.set_title("用户增长趋势")
trend_chart.set_description("显示过去12个月的用户注册和活跃用户数量变化")
trend_chart.set_data_summary("新增用户: +15% | 活跃用户: +8% | 留存率: 76%")

柱状图表¶

Python

bar_chart = ChartWidget()
bar_chart.set_image_url("sales_by_region.png")
bar_chart.set_title("各地区销售对比")
bar_chart.set_description("展示不同地区的销售业绩和市场占比")
bar_chart.set_data_summary("华东: 35% | 华南: 28% | 华北: 22% | 其他: 15%")

饼图¶

Python

pie_chart = ChartWidget()
pie_chart.set_image_url("market_share.png")
pie_chart.set_title("市场份额分布")
pie_chart.set_description("各产品线在总营收中的占比情况")
pie_chart.set_data_summary("产品A: 45% | 产品B: 30% | 产品C: 15% | 其他: 10%")

🔗 与数据分析库集成¶

与Matplotlib集成¶

Python

import matplotlib.pyplot as plt
import numpy as np
from email_widget import Email
from email_widget.widgets import ChartWidget

# 生成数据并创建图表
months = ['1月', '2月', '3月', '4月', '5月', '6月']
sales = [120, 135, 148, 162, 178, 195]

plt.figure(figsize=(10, 6))
plt.plot(months, sales, marker='o', linewidth=2, markersize=8)
plt.title('月度销售趋势', fontsize=16, fontweight='bold')
plt.xlabel('月份')
plt.ylabel('销售额(万元)')
plt.grid(True, alpha=0.3)
plt.tight_layout()

# 保存图表
chart_path = 'monthly_sales.png'
plt.savefig(chart_path, dpi=300, bbox_inches='tight')
plt.close()

# 在邮件中展示
email = Email("销售数据报告")
chart_widget = ChartWidget()
chart_widget.set_image_url(chart_path)
chart_widget.set_title("月度销售趋势分析")
chart_widget.set_description("展示2024年上半年销售业绩的持续增长态势")
chart_widget.set_data_summary(f"总销售额: {sum(sales)}万元 | 平均增长率: {((sales[-1]/sales[0])-1)*100:.1f}%")

email.add_widget(chart_widget)

📱 最佳实践¶

1. 选择合适的图表类型¶

Python

from email_widget import Email
from email_widget.widgets import ChartWidget

email = Email("数据可视化最佳实践")

# 趋势数据 -> 线图
trend_chart = ChartWidget()
trend_chart.set_image_url("time_series.png")
trend_chart.set_title("时间序列趋势")
trend_chart.set_description("适合展示随时间变化的数据")

# 分类对比 -> 柱状图  
comparison_chart = ChartWidget()
comparison_chart.set_image_url("category_comparison.png")
comparison_chart.set_title("分类数据对比")
comparison_chart.set_description("适合展示不同类别之间的比较")

# 占比关系 -> 饼图
proportion_chart = ChartWidget()
proportion_chart.set_image_url("proportion_chart.png")
proportion_chart.set_title("比例分布")
proportion_chart.set_description("适合展示部分与整体的关系")

email.add_widgets([trend_chart, comparison_chart, proportion_chart])

Chart Type Selection Guide

Generated: July 12, 2025 15:25:20

Time Series Trend

Best for showing data changes over time - Website traffic over 6 months

25K 20K 15K 10K 5K 0

Jan Feb Mar Apr May Jun

Category Comparison

Best for comparing different categories - Regional sales performance

150M 120M 90M 60M 30M 0

120M

East

85M

South

150M

North

95M

West

Proportion Distribution

Best for showing part-to-whole relationships - Product sales breakdown

Product A (45%)

Product B (30%)

Product C (15%)

Others (10%)

2. 业务数据仪表板¶

Python

from email_widget import Email
from email_widget.widgets import ChartWidget, TextWidget
from email_widget.core.enums import TextType

# 创建仪表板邮件
dashboard = Email("业务数据仪表板")

# 添加标题
title = TextWidget()
title.set_content("业务数据仪表板")
title.set_type(TextType.TITLE_LARGE)
title.set_align("center")
dashboard.add_widget(title)

# 创建多个图表
charts_data = [
    {
        'file': 'revenue_trend.png',
        'title': '营收趋势',
        'desc': '月度营收增长情况',
        'summary': '同比增长: +23%'
    },
    {
        'file': 'user_analytics.png', 
        'title': '用户分析',
        'desc': '用户活跃度和留存分析',
        'summary': '月活用户: 2.4M'
    },
    {
        'file': 'product_performance.png',
        'title': '产品表现', 
        'desc': '各产品线业绩对比',
        'summary': '核心产品占比: 68%'
    }
]

for chart_info in charts_data:
    chart = ChartWidget()
    chart.set_image_url(chart_info['file'])
    chart.set_title(chart_info['title'])
    chart.set_description(chart_info['desc'])
    chart.set_data_summary(chart_info['summary'])
    dashboard.add_widget(chart)

Business Data Dashboard

Generated: July 12, 2025 15:07:30

📈Revenue Trends

Monthly revenue growth - Shows revenue trend changes over the last 6 months

5M 4M 3M 2M 1M 0

Jan Feb Mar Apr May Jun

📊 YoY Growth: +23% | MoM Growth: +8.5% | Annual Target: 67%

👥User Analytics

User activity and retention analysis - Cross-platform user data comparison

3M 2.5M 2M 1.5M 1M 0.5M 0

2.8M

Mobile

2.2M

Desktop

3.2M

Mini-app

2.5M

H5 Page

👤 MAU: 2.4M | New Users: +45K | Retention Rate: 78.5%

📱Product Performance

Product line performance comparison - Product performance by revenue share

Core Products

68%

Premium Products

18%

Basic Products

10%

Other Products

🎯 Core Products: 68% | Premium Growth: +25% | Total Product Lines: 12

3. 完整业务报告¶

Python

from email_widget import Email
from email_widget.widgets import ChartWidget, TextWidget
from email_widget.core.enums import TextType

# 创建业务报告
report = Email("Q4业务分析报告")

# 报告标题
report_title = TextWidget()
report_title.set_content("第四季度业务分析报告")
report_title.set_type(TextType.TITLE_LARGE)
report_title.set_align("center")
report_title.set_color("#0078d4")
report.add_widget(report_title)

# 营收分析图表
revenue_chart = ChartWidget()
revenue_chart.set_image_url("q4_revenue_analysis.png")
revenue_chart.set_title("营收分析")
revenue_chart.set_description("第四季度各月营收情况及与去年同期对比")
revenue_chart.set_data_summary("Q4总营收: ¥18.5M | 同比增长: +15.2% | 环比增长: +8.7%")

# 用户增长图表  
growth_chart = ChartWidget()
growth_chart.set_image_url("user_growth_funnel.png")
growth_chart.set_title("用户增长漏斗")
growth_chart.set_description("从访问到转化的用户流失情况分析")
growth_chart.set_data_summary("访问用户: 2.4M | 注册转化: 12% | 付费转化: 3.2%")

# 产品表现图表
product_chart = ChartWidget()
product_chart.set_image_url("product_performance_matrix.png") 
product_chart.set_title("产品表现矩阵")
product_chart.set_description("各产品线的市场表现和增长潜力分析")
product_chart.set_data_summary("明星产品: 3个 | 问题产品: 1个 | 现金牛产品: 2个")

# 添加到报告
report.add_widgets([revenue_chart, growth_chart, product_chart])

Q4 Business Analysis Report

Generated: July 12, 2025 15:09:45

Q4 Business Analysis Report

Report Period: October 2024 - December 2024

💰Revenue Analysis

Q4 monthly revenue comparison with year-over-year analysis, showing business growth trends and seasonal characteristics

20M 16M 12M 8M 4M 0

Oct Nov Dec Oct(LY) Nov(LY) Dec(LY)

💹 Q4 Total Revenue: $18.5M | YoY Growth: +15.2% | QoQ Growth: +8.7% | Dec Record High

🔄User Growth Funnel

User conversion analysis from visit to purchase, identifying key bottlenecks and optimization opportunities

Website Visitors - 2.4M

Registered Users - 288K

Active Users - 180K

Paying Users - 76.8K

Visit→Register 12.0%

Active→Paying 42.7%

Total Conversion 3.2%

🎯 Visitors: 2.4M | Registration Rate: 12% | Payment Rate: 3.2% | User LTV: $67

📈Product Performance Matrix

Product line market performance and growth potential analysis using BCG matrix based on market share and growth rate

Star Products

Question Mark

Dogs

Cash Cow

High Growth Low Growth

Low Share High Share

Core SaaS
38%

Mobile
18%

Enterprise
30%

API Service
8%

Trial
4%

Others
2%

Star Products (3)

Cash Cow (2)

Question Mark (1)

⭐ Star Products: 3 | 💰 Cash Cow: 2 | ❓ Question Mark: 1 | 🐕 Dogs: 0

⚡ 快捷方法¶

Email 类提供了 add_chart 快捷方法：

Python

# 基础快捷方法
email.add_chart(
    image_url="sales_chart.png",
    title="销售图表"
)

# 带详细信息的快捷方法
email.add_chart(
    image_url="performance_chart.png",
    title="性能监控",
    description="系统关键指标实时监控",
    data_summary="响应时间: 245ms | QPS: 12.5K",
    max_width="800px"
)

🎯 样式和尺寸控制¶

图片尺寸优化¶

Python

# 设置最大宽度避免图片过大
large_chart = ChartWidget()
large_chart.set_image_url("wide_chart.png")
large_chart.set_max_width("800px")

# 移动端自适应
responsive_chart = ChartWidget()
responsive_chart.set_image_url("responsive_chart.png")
responsive_chart.set_max_width("100%")  # 自动适配容器宽度

提供清晰的标题和描述¶

Python

chart = ChartWidget()
chart.set_title("Q4营收分析")  # 简洁明确的标题
chart.set_description("展示第四季度月度营收变化及同比增长情况")  # 详细说明
chart.set_data_summary("总营收: ¥2.4M | 增长率: +15%")  # 关键数据
chart.set_alt_text("Q4营收分析柱状图")  # 无障碍访问

🐛 常见问题¶

Q: 图片无法显示怎么办？¶

A: 检查以下几点： - 确认图片URL是否正确 - 验证图片文件是否存在 - 检查网络连接和访问权限

Q: 如何选择合适的图片格式？¶

A: 推荐使用PNG格式以获得最佳兼容性：

Python

chart.set_image_url("chart.png")  # ✅ 推荐
# chart.set_image_url("chart.webp")  # ❌ 兼容性较差

Q: 图表在移动端显示异常？¶

A: 设置合适的最大宽度：

Python

chart.set_max_width("100%")  # 自动适配
chart.set_max_width("600px")  # 限制最大宽度

Q: 如何添加数据摘要？¶

A: 使用set_data_summary()方法：

Python

chart.set_data_summary("关键指标: 转化率 12% | ROI 3.2x | 客单价 ¥890")

🚨 注意事项¶

图片格式: 推荐使用PNG格式以获得最佳兼容性
文件大小: 控制图片文件大小，避免邮件过大
网络访问: 确保网络图片URL在邮件发送时可访问
替代文本: 为所有图表设置有意义的alt_text
移动适配: 使用百分比宽度确保移动设备显示正常

🔗 相关组件¶

ImageWidget - 基础图片展示组件
MetricWidget - 数据指标展示组件
CardWidget - 可以包含图表的卡片组件
TextWidget - 图表标题和说明文字

ChartWidget 图表组件¶

🎯 组件预览¶

Chart Component Preview

1. Chart Component Display

2024 Annual Sales Performance

✨ 核心特性¶

🚀 快速开始¶

基础用法¶

进阶用法¶

📊 图表类型示例¶

趋势线图表¶

柱状图表¶

饼图¶

🔗 与数据分析库集成¶

与Matplotlib集成¶

📱 最佳实践¶

1. 选择合适的图表类型¶

Chart Type Selection Guide

2. 业务数据仪表板¶

Business Data Dashboard

📊 Business Data Dashboard

3. 完整业务报告¶

Q4 Business Analysis Report

Q4 Business Analysis Report

⚡ 快捷方法¶

🎯 样式和尺寸控制¶

图片尺寸优化¶

提供清晰的标题和描述¶

🐛 常见问题¶

Q: 图片无法显示怎么办？¶

Q: 如何选择合适的图片格式？¶

Q: 图表在移动端显示异常？¶

Q: 如何添加数据摘要？¶

🚨 注意事项¶

🔗 相关组件¶