PlGaugeChart

미리 알려진 척도 위의 숫자 하나를 다이얼로 그립니다. 호로 굽힌 PlMeter이며, 여러 필드가 늘어선 줄이 아니라 타일 하나를 위한 물건입니다.

React

import { PlGaugeChart } from 'plass-ui';

<PlGaugeChart value={68} caption="of quota" />;

import 'package:plass_ui/plass_ui.dart';

PlGaugeChart(value: 68, caption: Text('of quota'));

value, min, max, thresholds는 meter에서와 똑같은 뜻입니다. 그래서 다루는 내용을 바꾸지 않고도 값을 막대에서 다이얼로 옮길 수 있습니다. 필드가 늘어선 줄에는 막대를, 방 건너편에서도 한눈에 읽혀야 하는 자리에는 이쪽을 쓰세요. 4px 막대는 그러지 못합니다.

shape="semi"인 파이 차트가 아닙니다. 파이는 전체의 부분이고 조각마다 category입니다. 이것은 척도에 대고 잰 값 하나이며, 채워지지 않은 호는 두 번째 category가 아니라 다이얼의 나머지입니다.

Props

Prop	타입	기본값	설명
value *	number | null	—	값. null은 아무것도 얹지 않은 다이얼을 그립니다
min	number	0	척도의 아래끝
max	number	100	척도의 위끝
sweep	number	180	다이얼이 도는 각도. 열두 시를 기준으로 좌우 대칭으로 열립니다
thickness	number	0.22	반지름에 대한 호의 두께 비율
thresholds	readonly PlassThreshold[]	—	호의 색이 바뀌는 band. PlMeter와 같은 규칙으로, 값 이하에서 가장 높은 band가 이깁니다
ticks	number | false	false	테두리에 그릴 눈금 수. 양 끝 포함
showRange	boolean	true	호의 양 끝에 min과 max를 적습니다. 330°를 넘으면 값과 무관하게 빠집니다
center	ReactNode	—	구멍 속에 들어가는 것. 비우면 format을 거친 값입니다
caption	ReactNode	—	값 아래 한 줄. 단위나 재고 있는 대상
height	number | string	—	그림의 높이
format	Intl.NumberFormatOptions	—	값을 쓰는 방식
label	string	—	다이얼의 이름. 없으면 평범한 상자로 남습니다
empty	ReactNode	—	그릴 것이 없을 때 그리는 것
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	threshold가 걸리지 않을 때 호가 입는 계열
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	타입 스케일과 다이얼 높이

Prop	타입	기본값	설명
value *	double?	—	값. null은 아무것도 얹지 않은 다이얼을 그립니다
min	double	0	척도의 아래끝
max	double	100	척도의 위끝
sweep	double	180	다이얼이 도는 각도. 열두 시를 기준으로 좌우 대칭으로 열립니다
thickness	double	0.22	반지름에 대한 호의 두께 비율
thresholds	List<PlassThreshold>?	—	호의 색이 바뀌는 band. PlMeter와 같은 규칙으로, 값 이하에서 가장 높은 band가 이깁니다
ticks	int?	false	테두리에 그릴 눈금 수. React의 number | false 대신 null이 '없음'입니다
showRange	bool	true	호의 양 끝에 min과 max를 적습니다. 330°를 넘으면 값과 무관하게 빠집니다
center	Widget?	—	구멍 속에 들어가는 것. 비우면 format을 거친 값입니다
caption	Widget?	—	값 아래 한 줄. 단위나 재고 있는 대상
height	double?	—	그림의 높이
format	String Function(double)?	—	값을 쓰는 방식
semanticLabel	String?	—	다이얼의 이름. 없으면 평범한 상자로 남습니다
empty	Widget?	—	그릴 것이 없을 때 그리는 것
color공통	PlassColor	PlassColor.primary	threshold가 걸리지 않을 때 호가 입는 계열
size공통	PlassSize	PlassSize.md	타입 스케일과 다이얼 높이

value가 null이면 아무것도 얹지 않은 다이얼을 그립니다. 아무 말도 듣지 못한 계기의 정직한 모습입니다. legend도 tooltip도 없습니다. 숫자 하나에는 둘 다 필요 없습니다.

라이브러리 전체에서 공유 prop이 뜻하는 바는 prop 규약에 있습니다.

Examples

sweep

React

import { PlGaugeChart } from 'plass-ui';

export default function GaugeChartSweep() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      {[180, 270, 360].map((sweep) => (
        <PlGaugeChart
          key={sweep}
          label={`Load at ${sweep} degrees`}
          value={62}
          sweep={sweep}
          height={160}
          caption={`${sweep}°`}
        />
      ))}
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return Row(
      children: <Widget>[
        for (final double sweep in <double>[180, 270, 360])
          Expanded(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 6),
              child: PlGaugeChart(
                value: 62,
                sweep: sweep,
                height: 160,
                caption: Text('${sweep.toInt()}°'),
                semanticLabel: 'Load at ${sweep.toInt()} degrees',
              ),
            ),
          ),
      ],
    );
  }
}

열두 시를 기준으로 좌우 대칭으로 열리는 각도입니다. 180은 대시보드 타일이 원하는 반달, 270은 계기 모양, 360은 고리입니다.

다이얼은 원이라고 가정하지 않고 상자에 맞춰 잽니다. 중심 아래로 얼마나 내려가는지가 sweep에 따라 다르기 때문입니다. 반달은 중심 높이에서 멈추고 270°는 반지름의 대부분만큼 더 내려갑니다. 넓고 낮은 카드가 위쪽 절반을 비운 채 가느다란 띠만 그리는 일을 막는 것이 이 계산입니다.

thresholds

React

import { PlGaugeChart } from 'plass-ui';

const bands = [
  { from: 70, color: 'warning' as const },
  { from: 90, color: 'danger' as const }
];

export default function GaugeChartThresholds() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      {[42, 78, 96].map((value) => (
        <PlGaugeChart
          key={value}
          label={`Disk at ${value} percent`}
          value={value}
          thresholds={bands}
          height={160}
          caption="disk"
        />
      ))}
    </div>
  );
}

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

const List<PlassThreshold> _bands = <PlassThreshold>[
  PlassThreshold(from: 70, color: PlassColor.warning),
  PlassThreshold(from: 90, color: PlassColor.danger),
];

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

  @override
  Widget build(BuildContext context) {
    return Row(
      children: <Widget>[
        for (final double value in <double>[42, 78, 96])
          Expanded(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 6),
              child: PlGaugeChart(
                value: value,
                thresholds: _bands,
                height: 160,
                caption: const Text('disk'),
                semanticLabel: 'Disk at ${value.toInt()} percent',
              ),
            ),
          ),
      ],
    );
  }
}

값 이하에서 가장 높은 band가 이깁니다. 모든 band 아래라면 color가 그대로 남습니다. 목록의 순서는 상관없습니다. band는 훑는 것이 아니라 읽는 것이고, 이는 PlMeter가 쓰는 것과 같은 규칙이자 같은 코드입니다.

band는 숫자를 보여 주는 두 번째 방법일 뿐 유일한 방법이 아닙니다. 호가 어떤 색을 입든 값은 가운데에 적힙니다.

ticks와 showRange

React

import { PlGaugeChart } from 'plass-ui';

export default function GaugeChartTicks() {
  return (
    <PlGaugeChart
      className="w-full max-w-xs"
      label="Line pressure"
      value={4.2}
      min={0}
      max={6}
      sweep={270}
      ticks={7}
      caption="bar"
      format={{ maximumFractionDigits: 1 }}
    />
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      height: 220,
      child: PlGaugeChart(
        value: 4.2,
        max: 6,
        sweep: 270,
        ticks: 7,
        caption: const Text('bar'),
        semanticLabel: 'Line pressure',
        format: (double value) => value.toStringAsFixed(1),
      ),
    );
  }
}

눈금은 기본으로 꺼져 있습니다. 대시보드의 게이지는 비율로 읽히고, 테두리의 눈금은 거기서 숫자를 읽어 가는 계기를 위한 것입니다.

showRange는 호의 양 끝에 min과 max를 적습니다. 330°를 넘으면 값과 무관하게 빠집니다. 그쯤이면 두 끝이 label 하나 너비 안으로 다가와, 0과 100이 겹쳐 찍힌 것은 척도가 아니라 얼룩이기 때문입니다.

center와 caption

center는 구멍 속의 숫자를 대신하고, caption은 그 아래에 한 줄을 겁니다. 값을 대신하는 것은 더하기 위한 것이지 빼기 위한 것이 아닙니다. 숫자가 다이얼의 존재 이유이기 때문입니다.

값은 그림에 그려 넣은 label이 아니라 진짜 텍스트입니다. 그래서 선택할 수 있고, 브라우저 검색에 걸리며, 차트가 스스로를 설명하지 않아도 읽힙니다. 크기는 고정이 아니라 구멍이 실제로 남긴 공간에 대고 풀어냅니다. 38과 10,000%가 같은 prop이기 때문입니다.

Accessibility

• label이 있으면 다이얼은 한 가지를 알리는 이름 붙은 이미지 하나가 됩니다. "Storage used: 1.36 / 2"와 같은 형태입니다. 양 끝 label이 떠도는 숫자로 들리는 일을 막아 줍니다.
• 없으면 평범한 상자로 남고, 가운데 값은 이미 텍스트이므로 그대로 읽힙니다.
• 값이 색만으로 전달되는 일은 없습니다. threshold는 계열을 바꾸고, 가운데 숫자가 같은 말을 글로 합니다.
• 호는 새 값으로 튀지 않고 쓸어 갑니다. 그 움직임은 transform이 아니라 길이라서, 다이얼 위에 적힌 숫자가 다시 샘플링되는 일이 없습니다.