progressBar 进度条

一个可视化指示器,用于展示正在进行中任务的状态和完成情况,例如文件传输、数据加载、复杂的计算或任何其他耗时的任务。

  • XML 元素:progressBar

  • Java 类:ProgressBar

基本用法

一个标准的进度条通过 0.0 至 1.0 的值表示任务的进度从 0% 至 100%。

progress bar determinate
XML 代码
<progressBar value="0.5"/>

进度更新

进度值通常在正在进行的任务的上下文环境中更新,以便进度条能精确反映任务的当前状态。

下面的示例是一个简单的 后台任务 更新进度条的值:

XML 代码
<progressBar id="progressBar"/>
Java code
@ViewComponent
protected ProgressBar progressBar; (1)
@Autowired
protected BackgroundWorker backgroundWorker;

protected BackgroundTaskHandler<Void> taskHandler;

private static final int ITERATIONS = 6;

@Subscribe
protected void onInit(InitEvent event) {  (2)
    taskHandler = backgroundWorker.handle(createBackgroundTask());
    taskHandler.execute();
}

protected BackgroundTask<Integer, Void> createBackgroundTask () { (3)
    return new BackgroundTask<>(100, TimeUnit.SECONDS) {
        @Override
        public Void run(TaskLifeCycle<Integer> taskLifeCycle) throws Exception {
            for (int i=1; i< ITERATIONS; i++) {
                TimeUnit.SECONDS.sleep(1);
                taskLifeCycle.publish(i);
            }
            return null;
        }

        @Override
        public void progress (List<Integer> changes) {
            double lastValue = changes.get(changes.size() - 1);
            double value = lastValue/ITERATIONS;
            progressBar.setValue(value); (4)
        }
    };
}
1 在控制器中注入进度条。
2 当视图打开时,初始化一个后台任务。
3 定义一个方法创建简单的后台任务。
4 任务执行过程中,更新进度状态。

模式

进度条根据任务的不同或进度信息是否能获取可以支持 可确定非确定 两种模式。

可确定

默认情况下,progressBar可确定 的模式展示进度。可以给用户展示任务还需多少时间才能完成。

progress bar determinate
XML 代码
<progressBar id="determinateMode"/>

当任务完成时间可预计或能跟踪任务进度时,请使用可确定模式。

非确定

设置 indeterminate 属性为 true 可以将进度条改为 非确定 模式。该模式下会展示一个循环播放的进度条,而非一个特定的进度值。

XML 代码
<progressBar id="indeterminateMode" indeterminate="true"/>

当无法获取任务进度或展示一个持续运行的任务时,请使用非确定模式。

值域

默认情况下,进度条的值必须在 0.0 和 1.0 之间,分别表示 0% 和 100% 的进度。但是这两个值也可以通过 minmax 属性修改。

例如,如果任务有 10 个步骤,可以设置 min="1"max="10" 来匹配任务的进度。当任务完成 5 步时,进度值也达到了 5:

progress bar determinate
XML 代码
<progressBar min="0" max="10" value="5"/>

进度对话框

如果需要用户等待任务的完成,可以使用 后台任务对话框

backgroundtask dialog

这个对话框可以禁止用户在任务执行期间的任何交互,直到任务结束或用户取消任务。

样式版本

使用 themeNames 属性设置组件样式。

样式 描述 支持的主题

success

表示进度令人满意或接近完成。

Aura, Lumo

error

表示进度不理想,或需要用户注意停滞或失败。

Aura, Lumo

contrast

提高可见性

Aura, Lumo

XML 属性

indeterminate

启用或禁用 非确定进度 模式。

max

设置进度的最大值。默认值为 1.0

min

设置进度的最小值。默认值为 0.0

value

定义 progressBar 的值。值必须在默认的 0.01.0 或自定义的 minmax 之间。

事件和处理器

在 Jmix Studio 生成处理器桩代码时,可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 Generate Handler 添加,也可以通过 CodeGenerate 菜单(Alt+Insert / Cmd+N)生成。

参考