ImageWidget API¶

`ImageWidget(widget_id=None)` ¶

Bases: BaseWidget

Embed images in emails with optional titles and descriptions.

This widget simplifies the process of adding images to emails. It can handle images from network URLs or local files and automatically converts them to Base64-encoded data URIs to ensure images display correctly in most email clients without relying on external links.

Core features

Multi-source support: Can load images from URLs or local file paths.
Automatic inline: All images are automatically converted to Base64 and embedded in HTML for better compatibility.
Rich media: Supports adding titles and descriptions to images for rich media explanations.
Style control: Can customize image dimensions, maximum width, and border radius.

Attributes:

Name	Type	Description
`image_url`	`Optional[str]`	Processed image source, usually a Base64 data URI.
`title`	`Optional[str]`	Title below the image.
`description`	`Optional[str]`	Detailed description below the image title.
`alt_text`	`str`	Alternative text for the image, used for accessibility.

Examples:

Load an image from a network URL and add description:

Python

from email_widget.widgets import ImageWidget

image_from_url = (ImageWidget()
                  .set_image_url("https://www.example.com/images/product_photo.jpg")
                  .set_title("Latest Product Showcase")
                  .set_description("Shows the design and features of our latest model.")
                  .set_alt_text("Front view of the latest product")
                  .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, embed=True)` ¶

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

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

Parameters:

Name	Type	Description	Default
`image_url`	`Union[str, Path]`	图片的URL字符串或本地文件Path对象。	required
`cache`	`bool`	是否缓存网络图片，默认为True。	`True`
`embed`	`bool`	是否嵌入图片，默认为True。如果为False，网络URL将直接使用链接，本地文件会给出警告并强制嵌入。	`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"))
>>> # 使用外部链接而不嵌入
>>> widget = ImageWidget().set_image_url("https://example.com/image.png", embed=False)

`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, embed=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, embed=True)` ¶

`set_max_width(max_width)` ¶

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

`set_title(title)` ¶

`show_caption(show=True)` ¶