尧图网页设计 
Textual ProgressBar 组件完全指南状态机、渐变与样式定制【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textualProgressBar 是 Textual 框架当前仓库中用于展示耗时任务进度的核心组件以“步数steps”为计量单位通过total、progress与percentage三个响应式属性驱动并原生支持不确定态动画、ETA 倒计时与渐变渲染。读完本文你将掌握如何在实际 App 中创建、驱动、自定义 ProgressBar理解其子组件结构与底层响应式实现并能基于源码级证据排查与扩展进度条行为。组件概览不可聚焦、非容器ProgressBar 是一个展示型组件文档明确标注不可聚焦Focusable否非容器Container否这意味着它不参与键盘焦点管理也不能直接挂载子组件其职责被严格限定为“可视化展示进度”。从源码看ProgressBar 类 的类声明为class ProgressBar(Widget, can_focusFalse)构造器默认参数包括show_barTrue、show_percentageTrue、show_etaTrue它通过内部compose()组合出三个子组件这部分在“子组件结构”小节详述。示例实战从隔离组件到完整 App隔离演示三种核心状态文档提供了一个“在隔离环境中的进度条”示例覆盖 ProgressBar 的三种典型形态不确定态Indeterminate尚未设置total时进度条显示为来回滚动的滑块动画进行中total已设置、进度处于中间值如 39%完成态progress达到或超过total百分比显示 100%。演示脚本 progress_bar_isolated_.py 使用MockClock冻结时间流按下f、t、u三个键分别冻结不确定态动画、固定 39% 进度和推进到 100% 完成态便于反复观察不同渲染状态。而真正可运行的隔离示例是 progress_bar_isolated.py它先yield ProgressBar()此时total为None处于不确定态App 启动后通过set_interval(1 / 10, ...)每 0.1 秒调用一次make_progress模拟“进度正在发生”的过程按下s键触发action_start调用update(total100)将进度条切换为确定态并恢复计时器开始累加进度。这是理解“不确定态 ↔ 确定态”切换的最简范例。完整 App募资进度追踪文档给出的完整示例是一个模拟组织募资的 App——用户输入金额并点击“Donate”按钮进度条随之推进。完整源码位于 progress_bar.py样式文件为 progress_bar.tcss。关键代码yield ProgressBar(total100, show_etaFalse) # (1)!创建一个total为 100 步的进度条同时隐藏 ETA 倒计时因为这里追踪的不是一段连续、不间断的任务。App 的事件处理逻辑通过query_one(ProgressBar)精确拿到进度条实例再用advance(value)把用户输入的捐赠金额作为“步数”推进进度def add_donation(self) - None: text_value self.query_one(Input).value try: value int(text_value) except ValueError: return self.query_one(ProgressBar).advance(value) self.query_one(VerticalScroll).mount(Label(fDonation for ${value} received!)) self.query_one(Input).value 对应的 progress_bar.tcss 负责布局Center容器使用水平布局并加上下外边距Input固定宽度 16ProgressBar左侧内边距 3VerticalScroll高度自适应捐赠历史记录逐条追加。渐变进度条ProgressBar 支持可选的gradient参数用平滑渐变色替代纯色填充。使用方式创建 textual.color.Gradient 对象并设置到组件上。文档特别强调设置渐变会覆盖 CSS 中定义的样式源码中gradient响应式属性的 docstring 也写明 “will replace CSS styling in bar”。示例 progress_bar_gradient.py 用 12 种颜色构建了一道“彩虹”渐变gradient Gradient.from_colors( #881177, #aa3355, #cc6666, #ee9944, #eedd00, #99dd55, #44dd88, #22ccbb, #00bbcc, #0099cc, #3366bb, #663399, ) with Center(): with Middle(): yield ProgressBar(total100, gradientgradient)App 挂载后通过update(progress70)把进度推进到 70%即可看到渐变填充效果。自定义样式示例文档提供了自定义样式版本progress_bar_styled.py 与 progress_bar_styled.tcss通过修改子组件的组件类component class实现视觉定制Bar .bar--indeterminate { color: $primary; background: $secondary; } Bar .bar--bar { color: $primary; background: $primary 30%; } Bar .bar--complete { color: $error; } PercentageStatus { text-style: reverse; color: $secondary; } ETAStatus { text-style: underline; }这里演示了三种不同的视觉状态配色以及百分比标签反色、ETA 标签下划线的文本样式定制具体可定制的组件类见下一节。子组件结构与样式体系ProgressBar 由三个可独立设置样式的子组件构成组件名ID说明Bar#bar直观表示进度的条形区域PercentageStatus#percentage显示完成百分比的 LabelETAStatus#eta显示预计完成时间的 Label从 源码 compose 逻辑 可以看到三个子组件通过data_bind与父组件的响应式属性绑定Bar绑定percentage与gradientPercentageStatus绑定percentageETAStatus绑定内部_display_eta。三个开关参数show_bar、show_percentage、show_eta分别控制是否生成对应子组件。Bar 的组件类COMPONENT_CLASSESBar子组件定义了三个组件类分别控制条形在不同状态下的前景色与背景色类名说明bar--bar条形本体样式通常用来改颜色bar--complete进度完成时条形的样式bar--indeterminate不确定态动画中条形的样式Bar的DEFAULT_CSS给出默认配色正常态前景$primary、背景$surface不确定态前景$error、背景$surface完成态前景$success、背景$surface且默认尺寸为width: 32、height: 1。值得留意的是三个子组件的渲染细节见 源码PercentageStatus默认宽度 5、右对齐percentage为None时显示--%否则显示取整后的百分比如39%ETAStatus默认宽度 9、右对齐ETA 为None时显示--:--:--超过 99 小时显示100h这类简写超过 999999 小时则显示999999hBar的渲染在percentage为None时进入render_indeterminate分支以 30 格/秒的速度计算滑块位置形成往返滚动动画当app.animation_level none时动画退化为静态全宽显示。响应式属性驱动进度的数据核心ProgressBar 的全部进度状态由三个响应式属性reactive attribute承载任一属性变化都会触发自动重渲染名称类型默认值说明percentagefloat \| None—只读的完成百分比0~1 之间的小数total未设置时为Noneprogressfloat0已经完成的步数totalfloat \| None—需要追踪的总步数为None时进度条渲染为不确定态percentage并非直接赋值而是由源码中的_compute_percentage实时推算源码def _compute_percentage(self) - float | None: if self.total: return clamp(self.progress / self.total, 0.0, 1.0) elif self.total 0: return 1.0 return None该逻辑包含两个重要边界行为total 0时百分比直接视为1.0完成避免除零total为None未设置时返回None驱动不确定态渲染。此外_validate_total会拒绝负数total被钳制到max(0, total)源码。这些行为在 tests/test_progress_bar.py 中均有覆盖验证例如test_initial_status、test_progress_overflow超出后百分比钳制为 1、test_progress_underflow回退后钳制为 0、test_non_negative_total负 total 归零。驱动进度的三种 APIupdate / advance / 直接赋值面向使用者的进度更新入口有三个均可在 源码 中看到实现# 1. 一次性推进指定步数 progress_bar.advance(10) # 前进 10 步 # 2. 批量更新可同时设置 total、progress、advance progress_bar.update( total200, # 重设总步数为 200 progress50, # 直接设定进度为 50总步数为 200 advance10, # 再额外推进 10 步 ) # 3. 直接操作响应式属性 progress_bar.total 100 progress_bar.progress 60三个入口在update方法内部汇聚直接赋值progress/total会触发_watch_progress/_watch_total并回调updateupdate与advance则会记录时间采样交给内部的ETA估算器计算剩余时间最终刷新_display_eta。一个与直觉略有出入但被测试test_update印证的行为是update(total100, progress30, advance20)执行后progress为50即progress与advance是叠加关系而非互斥覆盖。测试 tests/test_progress_bar.py 中还覆盖了advance支持小数步长advance(0.0625)、负步长回退advance(-10)、以及total置回None后重新回到不确定态test_go_back_to_indeterminate等边界场景。ETA 倒计时显示逻辑与关闭方式ProgressBar 默认显示 ETA预计完成时间但并非所有场景都适合展示它。文档中的募资示例就因“任务并非连续不间断”而关闭了 ETA。关闭方式有两个层面构造时ProgressBar(total100, show_etaFalse)不生成ETAStatus子组件CSS 层可单独为#eta定制样式例如默认样式外的自定义表现见上文的ETAStatus { text-style: underline; }。从源码看ETA 的计算基于_eta.add_sample(current_time, progress/total)采集的时间-进度样本源码并在on_mount中通过set_interval(1, self.update)每秒刷新一次。因此 ETA 的准确性依赖“持续、大致匀速”的进度推进——这正是文档建议在连续任务中才展示 ETA 的原因。消息与绑定MessagesProgressBar 不发布任何消息进度变化完全通过响应式属性驱动消费方通过读取percentage/progress或监听父容器数据绑定即可Bindings组件自身不注册任何按键绑定无绑定Component ClassesProgressBar 根组件自身没有组件类样式定制落在Bar子组件的bar--bar、bar--complete、bar--indeterminate三个类上。小结何时用、怎么用Textual 的 ProgressBar 是一支“麻雀虽小、五脏俱全”的组件用total定义任务规模用advance/update推进进度用percentage读取状态用show_eta/show_bar/show_percentage裁剪展示内容用gradient或子组件类实现视觉定制。适合下载、安装、渲染、批量处理等一切需要向用户反馈“正在发生什么、还有多久”的终端场景。若需在真实 App 中验证上述行为可直接运行 progress_bar.py 与 progress_bar_isolated.py 两个示例并结合 tests/test_progress_bar.py 了解全部边界行为。【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Textual ProgressBar 组件完全指南：状态机、渐变与样式定制
Textual ProgressBar 组件完全指南状态机、渐变与样式定制【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textualProgressBar 是 Textual 框架当前仓库中用于展示耗时任务进度的核心组件以“步数steps”为计量单位通过total、progress与percentage三个响应式属性驱动并原生支持不确定态动画、ETA 倒计时与渐变渲染。读完本文你将掌握如何在实际 App 中创建、驱动、自定义 ProgressBar理解其子组件结构与底层响应式实现并能基于源码级证据排查与扩展进度条行为。组件概览不可聚焦、非容器ProgressBar 是一个展示型组件文档明确标注不可聚焦Focusable否非容器Container否这意味着它不参与键盘焦点管理也不能直接挂载子组件其职责被严格限定为“可视化展示进度”。从源码看ProgressBar 类 的类声明为class ProgressBar(Widget, can_focusFalse)构造器默认参数包括show_barTrue、show_percentageTrue、show_etaTrue它通过内部compose()组合出三个子组件这部分在“子组件结构”小节详述。示例实战从隔离组件到完整 App隔离演示三种核心状态文档提供了一个“在隔离环境中的进度条”示例覆盖 ProgressBar 的三种典型形态不确定态Indeterminate尚未设置total时进度条显示为来回滚动的滑块动画进行中total已设置、进度处于中间值如 39%完成态progress达到或超过total百分比显示 100%。演示脚本 progress_bar_isolated_.py 使用MockClock冻结时间流按下f、t、u三个键分别冻结不确定态动画、固定 39% 进度和推进到 100% 完成态便于反复观察不同渲染状态。而真正可运行的隔离示例是 progress_bar_isolated.py它先yield ProgressBar()此时total为None处于不确定态App 启动后通过set_interval(1 / 10, ...)每 0.1 秒调用一次make_progress模拟“进度正在发生”的过程按下s键触发action_start调用update(total100)将进度条切换为确定态并恢复计时器开始累加进度。这是理解“不确定态 ↔ 确定态”切换的最简范例。完整 App募资进度追踪文档给出的完整示例是一个模拟组织募资的 App——用户输入金额并点击“Donate”按钮进度条随之推进。完整源码位于 progress_bar.py样式文件为 progress_bar.tcss。关键代码yield ProgressBar(total100, show_etaFalse) # (1)!创建一个total为 100 步的进度条同时隐藏 ETA 倒计时因为这里追踪的不是一段连续、不间断的任务。App 的事件处理逻辑通过query_one(ProgressBar)精确拿到进度条实例再用advance(value)把用户输入的捐赠金额作为“步数”推进进度def add_donation(self) - None: text_value self.query_one(Input).value try: value int(text_value) except ValueError: return self.query_one(ProgressBar).advance(value) self.query_one(VerticalScroll).mount(Label(fDonation for ${value} received!)) self.query_one(Input).value 对应的 progress_bar.tcss 负责布局Center容器使用水平布局并加上下外边距Input固定宽度 16ProgressBar左侧内边距 3VerticalScroll高度自适应捐赠历史记录逐条追加。渐变进度条ProgressBar 支持可选的gradient参数用平滑渐变色替代纯色填充。使用方式创建 textual.color.Gradient 对象并设置到组件上。文档特别强调设置渐变会覆盖 CSS 中定义的样式源码中gradient响应式属性的 docstring 也写明 “will replace CSS styling in bar”。示例 progress_bar_gradient.py 用 12 种颜色构建了一道“彩虹”渐变gradient Gradient.from_colors( #881177, #aa3355, #cc6666, #ee9944, #eedd00, #99dd55, #44dd88, #22ccbb, #00bbcc, #0099cc, #3366bb, #663399, ) with Center(): with Middle(): yield ProgressBar(total100, gradientgradient)App 挂载后通过update(progress70)把进度推进到 70%即可看到渐变填充效果。自定义样式示例文档提供了自定义样式版本progress_bar_styled.py 与 progress_bar_styled.tcss通过修改子组件的组件类component class实现视觉定制Bar .bar--indeterminate { color: $primary; background: $secondary; } Bar .bar--bar { color: $primary; background: $primary 30%; } Bar .bar--complete { color: $error; } PercentageStatus { text-style: reverse; color: $secondary; } ETAStatus { text-style: underline; }这里演示了三种不同的视觉状态配色以及百分比标签反色、ETA 标签下划线的文本样式定制具体可定制的组件类见下一节。子组件结构与样式体系ProgressBar 由三个可独立设置样式的子组件构成组件名ID说明Bar#bar直观表示进度的条形区域PercentageStatus#percentage显示完成百分比的 LabelETAStatus#eta显示预计完成时间的 Label从 源码 compose 逻辑 可以看到三个子组件通过data_bind与父组件的响应式属性绑定Bar绑定percentage与gradientPercentageStatus绑定percentageETAStatus绑定内部_display_eta。三个开关参数show_bar、show_percentage、show_eta分别控制是否生成对应子组件。Bar 的组件类COMPONENT_CLASSESBar子组件定义了三个组件类分别控制条形在不同状态下的前景色与背景色类名说明bar--bar条形本体样式通常用来改颜色bar--complete进度完成时条形的样式bar--indeterminate不确定态动画中条形的样式Bar的DEFAULT_CSS给出默认配色正常态前景$primary、背景$surface不确定态前景$error、背景$surface完成态前景$success、背景$surface且默认尺寸为width: 32、height: 1。值得留意的是三个子组件的渲染细节见 源码PercentageStatus默认宽度 5、右对齐percentage为None时显示--%否则显示取整后的百分比如39%ETAStatus默认宽度 9、右对齐ETA 为None时显示--:--:--超过 99 小时显示100h这类简写超过 999999 小时则显示999999hBar的渲染在percentage为None时进入render_indeterminate分支以 30 格/秒的速度计算滑块位置形成往返滚动动画当app.animation_level none时动画退化为静态全宽显示。响应式属性驱动进度的数据核心ProgressBar 的全部进度状态由三个响应式属性reactive attribute承载任一属性变化都会触发自动重渲染名称类型默认值说明percentagefloat \| None—只读的完成百分比0~1 之间的小数total未设置时为Noneprogressfloat0已经完成的步数totalfloat \| None—需要追踪的总步数为None时进度条渲染为不确定态percentage并非直接赋值而是由源码中的_compute_percentage实时推算源码def _compute_percentage(self) - float | None: if self.total: return clamp(self.progress / self.total, 0.0, 1.0) elif self.total 0: return 1.0 return None该逻辑包含两个重要边界行为total 0时百分比直接视为1.0完成避免除零total为None未设置时返回None驱动不确定态渲染。此外_validate_total会拒绝负数total被钳制到max(0, total)源码。这些行为在 tests/test_progress_bar.py 中均有覆盖验证例如test_initial_status、test_progress_overflow超出后百分比钳制为 1、test_progress_underflow回退后钳制为 0、test_non_negative_total负 total 归零。驱动进度的三种 APIupdate / advance / 直接赋值面向使用者的进度更新入口有三个均可在 源码 中看到实现# 1. 一次性推进指定步数 progress_bar.advance(10) # 前进 10 步 # 2. 批量更新可同时设置 total、progress、advance progress_bar.update( total200, # 重设总步数为 200 progress50, # 直接设定进度为 50总步数为 200 advance10, # 再额外推进 10 步 ) # 3. 直接操作响应式属性 progress_bar.total 100 progress_bar.progress 60三个入口在update方法内部汇聚直接赋值progress/total会触发_watch_progress/_watch_total并回调updateupdate与advance则会记录时间采样交给内部的ETA估算器计算剩余时间最终刷新_display_eta。一个与直觉略有出入但被测试test_update印证的行为是update(total100, progress30, advance20)执行后progress为50即progress与advance是叠加关系而非互斥覆盖。测试 tests/test_progress_bar.py 中还覆盖了advance支持小数步长advance(0.0625)、负步长回退advance(-10)、以及total置回None后重新回到不确定态test_go_back_to_indeterminate等边界场景。ETA 倒计时显示逻辑与关闭方式ProgressBar 默认显示 ETA预计完成时间但并非所有场景都适合展示它。文档中的募资示例就因“任务并非连续不间断”而关闭了 ETA。关闭方式有两个层面构造时ProgressBar(total100, show_etaFalse)不生成ETAStatus子组件CSS 层可单独为#eta定制样式例如默认样式外的自定义表现见上文的ETAStatus { text-style: underline; }。从源码看ETA 的计算基于_eta.add_sample(current_time, progress/total)采集的时间-进度样本源码并在on_mount中通过set_interval(1, self.update)每秒刷新一次。因此 ETA 的准确性依赖“持续、大致匀速”的进度推进——这正是文档建议在连续任务中才展示 ETA 的原因。消息与绑定MessagesProgressBar 不发布任何消息进度变化完全通过响应式属性驱动消费方通过读取percentage/progress或监听父容器数据绑定即可Bindings组件自身不注册任何按键绑定无绑定Component ClassesProgressBar 根组件自身没有组件类样式定制落在Bar子组件的bar--bar、bar--complete、bar--indeterminate三个类上。小结何时用、怎么用Textual 的 ProgressBar 是一支“麻雀虽小、五脏俱全”的组件用total定义任务规模用advance/update推进进度用percentage读取状态用show_eta/show_bar/show_percentage裁剪展示内容用gradient或子组件类实现视觉定制。适合下载、安装、渲染、批量处理等一切需要向用户反馈“正在发生什么、还有多久”的终端场景。若需在真实 App 中验证上述行为可直接运行 progress_bar.py 与 progress_bar_isolated.py 两个示例并结合 tests/test_progress_bar.py 了解全部边界行为。【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考