CardWidget 卡片组件¶
🎴 卡片展示组件
📊 数据统计报告
本月系统运行状况良好,各项指标均在正常范围内。用户活跃度较上月提升15%,系统响应时间保持在100ms以内。
报告时间: 2024-01-15
报告类型: 月度总结
状态: 正常
内容展示
元数据
状态指示
CardWidget是一个通用的卡片容器组件,用于展示结构化的内容信息。它支持标题、内容、图标和元数据的组合展示,是构建信息面板、产品展示和内容摘要的理想选择。
🎯 主要功能¶
内容展示¶
- 标题支持:可选的卡片标题
- 内容区域:主要内容展示区域
- 图标装饰:支持多种图标类型
- 状态指示:支持不同状态的视觉反馈
元数据管理¶
- 键值对:支持添加元数据信息
- 动态管理:支持动态添加、更新和清除元数据
- 灵活展示:元数据区域自动布局
样式定制¶
- 阴影效果:可选的卡片阴影
- 边框圆角:可自定义圆角大小
- 内边距:可调整内容间距
📋 核心方法¶
基础使用¶
Python
from email_widget.widgets import CardWidget
from email_widget.core.enums import StatusType, IconType
# 创建卡片组件
card = CardWidget()
# 设置基本信息
card.set_title("产品介绍")
card.set_content("这是一个功能强大的邮件组件库,提供了丰富的UI组件。")
card.set_icon(IconType.INFO)
内容管理方法¶
Python
# 设置标题
card.set_title("卡片标题")
# 设置内容
card.set_content("卡片的主要内容信息")
# 设置图标
card.set_icon(IconType.SUCCESS) # 使用预定义图标
card.set_icon("🎉") # 使用自定义图标
# 设置状态
card.set_status(StatusType.SUCCESS)
元数据管理¶
Python
# 添加单个元数据
card.add_metadata("作者", "张三")
card.add_metadata("创建时间", "2024-01-15")
# 批量设置元数据
metadata = {
"版本": "v1.0.0",
"大小": "2.5MB",
"更新时间": "2024-01-15"
}
card.set_metadata(metadata)
# 清空元数据
card.clear_metadata()
💡 实用示例¶
产品展示卡片¶
Python
from email_widget.widgets import CardWidget
from email_widget.core.enums import StatusType, IconType
# 创建产品展示卡片
product_card = CardWidget()
product_card.set_title("EmailWidget Pro")
product_card.set_content("专业的Python邮件组件库,提供丰富的UI组件和强大的邮件渲染能力。支持多种组件类型,完美适配各种邮件客户端。")
product_card.set_icon(IconType.SUCCESS)
product_card.set_status(StatusType.SUCCESS)
# 添加产品信息
product_card.add_metadata("版本", "v2.1.0")
product_card.add_metadata("许可证", "MIT")
product_card.add_metadata("支持Python", "3.8+")
product_card.add_metadata("最后更新", "2024-01-15")
# 渲染卡片
html = product_card.render_html()
用户信息卡片¶
Python
# 创建用户信息卡片
user_card = CardWidget()
user_card.set_title("用户档案")
user_card.set_content("高级开发工程师,专注于Python后端开发和数据分析。拥有5年以上的项目经验,熟悉多种开发框架和工具。")
user_card.set_icon("👤")
# 添加用户信息
user_card.add_metadata("姓名", "李四")
user_card.add_metadata("职位", "高级工程师")
user_card.add_metadata("部门", "技术部")
user_card.add_metadata("入职时间", "2019-03-15")
user_card.add_metadata("邮箱", "lisi@example.com")
项目状态卡片¶
Python
# 创建项目状态卡片
project_card = CardWidget()
project_card.set_title("项目进展")
project_card.set_content("EmailWidget项目开发进展顺利,目前已完成核心功能开发,正在进行测试和文档编写阶段。")
project_card.set_icon(IconType.INFO)
project_card.set_status(StatusType.SUCCESS)
# 添加项目信息
project_card.add_metadata("项目名称", "EmailWidget")
project_card.add_metadata("项目状态", "开发中")
project_card.add_metadata("完成度", "85%")
project_card.add_metadata("预计完成", "2024-02-01")
project_card.add_metadata("负责人", "王五")
通知消息卡片¶
Python
# 创建通知消息卡片
notification_card = CardWidget()
notification_card.set_title("系统通知")
notification_card.set_content("系统将在今晚22:00-24:00进行维护升级,届时可能会影响部分功能的正常使用,请提前做好相关准备。")
notification_card.set_icon("⚠️")
notification_card.set_status(StatusType.WARNING)
# 添加通知信息
notification_card.add_metadata("通知类型", "系统维护")
notification_card.add_metadata("影响范围", "全系统")
notification_card.add_metadata("维护时间", "22:00-24:00")
notification_card.add_metadata("发布时间", "2024-01-15 10:30")
数据报告卡片¶
Python
# 创建数据报告卡片
report_card = CardWidget()
report_card.set_title("月度数据报告")
report_card.set_content("本月网站访问量达到新高,用户活跃度显著提升。移动端访问占比持续增长,用户体验优化效果明显。")
report_card.set_icon("📊")
report_card.set_status(StatusType.INFO)
# 添加报告数据
report_card.add_metadata("报告周期", "2024年1月")
report_card.add_metadata("总访问量", "1,234,567")
report_card.add_metadata("活跃用户", "45,678")
report_card.add_metadata("移动端占比", "68%")
report_card.add_metadata("生成时间", "2024-01-15 09:00")
🎨 图标类型详解¶
预定义图标¶
图标类型 | 显示效果 | 适用场景 |
---|---|---|
IconType.INFO |
ℹ️ | 信息提示、说明 |
IconType.SUCCESS |
✅ | 成功状态、完成 |
IconType.WARNING |
⚠️ | 警告信息、注意 |
IconType.ERROR |
❌ | 错误状态、失败 |
IconType.QUESTION |
❓ | 帮助信息、疑问 |
自定义图标¶
Python
# 使用Emoji图标
card.set_icon("🎉") # 庆祝
card.set_icon("📈") # 数据增长
card.set_icon("🔧") # 工具/设置
card.set_icon("👤") # 用户
card.set_icon("📊") # 报告/统计
# 使用Unicode符号
card.set_icon("★") # 星号
card.set_icon("●") # 圆点
card.set_icon("▲") # 三角形
📊 状态类型说明¶
状态视觉效果¶
状态类型 | 视觉效果 | 适用场景 |
---|---|---|
SUCCESS |
成功色调 | 完成状态、正常运行 |
WARNING |
警告色调 | 需要注意、待处理 |
ERROR |
错误色调 | 异常状态、错误信息 |
INFO |
信息色调 | 一般信息、说明 |
PRIMARY |
主色调 | 重要信息、突出显示 |
🎨 最佳实践¶
1. 内容结构化¶
Python
# 保持内容结构清晰
card = CardWidget()
card.set_title("明确的标题") # 简洁明了的标题
card.set_content("详细的内容描述...") # 重要信息在前
card.set_icon(IconType.INFO) # 合适的图标
# 元数据按重要性排序
card.add_metadata("关键信息", "重要数据")
card.add_metadata("补充信息", "额外数据")
2. 状态和图标搭配¶
Python
# 状态和图标保持一致
success_card = CardWidget()
success_card.set_status(StatusType.SUCCESS)
success_card.set_icon(IconType.SUCCESS)
warning_card = CardWidget()
warning_card.set_status(StatusType.WARNING)
warning_card.set_icon(IconType.WARNING)
3. 元数据管理¶
Python
# 批量设置元数据
metadata = {
"创建时间": "2024-01-15",
"更新时间": "2024-01-15",
"作者": "张三",
"版本": "v1.0.0"
}
card.set_metadata(metadata)
# 动态更新元数据
def update_card_metadata(card, new_data):
for key, value in new_data.items():
card.add_metadata(key, value)
4. 组合使用¶
Python
# 多卡片组合展示
from email_widget.widgets import ColumnWidget
# 创建卡片组合
column = ColumnWidget().set_columns(2)
# 创建多个相关卡片
cards = []
for i in range(4):
card = CardWidget()
card.set_title(f"卡片 {i+1}")
card.set_content(f"这是第{i+1}个卡片的内容")
card.set_icon(IconType.INFO)
cards.append(card)
# 组合显示
column.add_widgets(cards)
5. 响应式设计¶
Python
# 根据内容长度调整卡片
def create_adaptive_card(title, content, metadata=None):
card = CardWidget()
card.set_title(title)
card.set_content(content)
# 根据内容长度选择图标
if len(content) > 100:
card.set_icon("📄") # 长文档
else:
card.set_icon(IconType.INFO) # 简短信息
if metadata:
card.set_metadata(metadata)
return card
🔧 常见问题¶
Q: 如何控制卡片的宽度?¶
A: 卡片宽度由容器控制,可以通过外层布局组件(如ColumnWidget)来管理。
Q: 元数据区域可以自定义样式吗?¶
A: 元数据区域使用统一的样式,如需自定义可以通过CSS覆盖。
Q: 卡片内容支持HTML吗?¶
A: 支持基本的HTML标签,但建议使用纯文本以确保邮件客户端兼容性。
Q: 如何实现卡片的点击效果?¶
A: 在邮件环境中,可以通过包装链接标签来实现点击跳转。
CardWidget为您提供了灵活而美观的内容展示方案,无论是产品介绍、用户信息还是数据报告,都能完美呈现!