CircularProgressWidget API¶

`CircularProgressWidget(widget_id=None)` ¶

Bases: BaseWidget

创建一个圆形的进度指示器。

圆形进度条以紧凑且直观的方式展示任务的完成度、资源的占用率或任何可量化的百分比数据。它非常适合用在仪表盘或需要节省空间的报告中。

核心功能

动态更新: 支持设置、增加、减少、重置或直接完成进度。
主题化: 提供多种预设主题（如成功、警告、错误），以颜色直观反映状态。
自定义外观: 可以自由调整进度环的大小和线条粗细。

Attributes:

Name	Type	Description
`value`	`float`	当前的进度值。
`max_value`	`float`	进度的最大值，默认为 100。
`label`	`Optional[str]`	显示在进度环下方的说明文字。
`theme`	`ProgressTheme`	进度环的颜色主题。

Examples:

创建一个显示任务完成度的圆形进度条：

Python

from email_widget.widgets import CircularProgressWidget
from email_widget.core.enums import ProgressTheme

# 创建一个表示 "成功" 状态的进度环
task_progress = (CircularProgressWidget()
                 .set_value(85)
                 .set_label("数据处理进度")
                 .set_theme(ProgressTheme.SUCCESS)
                 .set_size("120px")
                 .set_stroke_width("10px"))

# 创建一个表示 "警告" 状态的资源监控环
disk_usage = (CircularProgressWidget()
              .set_value(92)
              .set_label("磁盘使用率")
              .set_theme(ProgressTheme.WARNING)
              .set_size("90px"))

初始化CircularProgressWidget。

Parameters:

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

Functions¶

`complete()` ¶

将进度设置为最大值（100%）。

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().complete() # 进度变为100%

`decrement(amount=1.0)` ¶

减少进度值。

Parameters:

Name	Type	Description	Default
`amount`	`float`	减少的量，默认为1.0。	`1.0`

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(50).decrement(5) # 进度变为45

`get_template_context()` ¶

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

`increment(amount=1.0)` ¶

增加进度值。

Parameters:

Name	Type	Description	Default
`amount`	`float`	增加的量，默认为1.0。	`1.0`

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(50).increment(10) # 进度变为60

`reset()` ¶

重置进度为0。

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(75).reset() # 进度变为0

`set_label(label)` ¶

设置显示在进度环下方的说明性标签。

Parameters:

Name	Type	Description	Default
`label`	`str`	标签文本。	required

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_label("任务完成度")

`set_max_value(max_val)` ¶

设置进度的最大值。

Parameters:

Name	Type	Description	Default
`max_val`	`float`	进度的最大值。	required

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_max_value(200)

`set_size(size)` ¶

设置圆形进度条的整体大小。

Parameters:

Name	Type	Description	Default
`size`	`str`	CSS尺寸值，如 "100px", "5em"。	required

Returns:

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

Raises:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_size("120px")

`set_stroke_width(width)` ¶

设置圆形进度条的线条粗细。

Parameters:

Name	Type	Description	Default
`width`	`str`	CSS宽度值，如 "8px", "0.5em"。	required

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_stroke_width("12px")

`set_theme(theme)` ¶

设置进度环的颜色主题。

Parameters:

Name	Type	Description	Default
`theme`	`ProgressTheme`	进度环主题枚举值。	required

Returns:

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

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_theme(ProgressTheme.SUCCESS)

`set_value(value)` ¶

设置当前的进度值。

Parameters:

Name	Type	Description	Default
`value`	`float`	进度值，应在0到 `max_value` 之间。	required

Returns:

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

Raises:

Type	Description
`ValueError`	当值超出有效范围时。

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(75)

CircularProgressWidget API¶

CircularProgressWidget(widget_id=None) ¶

Functions¶

complete() ¶

decrement(amount=1.0) ¶

get_template_context() ¶

increment(amount=1.0) ¶

reset() ¶

set_label(label) ¶

set_max_value(max_val) ¶

set_size(size) ¶

set_stroke_width(width) ¶

set_theme(theme) ¶

set_value(value) ¶

`CircularProgressWidget(widget_id=None)` ¶

`complete()` ¶

`decrement(amount=1.0)` ¶

`get_template_context()` ¶

`increment(amount=1.0)` ¶

`reset()` ¶

`set_label(label)` ¶

`set_max_value(max_val)` ¶

`set_size(size)` ¶

`set_stroke_width(width)` ¶

`set_theme(theme)` ¶

`set_value(value)` ¶