PlTransfer

두 목록과 그 사이의 화살표입니다. 고를 수 있는 모든 것이 한쪽에, 고른 것이 다른 쪽에 있습니다. 체크는 선택이 아닙니다. 체크는 다음 누름이 무엇을 옮길지를 말합니다.

React

import { PlTransfer } from 'plass-ui';

<PlTransfer
  items={columns}
  value={value}
  onValueChange={setValue}
  sourceLabel="Available columns"
  targetLabel="In the report"
/>;

import 'package:plass_ui/plass_ui.dart';

PlTransfer(
  items: columns,
  value: value,
  onValueChanged: (List<String> next) => setState(() => value = next),
  sourceLabel: 'Available columns',
  targetLabel: 'In the report',
);

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'glass' | 'ghost'	'glass'	두 패널의 재질. 필드와 같은 껍데기입니다 — 목록은 값을 담지, 눌리지 않습니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	체크박스, 화살표, 타입 스케일, 여백이 함께 움직입니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
items *	readonly PlTransferItem[]	—	양쪽에 있을 수 있는 모든 것. 두 목록이 보여 주는 순서이기도 합니다
value	readonly string[]	—	뒤쪽에 있는 것. onValueChange와 함께 controlled로 씁니다
defaultValue	readonly string[]	—	뒤쪽에서 시작하는 것
onValueChange	(value: string[]) => void	—	뭔가 건너갔거나 돌아왔을 때
sourceLabel	ReactNode	'Available'	앞쪽 목록 위의 제목
targetLabel	ReactNode	'Selected'	뒤쪽 목록 위의 제목
searchable	boolean	false	각 목록 위에 필터를 둡니다
searchLabel	string	'Search'	그 필터가 비어 있을 때 말하는 내용
emptyLabel	string	'Nothing here'	아무것도 없는 목록이 말하는 내용
selectAllLabel	string	'Select all'	목록 제목의 체크박스가 불리는 이름
toTargetLabel	string	'Move to selected'	건너가는 화살표가 불리는 이름
toSourceLabel	string	'Move to available'	돌아오는 화살표가 불리는 이름
height	number | string	220	각 목록의 높이. 픽셀 수 또는 CSS 길이
disabled	boolean	false	아무것도 체크하거나 옮길 수 없습니다

Prop	타입	기본값	설명
variant공통	PlassVariant	PlassVariant.glass	두 패널의 재질. 필드와 같은 껍데기입니다 — 목록은 값을 담지, 눌리지 않습니다
size공통	PlassSize	PlassSize.md	체크박스, 화살표, 타입 스케일, 여백이 함께 움직입니다
color공통	PlassColor	PlassColor.primary	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	PlassDensity	PlassDensity.standard	여백만 바꿉니다. 높이와 글자 크기는 그대로
items *	List<PlTransferItem>	—	양쪽에 있을 수 있는 모든 것. 두 목록이 보여 주는 순서이기도 합니다
value	List<String>?	—	뒤쪽에 있는 것. onValueChange와 함께 controlled로 씁니다
defaultValue	List<String>	<String>[]	뒤쪽에서 시작하는 것
onValueChanged	ValueChanged<List<String>>?	—	뭔가 건너갔거나 돌아왔을 때
sourceLabel	String	'Available'	앞쪽 목록 위의 제목
targetLabel	String	'Selected'	뒤쪽 목록 위의 제목
searchable	bool	false	각 목록 위에 필터를 둡니다
searchLabel	String	'Search'	그 필터가 비어 있을 때 말하는 내용
emptyLabel	String	'Nothing here'	아무것도 없는 목록이 말하는 내용
selectAllLabel	String	'Select all'	목록 제목의 체크박스가 불리는 이름
toTargetLabel	String	'Move to selected'	건너가는 화살표가 불리는 이름
toSourceLabel	String	'Move to available'	돌아오는 화살표가 불리는 이름
height	double	220	각 목록의 높이. 픽셀 수 또는 CSS 길이
disabled	bool	false	아무것도 체크하거나 옮길 수 없습니다

네이티브 <div> 속성은 모두 그대로 전달됩니다. color는 여기서 Plass의 prop이라, defaultValue는 값의 목록으로 표기하기 때문에, onChange는 onValueChange로 보고하기 때문에 제외됩니다.

PlTransferItem

Prop	타입	기본값	설명
value *	string	—	이 항목을 식별하는 것이자, value가 담는 것
label *	ReactNode	—	행이 말하는 내용
disabled	boolean	false	목록에는 있지만 옮길 수 없습니다

Prop	타입	기본값	설명
value *	String	—	이 항목을 식별하는 것이자, value가 담는 것
label *	String	—	행이 말하는 내용. 위젯이 아니라 String이라, 필터가 읽을 수 없는 행이 생기지 않습니다
disabled	bool	false	목록에는 있지만 옮길 수 없습니다

공용 축(variant size color density elevation)이 라이브러리 전체에서 무엇을 뜻하는지는 prop 규약에 있습니다.

언제 쓰나

선택지가 길 때입니다. 필드에 칩이 마흔 개 든 PlCombobox는 더 이상 읽히지 않고, 체크박스 마흔 개의 목록은 "내가 결국 뭘 골랐지"에 아무 답도 주지 못합니다.

열두 개쯤 아래라면 그 둘 중 하나가 더 작은 컴포넌트입니다. 이것은 독자에게 목록 둘과 화살표 한 쌍을 치르게 하는데, 그 값을 하는 것은 답 자체를 되읽을 값어치가 있을 때입니다.

체크는 선택이 아닙니다

value는 행이 어느 쪽에 있는지입니다. 체크는 다음 누름이 어느 행을 옮길지이고, 일부러 별도의 상태입니다. 둘을 떼어 놓는 것이, 누름을 목록을 훑는 부수 효과가 아니라 의도한 행위로 만듭니다.

거기서 세 가지가 따라 나옵니다.

• items의 순서가 두 목록이 보여 주는 순서입니다. 건너갔다 돌아온 행이 자리를 옮기지 않습니다.
• 옮기는 것은 옮겨진 것의 체크를 떨구고 나머지는 남깁니다. 반대편에 도착한 행은 아직 거기로 보내지기를 기다리고 있지 않습니다.
• 필터가 숨기고 있던 행은 애초에 그 누름의 일부가 아니었습니다.

Examples

searchable

각 목록 위에 필터를 두고, 각자 자기 쪽만 좁힙니다.

접기는 대소문자와 결합 문자를 무시합니다. cafe가 Café를 찾습니다. "내가 친 것과 맞는다"에 대한 라이브러리의 단 하나의 답이고, 안의 모든 필터가 그것을 함께 씁니다. 제품의 어느 검색 상자에서 배운 것이 다음 것에서도 맞습니다.

문자열이 아니라 노드인 라벨은 맞춰 볼 텍스트가 없으므로 남습니다. 그러지 않으면 결코 만족시킬 수 없는 필터에서 행이 사라지게 됩니다.

React

import { PlTransfer, type PlTransferItem } from 'plass-ui';

const people: PlTransferItem[] = [
  { value: 'ada', label: 'Ada Lovelace' },
  { value: 'alan', label: 'Alan Turing' },
  { value: 'grace', label: 'Grace Hopper' },
  { value: 'jose', label: 'José Hernández' },
  { value: 'katherine', label: 'Katherine Johnson' },
  { value: 'linus', label: 'Linus Torvalds' }
];

export default function TransferSearchable() {
  return (
    <PlTransfer
      className="max-w-2xl"
      items={people}
      searchable
      defaultValue={['grace']}
      sourceLabel="Everyone"
      targetLabel="On the channel"
      height={180}
    />
  );
}

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

const List<PlTransferItem> _people = <PlTransferItem>[
  PlTransferItem(value: 'ada', label: 'Ada Lovelace'),
  PlTransferItem(value: 'alan', label: 'Alan Turing'),
  PlTransferItem(value: 'grace', label: 'Grace Hopper'),
  PlTransferItem(value: 'katherine', label: 'Katherine Johnson'),
  PlTransferItem(value: 'linus', label: 'Linus Torvalds'),
];

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

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 560,
      child: PlTransfer(
        items: _people,
        searchable: true,
        defaultValue: <String>['grace'],
        sourceLabel: 'Everyone',
        targetLabel: 'On the channel',
        height: 180,
      ),
    );
  }
}

variant

두 패널은 시트가 아니라 필드의 껍데기를 입습니다. 값을 담는 목록은 필드 모양의 것이기 때문입니다. solid는 well, glass는 헤어라인 판, ghost는 포인터가 오기 전까지 표면 없음. 화살표도 따라갑니다. 가장자리가 있는 패널 옆에서는 glass, 없는 패널 옆에서는 ghost입니다.

어느 패널에도 색이 들어가지 않습니다. 담고 있는 것은 누군가의 데이터이고, 색 계열은 체크, 화살표, focus ring까지 갑니다.

React

import { PlTransfer, type PlassVariant } from 'plass-ui';

const items = [
  { value: 'a', label: 'Alpha' },
  { value: 'b', label: 'Beta' },
  { value: 'c', label: 'Gamma' }
];

export default function TransferVariants() {
  return (
    <div className="flex w-full flex-col gap-6">
      {(['solid', 'glass', 'ghost'] as PlassVariant[]).map((variant) => (
        <PlTransfer
          key={variant}
          className="max-w-2xl"
          variant={variant}
          size="sm"
          items={items}
          defaultValue={['b']}
          sourceLabel={variant}
          targetLabel="Chosen"
          height={110}
        />
      ))}
    </div>
  );
}

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

const List<PlTransferItem> _items = <PlTransferItem>[
  PlTransferItem(value: 'a', label: 'Alpha'),
  PlTransferItem(value: 'b', label: 'Beta'),
  PlTransferItem(value: 'c', label: 'Gamma'),
];

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

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 560,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 24,
        children: <Widget>[
          for (final PlassVariant variant in PlassVariant.values)
            PlTransfer(
              variant: variant,
              size: PlassSize.sm,
              items: _items,
              defaultValue: const <String>['b'],
              sourceLabel: variant.name,
              targetLabel: 'Chosen',
              height: 110,
            ),
        ],
      ),
    );
  }
}

옮길 수 없는 행

항목의 disabled는 그것을 목록에 남기고 모든 누름에서 뺍니다. 제목의 전체 선택도 마찬가지라, 그 체크가 넷 중 넷이 아니라 넷 중 셋이라고 보고합니다. 고를 수 없다고 사라지는 선택지는 독자가 찾아 헤매게 되는 선택지입니다.

쌍 전체의 disabled는 모든 것을 한 번에 멈춥니다.

React

import { PlTransfer, type PlTransferItem } from 'plass-ui';

const permissions: PlTransferItem[] = [
  { value: 'read', label: 'Read' },
  { value: 'write', label: 'Write' },
  { value: 'admin', label: 'Administer', disabled: true },
  { value: 'billing', label: 'Billing' }
];

export default function TransferStates() {
  return (
    <div className="flex w-full flex-col gap-6">
      <PlTransfer
        className="max-w-2xl"
        size="sm"
        items={permissions}
        defaultValue={['read']}
        height={130}
      />
      <PlTransfer
        className="max-w-2xl"
        size="sm"
        items={permissions}
        defaultValue={['read']}
        height={130}
        disabled
      />
    </div>
  );
}

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

const List<PlTransferItem> _permissions = <PlTransferItem>[
  PlTransferItem(value: 'read', label: 'Read'),
  PlTransferItem(value: 'write', label: 'Write'),
  PlTransferItem(value: 'admin', label: 'Administer', disabled: true),
  PlTransferItem(value: 'billing', label: 'Billing'),
];

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

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 560,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 24,
        children: <Widget>[
          PlTransfer(
            size: PlassSize.sm,
            items: _permissions,
            defaultValue: <String>['read'],
            height: 130,
          ),
          PlTransfer(
            size: PlassSize.sm,
            items: _permissions,
            defaultValue: <String>['read'],
            height: 130,
            disabled: true,
          ),
        ],
      ),
    );
  }
}

Controlled

value를 onValueChange와 함께 넘기세요. 값은 뒤쪽에 있는 value들의 목록이고 items 순서입니다. 객체가 아닙니다. transfer는 폼 컨트롤이고, 담는 것은 폼이 제출하는 것입니다. 식별자는 여기 두고 객체는 반대편에서 찾으세요.

React 빌드와 다른 점

React	Flutter	이유
ReactNode인 label, 문자열이 아니면 필터가 남겨 둠	String인 label	필터는 라벨을 읽고, 읽을 수 없는 행은 결코 만족시킬 수 없는 검색에서 사라지는 행입니다. 텍스트로 만드는 것이 모든 행을 구조적으로 검색 가능하게 합니다.
대소문자 와 결합 문자를 접음	대소문자만	Dart 코어에는 String.normalize가 없고, 이 패키지에는 의존성이 없습니다. 검색 상자가 악센트를 접자고 의존성을 들이면 비교 한 번을 위해 모든 소비자의 바이너리에 그것이 들어갑니다.
숫자나 CSS 길이인 height	double인 height	이름 붙일 두 번째 단위가 없습니다.
onValueChange	onValueChanged	Flutter의 이름입니다.
className, style, 네이티브 속성	—	전달할 class 목록도 style 속성도 없습니다.

Accessibility

• 모든 행은 행의 라벨을 이름으로 갖는 진짜 PlCheckbox입니다. 스크린 리더가 목록을 실제 모습대로, 체크박스의 목록으로 읽습니다.
• 각 제목의 체크도 체크박스이고 selectAllLabel이 이름이며, 목록의 일부만 체크된 상태에서는 indeterminate를 보고합니다.
• 두 화살표는 진짜 이름이 붙은 PlIconButton이고, 누름이 실제로 무언가를 옮길 수 있을 때까지 disabled입니다. 보이는 사람이 보는 상태를, 보지 못하는 사람도 알 수 있게.
• 각 목록에는 제목 옆에 자기 개수(체크/전체)가 있습니다. 행을 세지 않고 "방금 얼마나 골랐나"에 답하는 것이 그것입니다.
• 목록은 각자 스크롤되고 스크롤 위치를 유지하므로, 행 하나를 옮겼다고 독자가 맨 위로 되돌려지지 않습니다.