跳到正文
册页

反馈

Progress - 进度条

一条会填充的进度条；终点未知时它来回扫。

用法

TSX
import { Progress } from '@misoto22/folio'

说明

一根会填充的条；终点未知时它会来回扫。

平的：轨道是 --stone，填充是 --ink。归白没有渐变也没有光晕，所以承载读数的只有这两者之间的那条边界。

结构

Progress anatomy
部件说明
轨道必填Radix 的根节点：4px 高的 --stone、胶囊圆角，带着 role="progressbar" 和由 label 而来的 aria-label。它默认占满宽度，所以扔进哪一栏就取哪一栏的宽度。
填充指示条，颜色是 --accent，用 width 而不是 translate 定尺寸，所以在从右到左的文档里它同样是从行首长出来的。只有 value 是数字时才存在。
扫动条value 为 null 时顶替填充的东西：一根四分之一宽的 --accent 条，只靠 transform 在轨道上走，在 rtl 下会镜像，所以它永远不会被读成进度在倒退。在 prefers-reduced-motion 下，它停在画出来的那个位置，而不是把整条轨道填满。
数值行轨道上方的一行：左边是 label，右边是等宽数字的百分比。只有设了 showValue 且 value 是数字时才渲染——这也是 label 唯一有机会被看见的地方。
竖列装着数值行和轨道的 flex 容器。className 落在这里；其余所有属性都转发给 Radix 根节点。

实践建议

推荐

  • 任何确定进度的条都要传 showValue。它是唯一能把 label 放上屏幕的东西——不传的话，这个名字就只以 aria-label 的形式存在，看得见的读者面前只剩一条没有名字、也没有数字的 4px 细线。
  • 估算一旦不再作数，就立刻把 value 切回 null。填充的宽度是按 --duration-slow 过渡的，所以一个往回修的数字会倒着动一遍，读者眼睁睁看着进度自己往回退。
  • max 要设成真实的总数，不要自己先换算成百分比。宽度和 aria-valuemax 取自同一个数字，所以画出来的和播报出来的不会各走各的——但超过上限的值照样会被夹住，一个估少了的总数，会让这条进度在剩下的整段操作里停在满格，而不是承认估错了。

避免

  • 不要传一个不是正数的 max。Radix 会拒收它，打印自己的警告，回退到 100，宽度也跟着一起回退——于是 value={40} 画出来、也播报出来的，是一个没有人选定的上限的百分之四十。
  • 不要把停住的扫动条读成一个位置。在 prefers-reduced-motion 下，它停在轨道的四分之一处，而那正是一条停在 25% 的确定进度条的样子——把两者分开的只有播报，这也正是不传 value 之所以要紧的原因。
  • className 作用在竖列上，不是轨道上，所以这样传进来的高度工具类只是把外层容器撑高，那条 4px 的进度条还在原地一动不动。

示例

determinate

一条带着真实分数的进度条，名字就在屏幕上。showValue 是唯一会把 label 印出来的东西：没有它，那个名字只以 aria-label 的形式存在，而看得见的读者面对的是一条 4px 的、没有标签的线，连数字都没有。value 是一个百分比，别的什么都不是——这个组件会静悄悄地把它夹在 0 和 100 之间，所以一个被低估了的总量，会让进度条在剩下的整个过程里停在 100%，而不是承认那个估计错了。className 修饰的是那一列、不是轨道，所以往那儿传一个高度工具类，会把外层容器撑高，而那条 4px 的进度条原地不动。

Uploading photos62%

indeterminate

没有 value，于是进度条来回扫而不是填充，aria-valuenow 也会被丢掉——读屏软件被告知的是「不确定」，而不是一个猜出来的数字。那一行数值只有在 value 是数字时才渲染，所以来回扫的进度条什么都不会印出来，名字必须用别的方式出现在页面上，就像这里。别让这样一条永远挂着：在 prefers-reduced-motion 下，那次扫动会停成一条 40% 不透明度的满宽横条，而那正是一条已经走完的进度条的样子，于是一个要求减少动效的读者，看到的是一个在说「已经完成」的东西。

Rebuilding the search index

Started 40 seconds ago. No estimate yet.

bytes into percent

数量属于调用方，百分比属于进度条。在调用处相除，并且取整——印出来的数字是取过整的，但 aria-valuenow 是你传进来的那个数，所以一次没取整的除法会播报出十五位小数——再把真实的数字留在下面那一行，让读者能读到。没有任何办法把一个总量交给这个组件：无论旁边还传了什么，value 都会被夹到 100，所以一条被告知总量是 500 的进度条，会把自己画满，并播报「五百分之一百」，而按读屏软件唯一能读到的东西算，那是百分之二十。估计一旦不再真实，立刻把 value 切回 null：填充部分的宽度是带过渡的，所以一个往回修正的数字会倒着动画，读者会眼看着进度自己撤回去。

Uploading footage.mov62%

18.2 MB of 29.4 MB

无障碍

  • 不传 value 会去掉 aria-valuenow，读屏听到的是“不确定”，而不是一个猜出来的数字。
  • label 必填——一条没有名字的进度条什么也没说。
  • 宽度是由 value 和 max 算出来的，正是 Radix 播报成 aria-valuenow 和 aria-valuemax 的那一对，所以画出来的和说出来的不可能对不上。

相关组件

Spinner