Mesop progress_bar 组件完全指南基于 Angular Material 的进度条实战【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop导读mesop.progress_bar是 MesopRapidly build AI apps in Python内置的原生组件之一用于向用户直观地展示某个操作正在进行中其底层基于成熟的 Angular Material progress bar 组件 为骨架结合仓库内的 Python 封装源码、protobuf 定义、Angular 模板与端到端测试系统讲解progress_bar的全部参数、四种模式determinate / indeterminate / buffer / query的适用场景、动画结束事件回调并给出可直接复制运行的完整示例帮助你准确地把进度反馈嵌入到 AI 推理、文件上传、数据加载等长耗时任务中。Overviewprogress_bar 是什么进度条Progress Bar用于指示某事正在进行中是反馈型 UI 组件的核心成员。在 Mesop 中progress_bar是对 Angular Materialmat-progress-bar的 Python 化封装所有属性通过 protobuf 从 Python 序列化传输到前端 Angular 组件渲染因此你可以像调用普通 Python 函数一样在页面里声明进度条无需编写任何 JavaScript。import mesop as me me.page(path/progress_bar) def app(): me.progress_bar(modeindeterminate)从源码结构看该组件的前后端分工如下Python 侧封装入口mesop/components/progress_bar/progress_bar.py通过register_native_component注册负责把参数写入ProgressBarTypeprotobuf 并调用insert_component插入组件树跨语言数据契约mesop/components/progress_bar/progress_bar.proto定义了color、value、buffer_value、mode以及动画结束事件处理器 ID 五个字段前端渲染实现mesop/components/progress_bar/progress_bar.ts 与 progress_bar.ng.html把 protobuf 配置直接绑定到mat-progress-bar指令上。完整示例最简用法官方文档的示例位于 demo/progress_bar.py这也是 Mesop 官方演示站点中progress_bardemo 的源码import mesop as me def load(e: me.LoadEvent): me.set_theme_mode(system) me.page( on_loadload, security_policyme.SecurityPolicy( allowed_iframe_parents[https://mesop-dev.github.io] ), path/progress_bar, ) def app(): with me.box(styleme.Style(marginme.Margin.all(15))): me.text(Default progress bar, typeheadline-5) me.progress_bar()要点解读me.set_theme_mode(system)在页面加载时把主题模式设为跟随系统进度条的颜色主题primary / accent / warn会随主题切换security_policy.allowed_iframe_parents允许该页面被嵌入官方演示站点 iframe不传任何参数直接调用me.progress_bar()即为默认用法——此时mode默认是indeterminate显示一条循环流动的动画进度条非常适合表示任务进行中但无法预估进度。组件同样被收录进组件索引mesop/components/index.md 对应代码位于 mesop/components/init.py通过from mesop.components.progress_bar.progress_bar import progress_bar对外导出因此你可以直接用me.progress_bar(...)调用。API 详解函数签名与全部参数progress_bar的函数签名定义于 mesop/components/progress_bar/progress_bar.py如下def progress_bar( *, key: str | None None, color: Literal[primary, accent, warn] | None None, value: float 0, buffer_value: float 0, mode: Literal[ determinate, indeterminate, buffer, query ] indeterminate, on_animation_end: Callable[[ProgressBarAnimationEndEvent], Any] | None None, ):参数类型默认值说明keystr \| NoneNone组件的 key用于在事件回调中标识是哪个组件触发了事件colorprimary \| accent \| warn \| NoneNone进度条的主题调色板颜色取值为 Angular Material 主题色之一valuefloat0进度条的当前值默认 0会被镜像到aria-valuenow无障碍属性buffer_valuefloat0进度条的缓冲值默认 0仅buffer模式生效modedeterminate \| indeterminate \| buffer \| queryindeterminate进度条模式源码 docstring 中写为defaults to determinate但函数签名实际默认值为indeterminate以签名实现为准会镜像到 DOM 的mode属性on_animation_endCallable[[ProgressBarAnimationEndEvent], Any] \| NoneNone主进度条动画结束时触发的事件不会在禁用动画、以及indeterminate/query这类连续动画模式下触发各参数的底层映射从 progress_bar.proto 可以看到Python 参数被一对一写入 protobuf 字段message ProgressBarType { optional string color 1; optional double value 2; optional double buffer_value 3; optional string mode 4; optional string on_progress_bar_animation_end_event_handler_id 5; }而在 Angular 模板 progress_bar.ng.html 中这些字段被直接绑定到 Material 指令mat-progress-bar [color]config().getColor() [value]config().getValue() [bufferValue]config().getBufferValue() [mode]getMode() (animationEnd)onProgressBarAnimationEndEvent($event) /mat-progress-bar因此你设置color、value、buffer_value、mode后最终渲染的就是标准的mat-progress-bar视觉表现、无障碍支持与 Material Design 规范完全一致。四种模式mode的选择与实战mode是进度条最重要的参数决定了进度条的表达语义。根据函数签名中的Literal约束与前端getMode()的类型定义progress_bar.ts共四种取值determinate —— 确定进度进度值可精确计算如已处理 3/10 个文件时使用。配合value0100显示实心填充条me.progress_bar(modedeterminate, value70)indeterminate —— 不确定进度默认无法预估完成时间时使用例如大模型推理、请求等待。默认模式即为此显示连续循环动画不需要也不理会valueme.progress_bar() # 等价于 me.progress_bar(modeindeterminate)端到端测试 mesop/components/progress_bar/e2e/progress_bar_app.py 正是用me.progress_bar(modeindeterminate)来验证组件的冒烟渲染me.page(path/components/progress_bar/e2e/progress_bar_app) def app(): me.text(textHello, world!) me.progress_bar(modeindeterminate)对应测试 progress_bar_test.ts 使用 Playwright 访问该页面并断言文本渲染成功。buffer —— 缓冲进度适合已知目标进度、同时展示缓冲如已下载缓冲进度的场景例如流式播放、渐进式加载。需要同时指定value与buffer_valueme.progress_bar(modebuffer, value40, buffer_value80)query —— 查询进度进度未知且处于加载/查询中状态的连续动画变体常用于初始加载前奏me.progress_bar(modequery)事件回调on_animation_endprogress_bar支持在进度动画结束时触发 Python 事件回调。事件类型为ProgressBarAnimationEndEvent定义于 progress_bar.pydataclass(kw_onlyTrue) class ProgressBarAnimationEndEvent(MesopEvent): Event emitted when the animation of the progress bar ends. Attributes: value: The value of the progress bar when the animation ends. key (str): Key of the component that emitted this event. value: float用法示例——进度走到 100% 后自动提示import mesop as me def on_anim_end(e: me.ProgressBarAnimationEndEvent): print(f进度动画结束当前值: {e.value}) me.page(path/progress_bar_event) def app(): me.progress_bar( keypb, modedeterminate, value100, on_animation_endon_anim_end, )底层事件链路Python 侧通过register_event_handler(on_animation_end, eventProgressBarAnimationEndEvent)注册处理器并把生成的 handler ID 写入 protobuf 字段on_progress_bar_animation_end_event_handler_id前端在(animationEnd)事件触发时由 progress_bar.ts 构造UserEvent把event.value通过setDoubleValue传入同时带上 handler ID 与组件key经Channel.dispatch回传到 Python 服务端服务端通过register_event_mapper注册的映射函数progress_bar.py把event.double_value还原为ProgressBarAnimationEndEvent.value字段并携带组件key调用你的回调函数。使用注意源码 docstring 明确说明禁用动画时不会触发该事件indeterminate与query模式属于连续动画不会触发该事件因此on_animation_end通常配合determinate或buffer模式使用用于在进度到达终点后执行后续逻辑例如收起进度条、跳转页面。结合 State 实现真实进度更新progress_bar最典型的实战场景是把耗时任务的进度写入me.state在轮询或任务回调中更新value从而让前端进度条实时推进。以下示例演示了带状态的 determinate 进度条import mesop as me me.stateclass class State: progress: float 0.0 done: bool False me.page(path/progress_state) def app(): state me.state(State) me.progress_bar( modedeterminate, valuestate.progress, coloraccent, on_animation_endlambda e: setattr(state, done, True), ) me.text(f进度: {state.progress:.0f}%) if state.done: me.text(处理完成)当任务完成时更新state.progress 100进度条即平滑填充至终点并触发on_animation_end。若任务存在已处理 预加载两段进度改用modebuffer并同时维护value与buffer_value即可。小结me.progress_bar()是 Mesop 对 Angular Material 进度条的原生 Python 封装零 JS 成本即可使用默认indeterminate模式适合进度未知determinatevalue适合精确进度buffer适合带缓冲进度query适合查询加载前奏颜色通过color在primary/accent/warn主题色间切换value自动镜像到aria-valuenow无障碍开箱即用on_animation_end仅在determinate/buffer等非连续动画模式下于动画结束时触发回调中可通过e.value拿到结束时的进度值、通过e.key区分多实例完整参考官方文档 docs/components/progress-bar.md、Python 实现 mesop/components/progress_bar/progress_bar.py、protobuf 定义 progress_bar.proto、前端模板 progress_bar.ng.html 与演示源码 demo/progress_bar.py。【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考