TableWidget API¶

`TableWidget(widget_id=None)` ¶

Bases: BaseWidget

创建一个用于在邮件中展示表格数据的微件.

该微件提供了灵活的方式来呈现结构化数据，无论是手动构建表格，还是直接从 pandas.DataFrame 导入数据.它支持多种样式选项，如斑马纹、边框、悬停效果，并能为特定单元格应用颜色和状态，以增强数据的可读性和视觉吸引力.

核心功能

数据源多样: 支持直接添加行数据，或从 pandas.DataFrame 导入.
样式定制: 可设置标题、表头、斑马纹、边框、悬停效果等.
单元格样式: 允许为单个单元格设置颜色、粗体和对齐方式，并支持状态着色.
邮件兼容性: 生成的 HTML 针对主流邮件客户端进行了优化，确保显示效果一致.

Attributes:

Name	Type	Description
`title`	`Optional[str]`	表格的标题.
`headers`	`List[str]`	表格的列头列表.
`rows`	`List[List[Union[str, TableCell]]]`	表格的行数据，每行包含字符串或 `TableCell` 对象.
`show_index`	`bool`	是否显示行索引.
`striped`	`bool`	是否启用斑马纹样式.
`bordered`	`bool`	是否显示所有单元格边框.
`hover_effect`	`bool`	是否启用鼠标悬停高亮效果.

Examples:

手动创建一个包含状态单元格的表格：

Python

from email_widget.widgets import TableWidget, TableCell
from email_widget.core.enums import StatusType

project_status_table = (TableWidget()                                .set_title("项目进度概览")                                .set_headers(["项目名称", "负责人", "进度", "状态"])                                .add_row(["Website Redesign", "Alice", "85%",
                                  TableCell("进行中", status=StatusType.INFO)])                                .add_row(["Mobile App Dev", "Bob", "100%",
                                  TableCell("已完成", status=StatusType.SUCCESS)])                                .add_row(["Backend Optimization", "Charlie", "60%",
                                  TableCell("有风险", status=StatusType.WARNING)])                                .set_striped(True)                                .set_bordered(True))

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

从 pandas.DataFrame 创建表格：

Python

import pandas as pd

data = {
    'Product': ['Laptop', 'Mouse', 'Keyboard'],
    'Sales': [1200, 300, 500],
    'Region': ['North', 'South', 'East']
}
df = pd.DataFrame(data)

sales_table = (TableWidget()                       .set_dataframe(df)                       .set_title("产品销售数据")                       .show_index(False) # 不显示索引
               .set_hover_effect(True))

初始化TableWidget实例.

Parameters:

Name	Type	Description	Default
`widget_id`	`Optional[str]`	可选的Widget ID.	`None`

Examples:

Python Console Session

>>> table = TableWidget()
>>> table_with_id = TableWidget("my-table")

Attributes¶

`dataframe` `property` ¶

获取DataFrame数据.

Returns:

Type	Description
`Optional[DataFrame]`	Optional[pd.DataFrame]: DataFrame对象或None.

`headers` `property` ¶

获取表头列表.

Returns:

Type	Description
`list[str]`	List[str]: 表头列表.

`rows` `property` ¶

获取行数据.

Returns:

Type	Description
`list[list[str \| TableCell]]`	List[List[Union[str, TableCell]]]: 行数据列表.

`title` `property` ¶

获取表格标题.

Returns:

Type	Description
`str \| None`	Optional[str]: 标题或None.

Functions¶

`add_colored_cell(value, color, bold=False, align='center')` ¶

创建彩色单元格.

此辅助方法用于快速创建一个带有自定义颜色、字体粗细和对齐方式的 TableCell 对象.

Parameters:

Name	Type	Description	Default
`value`	`str`	单元格显示的值.	required
`color`	`str`	单元格文本的颜色（CSS颜色值）.	required
`bold`	`bool`	是否加粗，默认为False.	`False`
`align`	`str`	对齐方式，默认为"center".	`'center'`

Returns:

Name	Type	Description
`TableCell`	`TableCell`	一个配置好的 `TableCell` 对象.

Examples:

Python Console Session

>>> cell = table.add_colored_cell("重要", "#ff0000", bold=True)

`add_data_row(row_data)` ¶

添加数据行（基于DataFrame）.

此方法用于向表格添加一行数据.如果表格已通过 set_dataframe 初始化，新行将添加到现有DataFrame中；否则，将创建一个新的DataFrame.

Parameters:

Name	Type	Description	Default
`row_data`	`list`	包含行数据的列表.列表的长度应与表头数量匹配.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Raises:

Type	Description
`ImportError`	如果未安装pandas库.

Examples:

Python Console Session

>>> table = TableWidget().add_data_row(["新项目", "0%", "开始"])

`add_row(row)` ¶

添加行数据.

Parameters:

Name	Type	Description	Default
`row`	`List[Union[str, TableCell]]`	行数据，可以是字符串或TableCell对象.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().add_row(["项目A", "80%", TableCell("进行中", status=StatusType.INFO)])

`add_status_cell(value, status)` ¶

创建状态单元格.

此辅助方法用于快速创建一个带有特定状态（如成功、警告、错误）的 TableCell 对象. 状态单元格会自动应用预定义的颜色和背景样式.

Parameters:

Name	Type	Description	Default
`value`	`str`	单元格显示的值.	required
`status`	`StatusType`	单元格的状态类型.	required

Returns:

Name	Type	Description
`TableCell`	`TableCell`	一个配置好的 `TableCell` 对象.

Examples:

Python Console Session

>>> cell = table.add_status_cell("成功", StatusType.SUCCESS)

`clear_data()` ¶

清空表格数据.

此方法将清除通过 set_dataframe 或 add_data_row 添加的所有数据，并重置内部的DataFrame和行数据列表.

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().clear_data()

`clear_rows()` ¶

清空行数据.

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().clear_rows()

`get_template_context()` ¶

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

`set_border_color(color)` ¶

设置边框颜色.

Parameters:

Name	Type	Description	Default
`color`	`str`	CSS颜色值.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_border_color("#ddd")

`set_bordered(bordered=True)` ¶

设置是否显示边框.

Parameters:

Name	Type	Description	Default
`bordered`	`bool`	是否显示边框，默认为True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_bordered(False)

`set_column_width(column, width)` ¶

设置列宽度

`set_dataframe(df)` ¶

设置DataFrame数据.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	pandas DataFrame对象.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Raises:

Type	Description
`ImportError`	如果未安装pandas库.

Examples:

Python

import pandas as pd
df = pd.DataFrame({'名称': ['项目A', '项目B'], '状态': ['完成', '进行中']})
table = TableWidget().set_dataframe(df)

`set_header_bg_color(color)` ¶

设置表头背景色.

Parameters:

Name	Type	Description	Default
`color`	`str`	CSS颜色值.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_header_bg_color("#4CAF50")

`set_headers(headers)` ¶

设置表头.

Parameters:

Name	Type	Description	Default
`headers`	`List[str]`	表头列表.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_headers(["项目名称", "进度", "状态"])

`set_hover_effect(hover=True)` ¶

设置是否启用悬停效果.

Parameters:

Name	Type	Description	Default
`hover`	`bool`	是否启用悬停效果，默认为True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_hover_effect(False)

`set_max_width(width)` ¶

设置最大宽度.

Parameters:

Name	Type	Description	Default
`width`	`str`	CSS宽度值.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_max_width("800px")

`set_rows(rows)` ¶

设置所有行数据.

Parameters:

Name	Type	Description	Default
`rows`	`List[List[Union[str, TableCell]]]`	行数据列表.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python

rows = [
    ["项目A", "80%", TableCell("进行中", status=StatusType.INFO)],
    ["项目B", "100%", TableCell("完成", status=StatusType.SUCCESS)]
]
table = TableWidget().set_rows(rows)

`set_striped(striped=True)` ¶

设置是否使用斑马纹.

Parameters:

Name	Type	Description	Default
`striped`	`bool`	是否使用斑马纹，默认为True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_striped(False)

`set_title(title)` ¶

设置表格标题.

Parameters:

Name	Type	Description	Default
`title`	`str`	表格标题.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().set_title("项目进度表")

`show_index(show=True)` ¶

设置是否显示索引.

Parameters:

Name	Type	Description	Default
`show`	`bool`	是否显示索引，默认为True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	返回self以支持链式调用.

Examples:

Python Console Session

>>> table = TableWidget().show_index(False)

`TableCell(value, status=None, color=None, bold=False, align='center')` ¶

表格单元格类.

用于封装表格中单个单元格的数据和样式信息，支持设置单元格的值、状态、颜色、字体粗细和对齐方式.这使得表格能够展示更丰富、更具表现力的数据.

Attributes:

Name	Type	Description
`value`	`Any`	单元格的实际值，可以是任何类型，最终会转换为字符串显示.
`status`	`Optional[StatusType]`	单元格的状态类型，用于应用预定义的颜色和背景.
`color`	`Optional[str]`	单元格文本的自定义颜色（CSS颜色值）.
`bold`	`bool`	单元格文本是否加粗.
`align`	`str`	单元格文本的对齐方式（如 "left", "center", "right"）.

Examples:

Python

from email_widget.widgets import TableCell
from email_widget.core.enums import StatusType

# 创建一个成功状态的单元格
success_cell = TableCell("成功", status=StatusType.SUCCESS, bold=True)

# 创建一个自定义颜色的单元格
red_text_cell = TableCell("警告", color="#FF0000", align="right")

初始化表格单元格.

Parameters:

Name	Type	Description	Default
`value`	`Any`	单元格值.	required
`status`	`Optional[StatusType]`	状态类型，用于应用预定义的颜色和背景.	`None`
`color`	`Optional[str]`	文字颜色（CSS颜色值）.	`None`
`bold`	`bool`	是否粗体，默认为False.	`False`
`align`	`str`	对齐方式，默认为"center".	`'center'`

Examples:

Python Console Session

>>> cell = TableCell("成功", status=StatusType.SUCCESS, bold=True)

TableWidget API¶

TableWidget(widget_id=None) ¶

Attributes¶

dataframe property ¶

headers property ¶

rows property ¶

title property ¶

Functions¶

add_colored_cell(value, color, bold=False, align='center') ¶

add_data_row(row_data) ¶

add_row(row) ¶

add_status_cell(value, status) ¶

clear_data() ¶

clear_rows() ¶

get_template_context() ¶

set_border_color(color) ¶

set_bordered(bordered=True) ¶

set_column_width(column, width) ¶

set_dataframe(df) ¶

set_header_bg_color(color) ¶

set_headers(headers) ¶

set_hover_effect(hover=True) ¶

set_max_width(width) ¶

set_rows(rows) ¶

set_striped(striped=True) ¶

set_title(title) ¶

show_index(show=True) ¶

TableCell(value, status=None, color=None, bold=False, align='center') ¶

Functions¶

`TableWidget(widget_id=None)` ¶

`dataframe` `property` ¶

`headers` `property` ¶

`rows` `property` ¶

`title` `property` ¶

`add_colored_cell(value, color, bold=False, align='center')` ¶

`add_data_row(row_data)` ¶

`add_row(row)` ¶

`add_status_cell(value, status)` ¶

`clear_data()` ¶

`clear_rows()` ¶

`get_template_context()` ¶

`set_border_color(color)` ¶

`set_bordered(bordered=True)` ¶

`set_column_width(column, width)` ¶

`set_dataframe(df)` ¶

`set_header_bg_color(color)` ¶

`set_headers(headers)` ¶

`set_hover_effect(hover=True)` ¶

`set_max_width(width)` ¶

`set_rows(rows)` ¶

`set_striped(striped=True)` ¶

`set_title(title)` ¶

`show_index(show=True)` ¶

`TableCell(value, status=None, color=None, bold=False, align='center')` ¶