ImageWidget API¶

`ImageWidget(widget_id=None)` ¶

Bases: BaseWidget

在邮件中嵌入图片，并可选择性地附带标题和描述。

该微件简化了在邮件中添加图片的过程。它能够处理来自网络 URL 或本地文件的图片，并自动将其转换为 Base64 编码的 data URI，以确保图片能在绝大多数邮件客户端中正确显示，无需依赖外部链接。

核心功能

多源支持: 可加载来自 URL 或本地文件路径的图片。
自动内联: 所有图片都会被自动转换为 Base64 并嵌入 HTML，提高兼容性。
图文并茂: 支持为图片添加标题和描述，形成图文说明。
样式控制: 可以自定义图片的尺寸、最大宽度和边框圆角。

Attributes:

Name	Type	Description
`image_url`	`Optional[str]`	处理后的图片来源，通常为 Base64 data URI。
`title`	`Optional[str]`	图片下方的标题。
`description`	`Optional[str]`	图片标题下方的详细描述。
`alt_text`	`str`	图片的替代文本，用于可访问性（Accessibility）。

Examples:

从网络 URL 加载一张图片并添加说明：

Python

from email_widget.widgets import ImageWidget

image_from_url = (ImageWidget()
                  .set_image_url("https://www.example.com/images/product_photo.jpg")
                  .set_title("最新产品展示")
                  .set_description("展示了我们最新型号的设计和功能。")
                  .set_alt_text("最新产品的正面照片")
                  .set_size(width="100%", height="auto")
                  .set_max_width("600px")
                  .set_border_radius("8px"))

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

从本地文件加载图片：

Python

from pathlib import Path

local_image_path = Path("./assets/company_logo.png")
logo_image = ImageWidget().set_image_url(local_image_path)

初始化ImageWidget。

Parameters:

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

Attributes¶

`alt_text` `property` ¶

获取图片的替代文本。

Returns:

Name	Type	Description
`str`	`str`	图片的替代文本。

`border_radius` `property` ¶

获取边框圆角。

Returns:

Name	Type	Description
`str`	`str`	边框圆角值。

`description` `property` ¶

获取图片描述。

Returns:

Type	Description
`str \| None`	Optional[str]: 图片描述或None。

`height` `property` ¶

获取图片高度。

Returns:

Type	Description
`str \| None`	Optional[str]: 图片高度或None。

`image_url` `property` ¶

获取处理后的图片URL（通常为Base64 data URI）。

Returns:

Type	Description
`str \| None`	Optional[str]: 图片的Base64 data URI或None。

`is_show_caption` `property` ¶

判断是否显示标题和描述。

Returns:

Name	Type	Description
`bool`	`bool`	如果显示标题和描述则为True，否则为False。

`title` `property` ¶

获取图片标题。

Returns:

Type	Description
`str \| None`	Optional[str]: 图片标题或None。

`width` `property` ¶

获取图片宽度。

Returns:

Type	Description
`str \| None`	Optional[str]: 图片宽度或None。

Functions¶

`get_template_context()` ¶

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

`set_alt_text(alt)` ¶

设置图片的替代文本。

替代文本在图片无法显示时提供描述，对可访问性（Accessibility）非常重要。

Parameters:

Name	Type	Description	Default
`alt`	`str`	图片的替代文本。	required

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = ImageWidget().set_alt_text("公司Logo")

`set_border_radius(radius)` ¶

设置图片的边框圆角。

Parameters:

Name	Type	Description	Default
`radius`	`str`	CSS边框圆角值，如 "8px", "50%"。	required

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = ImageWidget().set_border_radius("8px")
>>> widget = ImageWidget().set_border_radius("50%") # 圆形图片

`set_description(description)` ¶

设置图片描述。

Parameters:

Name	Type	Description	Default
`description`	`str`	图片标题下方的详细描述文本。	required

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = ImageWidget().set_description("此图展示了过去一年的销售数据变化。")

`set_image_url(image_url, cache=True)` ¶

设置图片来源URL或本地路径。

此方法支持从网络URL或本地文件路径加载图片。图片会被自动处理并转换为 Base64编码的data URI，直接嵌入到HTML中，以确保在邮件客户端中的兼容性。

Parameters:

Name	Type	Description	Default
`image_url`	`Union[str, Path]`	图片的URL字符串或本地文件Path对象。	required
`cache`	`bool`	是否缓存网络图片，默认为True。	`True`

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Raises:

Type	Description
`ValueError`	如果图片URL或路径无效，或图片处理失败。

Examples:

Python Console Session

>>> widget = ImageWidget().set_image_url("https://example.com/image.png")
>>> from pathlib import Path
>>> widget = ImageWidget().set_image_url(Path("local/image.jpg"))

`set_max_width(max_width)` ¶

设置图片的最大宽度。

Parameters:

Name	Type	Description	Default
`max_width`	`str`	CSS最大宽度值，如 "600px", "100%"。	required

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = ImageWidget().set_max_width("600px")

`set_size(width=None, height=None)` ¶

设置图片的宽度和高度。

Parameters:

Name	Type	Description	Default
`width`	`Optional[str]`	图片的宽度，如 "100px", "50%", "auto"。	`None`
`height`	`Optional[str]`	图片的高度，如 "200px", "auto"。	`None`

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Raises:

Type	Description
`ValueError`	当尺寸格式无效时。

Examples:

Python Console Session

>>> widget = ImageWidget().set_size(width="300px", height="200px")
>>> widget = ImageWidget().set_size(width="100%", height="auto")

`set_title(title)` ¶

设置图片标题。

Parameters:

Name	Type	Description	Default
`title`	`str`	图片下方的标题文本。	required

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = ImageWidget().set_title("产品销售趋势图")

`show_caption(show=True)` ¶

设置是否显示图片标题和描述。

Parameters:

Name	Type	Description	Default
`show`	`bool`	是否显示标题和描述，默认为True。	`True`

Returns:

Name	Type	Description
`ImageWidget`	`ImageWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = ImageWidget().show_caption(False) # 隐藏标题和描述

ImageWidget API¶

ImageWidget(widget_id=None) ¶

Attributes¶

alt_text property ¶

border_radius property ¶

description property ¶

height property ¶

image_url property ¶

is_show_caption property ¶

title property ¶

width property ¶

Functions¶

get_template_context() ¶

set_alt_text(alt) ¶

set_border_radius(radius) ¶

set_description(description) ¶

set_image_url(image_url, cache=True) ¶

set_max_width(max_width) ¶

set_size(width=None, height=None) ¶

set_title(title) ¶

show_caption(show=True) ¶

`ImageWidget(widget_id=None)` ¶

`alt_text` `property` ¶

`border_radius` `property` ¶

`description` `property` ¶

`height` `property` ¶

`image_url` `property` ¶

`is_show_caption` `property` ¶

`title` `property` ¶

`width` `property` ¶

`get_template_context()` ¶

`set_alt_text(alt)` ¶

`set_border_radius(radius)` ¶

`set_description(description)` ¶

`set_image_url(image_url, cache=True)` ¶

`set_max_width(max_width)` ¶

`set_size(width=None, height=None)` ¶

`set_title(title)` ¶

`show_caption(show=True)` ¶