Skip to content

UIProgressView ​

UIProgressView 表示一条进度条:一条横线,从左边起有一段是填满的,填满的长度表示一件事完成了多少。完成的比例由 progress 属性给出,0 是还没开始,1 是全部完成。

进度条不会自己走。它显示的是 App 写进 progress 的值,App 每次得知任务前进了一步,就写一次新的值。所以它适合能数出步骤的任务:一共 10 张图片,上传完第 3 张,进度是 0.3。不知道完成了多少、只知道还在进行时,用 UIActivityIndicatorView。

进度条是视图:位置、宽度、隐藏、透明度来自 UIView。它不是控件:用户不能拖它,它也不派发事件。

本页和成员页里的数值和状态变化(高度、默认值、取值范围)是在模拟器(iPhone Air,iOS 27.2)上量的。画面上的样子(颜色、动画、图片怎么铺)未在模拟器验证。

继承关系:EventTarget → NSObject → UIResponder → UIView → UIProgressView

怎么显示一件事的进度,见指南显示加载和进度。

构造函数 ​

UIProgressView()

创建一条 'default' 样式的进度条。progress 是 0,frame 宽 0、高 4 pt。

实例属性 ​

还继承 UIView 的属性。进度条常用的继承属性是 isHidden、frame、translatesAutoresizingMaskIntoConstraints。

属性说明
progress完成的比例,0 到 1
progressViewStyle样式,决定高度
progressTintColor填满的那一段的颜色
trackTintColor没填的那一段的颜色
progressImage填满的那一段用的图片
trackImage没填的那一段用的图片

实例方法 ​

还继承 UIView 的方法。

方法说明
setProgress()改进度,可以带动画

事件 ​

进度条不派发事件。它的值只由 App 自己的代码改变。

概念 ​

高度由样式决定 ​

样式高度
'default'(默认)4 pt
'bar'小于 4 pt。3 倍屏上是 2.67 pt

进度条每次被设置 frame 或 bounds 时,都把高度改回样式决定的值:写 frame 时高度不生效,写 30 读回来还是 4,只有位置和宽度写得进去。高度约束不受这个限制,要更粗的进度条就加一条高度约束。

读继承的 intrinsicContentSize 得到的宽度是 -1,表示进度条对宽度没有要求,宽度由 frame 或约束给出。

所有尺寸的单位都是点(pt)。

颜色和图片二选一 ​

进度条的两段各有一个颜色属性和一个图片属性:

颜色图片
填满的那一段progressTintColorprogressImage
没填的那一段trackTintColortrackImage

同一段的颜色和图片只有一个有效,后写的那个生效:

  • 写图片,同一段的颜色变成 null。
  • 写颜色,同一段的图片变成 null。
  • 把颜色写成 null,图片不受影响。

两段之间互不影响。

progress 是 32 位浮点数 ​

progress 存成 32 位浮点数。写 0.3,读回来是 0.30000001192092896。0.5、0.25 这类 32 位浮点数能精确表示的值读回来不变。所以不要用 bar.progress === 0.3 判断:要比较,和 Math.fround(0.3) 比;要显示百分比,用 Math.round(bar.progress * 100)。

示例 ​

每半秒前进一格 ​

从空白 App 开始,在页面上放一条进度条,每半秒前进一格,走满后停下。

js
application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  const bar = new UIProgressView();

  const safe = page.view.safeAreaLayoutGuide;
  bar.translatesAutoresizingMaskIntoConstraints = false;
  page.view.addSubview(bar);
  NSLayoutConstraint.activateConstraints([
    bar.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 24 }),
    bar.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -24 }),
    bar.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 40 }),
  ]);

  const total = 10;
  let done = 0;
  const timer = setInterval(() => {
    done += 1;
    bar.setProgress(done / total, { animated: true });
    console.log('完成', done, '/', total);
    if (done === total) clearInterval(timer);
  }, 500);
});

效果

  • 页面上方出现一条 4 pt 高的浅色横线,左右各留 24 pt。
  • 每半秒,横线左边蓝色的那一段变长一格,控制台输出 完成 1 / 10、完成 2 / 10……
  • 五秒后整条变成蓝色,停下。

安全区是屏幕上不被刘海、圆角和底部横条遮挡的区域,见 UIView 的安全区。

这段代码没有作为一个整体在模拟器运行过。

更多写法见指南显示加载和进度。

对应的 iOS API ​

ObjCJS
[[UIProgressView alloc] init]new UIProgressView()
[[UIProgressView alloc] initWithProgressViewStyle:UIProgressViewStyleBar]const bar = new UIProgressView(); bar.progressViewStyle = 'bar';
bar.progress = 0.5fbar.progress = 0.5
[bar setProgress:0.8f animated:YES]bar.setProgress(0.8, { animated: true })
bar.progressViewStyle = UIProgressViewStyleBarbar.progressViewStyle = 'bar'
bar.progressTintColor = UIColor.systemGreenColorbar.progressTintColor = 'systemGreen'
bar.trackTintColor = nilbar.trackTintColor = null
bar.progressImage = imagebar.progressImage = image
bar.trackImage = imagebar.trackImage = image

initWithProgressViewStyle: 创建的进度条 frame 宽 160 pt,new UIProgressView() 创建的宽 0。两种写法在给了宽度之后没有区别。

参见 ​