CardWidget API¶
CardWidget(widget_id=None)
¶
Bases: BaseWidget
创建一个内容卡片，用于以结构化的方式展示信息.
卡片是组织和呈现信息的理想选择，常用于展示数据摘要、状态更新、个人资料等. 它支持标题、主要内容、图标以及一个或多个元数据条目.
Attributes:
| Name | Type | Description |
|---|---|---|
title |
Optional[str]
|
卡片的标题. |
content |
str
|
卡片的主要内容文本. |
icon |
Optional[str]
|
显示在标题前的图标，可以是 Emoji 或其他字符. |
metadata |
Dict[str, str]
|
一个键值对字典，用于在卡片底部显示额外信息. |
Examples:
创建一个用于展示服务状态的卡片：
from email_widget.widgets import CardWidget
card = CardWidget()
card.set_title("API 服务监控")
card.set_content("所有服务均运行正常，平均响应时间为 50ms.")
card.set_icon("✅")
card.add_metadata("最后检查时间", "2024-07-07 10:30:00")
card.add_metadata("在线率", "99.99%")
# 使用链式调用可以使代码更紧凑：
server_status_card = (CardWidget() .set_title("数据库服务器") .set_content("连接正常，磁盘空间充足.") .set_icon("🗄️") .set_metadata({
"CPU 使用率": "15%",
"内存占用": "2.5 GB / 16 GB"
}))
初始化CardWidget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
widget_id
|
Optional[str]
|
可选的Widget ID. |
None
|
Functions¶
add_metadata(key, value)
¶
向卡片添加一个元数据条目.
元数据以键值对的形式显示在卡片底部.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
元数据项的键（名称）. |
required |
value
|
str
|
元数据项的值. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
CardWidget |
CardWidget
|
返回self以支持链式调用. |
Examples:
clear_metadata()
¶
get_template_context()
¶
获取模板渲染所需的上下文数据
set_content(content)
¶
设置卡片的主要内容文本.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
str
|
卡片内容文本. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
CardWidget |
CardWidget
|
返回self以支持链式调用. |
Raises:
| Type | Description |
|---|---|
ValueError
|
当内容为空时. |
Examples:
set_icon(icon)
¶
设置显示在标题前的图标.
图标可以是任何字符串（如Emoji字符）或 IconType 枚举值.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
icon
|
Union[str, IconType]
|
图标字符串或 |
required |
Returns:
| Name | Type | Description |
|---|---|---|
CardWidget |
CardWidget
|
返回self以支持链式调用. |
Examples:
set_metadata(metadata)
¶
设置卡片的所有元数据.
此方法会替换所有现有的元数据.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
metadata
|
Dict[str, str]
|
包含所有元数据项的字典. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
CardWidget |
CardWidget
|
返回self以支持链式调用. |
Examples:
set_status(status)
¶
设置卡片的状态.
此状态通常用于内部逻辑或未来可能的视觉指示，目前不直接影响卡片外观.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
status
|
StatusType
|
卡片的状态类型. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
CardWidget |
CardWidget
|
返回self以支持链式调用. |
Examples:
set_title(title)
¶
设置卡片的标题.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title
|
str
|
卡片标题文本. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
CardWidget |
CardWidget
|
返回self以支持链式调用. |
Raises:
| Type | Description |
|---|---|
ValueError
|
当标题为空时. |
Examples: