PlProgressBox

불이 들어오는 작은 유리판들의 줄입니다. 세 번째 모양이고, 양이 아니라 재질에 대한 모양입니다.

React

import { PlProgressBox } from 'plass-ui';

<PlProgressBox label="Step 3 of 5" value={3} max={5} count={5} showValue />;

import 'package:plass_ui/plass_ui.dart';

PlProgressBox(label: const Text('Step 3 of 5'), value: 3, max: 5, count: 5, showValue: true);

Props

Prop	타입	기본값	설명
value	number | null	null	min과 max 사이의 진행도. null은 indeterminate — 뭔가 진행 중이고 얼마나 남았는지는 아무도 모르는 경우입니다
min	number	0	범위의 아래끝
max	number	100	범위의 위끝
label	ReactNode	—	무엇이 진행 중인지. 값과 함께 스크린리더가 읽습니다
showValue	boolean	false	값을 글자로 함께 보여 줍니다. format이 없으면 범위에 대한 백분율입니다
format	Intl.NumberFormatOptions	—	값을 어떻게 쓸지. Intl.NumberFormat 옵션이라 바이트나 통화도 그대로 됩니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	플레이트 하나의 크기
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 채워지는 쪽의 그러데이션이 됩니다
count	number	4	플레이트 몇 장으로 만들지. 기다리는 대상에 진짜로 단계가 있다면 그 수를 주세요

Prop	타입	기본값	설명
value	double?	null	min과 max 사이의 진행도. null은 indeterminate — 뭔가 진행 중이고 얼마나 남았는지는 아무도 모르는 경우입니다
min	double	0	범위의 아래끝
max	double	100	범위의 위끝
count	int	4	플레이트 몇 장으로 만들지. 기다리는 대상에 진짜로 단계가 있다면 그 수를 주세요
label	Widget?	—	무엇이 진행 중인지. 값과 함께 스크린리더가 읽습니다
showValue	bool	false	값을 글자로 함께 보여 줍니다. format이 없으면 범위에 대한 백분율입니다
formatValue	String Function(double value)?	—	값을 어떻게 쓸지. React의 format 옵션 객체 대신 함수를 받습니다 — 프레임워크에 Intl.NumberFormat이 없고, 그것 때문에 package:intl을 끌어오는 건 소비자 대신 의존성을 정하는 일이기 때문입니다
size공통	PlassSize	PlassSize.md	플레이트 하나의 크기
color공통	PlassColor	PlassColor.primary	의미론적 색 역할. 채워지는 쪽의 그러데이션이 됩니다

count 위쪽은 전부 PlProgressLinear의 표 그대로입니다. size가 재는 대상만 다릅니다. 홈의 두께가 아니라 플레이트 한 장의 크기입니다.

나머지 <div> 속성은 그대로 통과합니다. color는 위 표의 color와 겹쳐서, children은 플레이트 줄이 아무것도 담지 않아서 제외했습니다.

React가 옵션 객체를 받는 자리에서 formatValue는 함수를 받습니다. 이유는 PlProgressLinear에 있습니다.

언제 쓰나

바와 링은 둘 다 얼마나 끝났는가 에 답합니다. 플레이트 줄은 지금 돌아가고 있다 에 답하는데, 그것도 이 라이브러리 자신의 어휘로(같은 홈, 같은 모서리, 같은 그러데이션으로) 답합니다. 그래서 Plass 표면 안쪽 의 로딩 상태에 맞습니다. 거기에 낯선 회색 스피너를 두면 빌려 온 것처럼 보입니다.

단계로도 읽히는 유일한 모양이기도 합니다. 기다리는 대상에 실제로 단계가 있다면 count를 그 수로 두세요. 줄이 측정이 아니라 진행 순서 가 됩니다.

Examples

value와 count

플레이트는 순서대로 차오르고 맨 앞 한 장은 부분적으로 찹니다. 그래서 플레이트 넷의 30%는 1/4로 반올림된 것이 아니라 한 장이 가득 차고 다음 장이 1/5쯤 찬 모습입니다. 플레이트 하나하나가 자기 홈인 이유가 이것입니다. 그렇지 않으면 플레이트 넷은 0, 25, 50, 75, 100밖에 보여 줄 수 없습니다.

React

import { PlProgressBox } from 'plass-ui';

export default function ProgressBoxCount() {
  return (
    <div className="flex flex-col items-start gap-6">
      <PlProgressBox label="Four plates, 30%" value={30} showValue />
      <PlProgressBox label="Five steps, on the third" value={3} max={5} count={5} showValue />
      <PlProgressBox label="Twelve plates" value={30} count={12} showValue />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ProgressBoxCount extends StatelessWidget {
  const ProgressBoxCount({super.key});

  @override
  Widget build(BuildContext context) {
    return const Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 24,
      children: <Widget>[
        PlProgressBox(label: Text('Four plates, 30%'), value: 30, showValue: true),
        PlProgressBox(
          label: Text('Five steps, on the third'),
          value: 3,
          max: 5,
          count: 5,
          showValue: true,
        ),
        PlProgressBox(label: Text('Twelve plates'), value: 30, count: 12, showValue: true),
      ],
    );
  }
}

Indeterminate

기본값인 null은 줄을 순환시키고, 각 플레이트는 자기 index만큼 늦게 켜집니다. 순환하는 것은 fill의 opacity이고 절대 칠 자체가 아닙니다. Plass의 fill은 그러데이션이고 background-image는 그러데이션과 없음 사이를 보간하지 못하므로, background를 바꾸는 플레이트는 켜지는 것이 아니라 튑니다.

플레이트는 움직이지 않습니다. 플레이트 줄은 누군가 읽고 있는 페이지 구석에서 뛰는 무언가가 아니라, 무언가 기록되고 있는 표면으로 읽힙니다.

React

import { PlProgressBox } from 'plass-ui';

export default function ProgressBoxIndeterminate() {
  return (
    <div className="flex flex-col items-start gap-6">
      <PlProgressBox label="Known" value={45} showValue />
      <PlProgressBox label="Unknown" />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ProgressBoxIndeterminate extends StatelessWidget {
  const ProgressBoxIndeterminate({super.key});

  @override
  Widget build(BuildContext context) {
    return const Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 24,
      children: <Widget>[
        PlProgressBox(label: Text('Known'), value: 45, showValue: true),
        PlProgressBox(label: Text('Unknown')),
      ],
    );
  }
}

size

플레이트 자신의 사다리이고, PlCheckbox의 박스와 PlRadio의 링이 올라 있는 tick 사다리입니다. 플레이트는 라벨 옆의 표시이지 라벨을 안에 넣을 수 있는 컨트롤이 아닙니다.

React

import { PlProgressBox } from 'plass-ui';

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function ProgressBoxSizes() {
  return (
    <div className="flex flex-col items-start gap-5">
      {sizes.map((size) => (
        <PlProgressBox key={size} size={size} label={size} value={60} />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ProgressBoxSizes extends StatelessWidget {
  const ProgressBoxSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 20,
      children: <Widget>[
        for (final PlassSize size in PlassSize.values)
          PlProgressBox(size: size, label: Text(size.name), value: 60),
      ],
    );
  }
}

color

React

import { PlProgressBox } from 'plass-ui';

const colors = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function ProgressBoxColors() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {colors.map((color) => (
        <PlProgressBox key={color} color={color} label={color} value={65} />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ProgressBoxColors extends StatelessWidget {
  const ProgressBoxColors({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 24,
      runSpacing: 16,
      children: <Widget>[
        for (final PlassColor color in PlassColor.values)
          PlProgressBox(color: color, label: Text(color.name), value: 65),
      ],
    );
  }
}

Accessibility

• Base UI가 role="progressbar"를 렌더링하고 aria-valuenow aria-valuemin aria-valuemax를 prop과 맞춰 둡니다. 플레이트 자체는 aria-hidden입니다. 그건 그림이기 때문입니다.
• indeterminate인 줄은 0이 아니라 값 자체를 보고하지 않습니다. 그래야 스크린리더가 진행도를 알 수 없다고 읽어 줍니다.
• aria-valuetext는 showValue가 그리는 문자열과 같습니다. format이 없으면 100이 아니라 범위에 대한 백분율이고, 플레이트 다섯 장이 보통 max={5}를 뜻하는 여기서 그것이 가장 중요합니다.
• prefers-reduced-motion에서는 파도를 멈추는 대신 움직임으로 읽히지 않을 만큼 느리게 합니다. 가만히 있는 플레이트 줄은 작업이 멈췄다고 말합니다.

• 줄은 SemanticsRole.progressBar와 값을 지닌 하나의 병합된 semantics 노드입니다. 라벨과 플레이트가 함께 읽히고, 플레이트 자체는 아무것도 더하지 않습니다. 그건 그림이기 때문입니다.
• 값이 없으면 role은 SemanticsRole.loadingSpinner이고 값 자체가 없습니다. 그래야 플랫폼이 진행도를 알 수 없다고 읽어 줍니다.
• 그려진 백분율은 ExcludeSemantics 뒤에 있습니다. 같은 문자열이 이미 노드의 값입니다.
• MediaQuery.disableAnimations에서는 파도를 멈추는 대신 느리게 합니다.

React 빌드와 다른 점

React	Flutter	이유
format: Intl.NumberFormatOptions	formatValue: String Function(double)	프레임워크에 Intl.NumberFormat이 없고, 그것을 위해 package:intl을 끌어오는 것은 소비자 대신 의존성을 정하는 일입니다.
소수 count를 내림	count가 int	Dart의 타입이 이미 그렇게 알립니다. 1 미만이 1이 되는 것은 그대로입니다.
파도가 플레이트마다 자기 delay가 붙은 keyframe	컨트롤러 하나를 플레이트들이 각자의 위상으로 읽음	같은 파도이고, 플레이트마다 하나가 아니라 줄마다 ticker 하나입니다.
className, style, 네이티브 속성	—	통과시킬 class 목록도 style 속성도 없습니다.