跳转至

ColumnWidget API

ColumnWidget(widget_id=None)

Bases: BaseWidget

创建一个多列布局容器，用于水平排列多个微件。

该微件使用 <table> 元素来确保在各种邮件客户端中的最大兼容性。 你可以将任何其他微件（如 TextWidget, CardWidget, ChartWidget 等） 放入列布局中，以创建复杂且美观的邮件版式。

核心功能
  • 自动列数: 默认情况下，它会根据内部微件的数量智能地计算出最佳列数。
  • 手动列数: 你也可以手动指定1到4之间的固定列数。
  • 响应式: 布局会根据屏幕宽度自动调整，确保在桌面和移动设备上都有良好体验。
  • 间隔控制: 可以自定义列与列之间的水平间距。
自动列数规则
  • 1个微件: 1列
  • 2个微件: 2列
  • 3个微件: 3列
  • 4个微件: 2列 (2x2 网格)
  • 5-6个微件: 3列
  • 7-8个微件: 2列
  • 9个及以上: 3列

Examples:

创建一个两列布局，左侧是卡片，右侧是图表：

Python
from email_widget.widgets import ColumnWidget, CardWidget, ChartWidget
import matplotlib.pyplot as plt

# 准备左侧卡片
left_card = (CardWidget()
             .set_title("关键指标")
             .add_metadata("用户增长", "+15%")
             .add_metadata("收入", "+12%"))

# 准备右侧图表
plt.figure()
plt.plot([1, 2, 3], [4, 5, 2])
right_chart = ChartWidget().set_chart(plt)

# 创建2列布局并添加微件
two_column_layout = (ColumnWidget()
                     .set_columns(2)
                     .set_gap("24px")
                     .add_widget(left_card)
                     .add_widget(right_chart))

# 假设 email 是一个 Email 对象
# email.add_widget(two_column_layout)

初始化ColumnWidget。

Parameters:

Name Type Description Default
widget_id Optional[str]

可选的Widget ID。

 None

Functions

add_widget(widget)

向列布局中添加一个微件。

Parameters:

Name Type Description Default
widget BaseWidget

要添加的微件实例。

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Examples:

Python Console Session
>>> column = ColumnWidget().add_widget(TextWidget().set_content("左侧内容"))
add_widgets(widgets)

向列布局中添加多个微件。

Parameters:

Name Type Description Default
widgets List[BaseWidget]

要添加的微件实例列表。

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Examples:

Python Console Session
>>> column = ColumnWidget().add_widgets([TextWidget(), ImageWidget()])
clear_widgets()

清空列布局中的所有微件。

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Examples:

Python Console Session
>>> column = ColumnWidget().clear_widgets()
get_current_columns()

获取当前实际使用的列数。

如果处于自动模式，则返回根据微件数量计算出的列数；否则返回手动设置的列数。

Returns:

Name Type Description
int int

实际使用的列数。

Examples:

Python Console Session
>>> column = ColumnWidget().add_widgets([TextWidget(), TextWidget()])
>>> column.get_current_columns() # 自动模式下，2个微件返回2列
get_effective_columns()

获取实际生效的列数。

如果设置为自动模式，则根据当前微件数量计算；否则返回手动设置的列数。

Returns:

Name Type Description
int int

实际使用的列数。
get_template_context()

获取模板渲染所需的上下文数据

get_widget_count()

获取列布局中微件的数量。

Returns:

Name Type Description
int int

微件的数量。

Examples:

Python Console Session
>>> count = ColumnWidget().add_widget(TextWidget()).get_widget_count()
>>> print(count) # 输出: 1
is_auto_mode()

检查当前是否为自动列数模式。

Returns:

Name Type Description
bool bool

如果是自动模式则为True，否则为False。

Examples:

Python Console Session
>>> column = ColumnWidget().is_auto_mode() # 默认为True
remove_widget(widget_id)

根据微件ID移除指定的微件。

Parameters:

Name Type Description Default
widget_id str

要移除的微件的ID。

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Examples:

Python Console Session
>>> column = ColumnWidget().remove_widget("my_text_widget")
remove_widget_by_index(index)

移除指定索引的微件。

Parameters:

Name Type Description Default
index int

要移除的微件的索引。

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Raises:

Type Description
IndexError

如果索引超出范围。

Examples:

Python Console Session
>>> column = ColumnWidget().remove_widget_by_index(0) # 移除第一个微件
set_columns(columns)

设置列布局的列数。

Parameters:

Name Type Description Default
columns int

列数。-1表示自动模式，其他值限制在1到4列之间。

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Examples:

Python Console Session
>>> column = ColumnWidget().set_columns(2) # 设置为2列
>>> column = ColumnWidget().set_columns(-1) # 自动模式
set_equal_width(equal=True)

设置列是否等宽。

Parameters:

Name Type Description Default
equal bool

是否等宽，默认为True。

 True

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。
Note

此方法目前仅为预留接口，实际渲染中列宽始终等分。

Examples:

Python Console Session
>>> column = ColumnWidget().set_equal_width(False)
set_gap(gap)

设置列之间的水平间距。

Parameters:

Name Type Description Default
gap str

CSS间距值，如 "20px", "1em"。

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

返回self以支持链式调用。

Examples:

Python Console Session
>>> column = ColumnWidget().set_gap("16px")