ItemPicker#

검색 입력과 함께 문자열 아이템을 리스트 또는 그리드로 나열하여 단일 선택하는 인라인 피커입니다. 검색어를 입력하면 아이템이 대소문자 무시 contains 로 필터링되고, 클릭하면 선택됩니다.

Live Preview#

class ItemPickerDefaultExample extends StatefulComponent {
  const ItemPickerDefaultExample({super.key});

  @override
  State<ItemPickerDefaultExample> createState() =>
      _ItemPickerDefaultExampleState();
}

class _ItemPickerDefaultExampleState extends State<ItemPickerDefaultExample> {
  String _selected = 'Apple';

  @override
  Component build(BuildContext context) {
    return ItemPicker(
      items: const ['Apple', 'Banana', 'Cherry', 'Mango', 'Orange'],
      selectedValue: _selected,
      title: 'Fruits',
      onChanged: (value) => setState(() => _selected = value),
    );
  }
}

class ItemPickerDefaultExample extends StatefulWidget {
  const ItemPickerDefaultExample({super.key});

  @override
  State<ItemPickerDefaultExample> createState() =>
      _ItemPickerDefaultExampleState();
}

class _ItemPickerDefaultExampleState extends State<ItemPickerDefaultExample> {
  String _selected = 'Apple';

  @override
  Widget build(BuildContext context) {
    return ItemPicker(
      items: const ['Apple', 'Banana', 'Cherry', 'Mango', 'Orange'],
      selectedValue: _selected,
      title: 'Fruits',
      onChanged: (value) => setState(() => _selected = value),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 미리 정의된 아이템 목록에서 검색하며 하나를 선택받는 경우
• 색상·아이콘·템플릿처럼 그리드로 보여줘야 하는 선택지

대신 다른 컴포넌트를 사용하세요:

• Select: 드롭다운으로 공간을 절약해야 하는 경우
• Autocomplete: 자유 입력 + 제안이 필요한 경우

기본 사용법 (Basic Usage)#

// 검색 가능한 리스트 피커
ItemPicker(
  items: const ['Apple', 'Banana', 'Cherry'],
  selectedValue: selected,
  onChanged: (value) => setState(() => selected = value),
)

// 그리드 레이아웃
ItemPicker(
  items: items,
  layout: CoreItemPickerLayout.grid,
  gridColumns: 3,
  title: 'Templates',
  onChanged: (value) => pick(value),
)

// 검색 가능한 리스트 피커
ItemPicker(
  items: const ['Apple', 'Banana', 'Cherry'],
  selectedValue: selected,
  onChanged: (value) => setState(() => selected = value),
)

// 그리드 레이아웃
ItemPicker(
  items: items,
  layout: CoreItemPickerLayout.grid,
  gridColumns: 3,
  title: 'Templates',
  onChanged: (value) => pick(value),
)

Props / Parameters#

동작 스펙 (Behavior)#

인터랙션#

• 검색: 검색어 입력 시 대소문자 무시 contains 필터링
• 클릭: 아이템 클릭 시 선택, 선택 아이템은 체크 아이콘 표시
• 호버: 마우스 올린 아이템에 hover 색상 적용
• enabled가 false이면 비활성

접근성 (Accessibility)#

• 컨테이너: role="listbox", 비활성 시 aria-disabled="true"
• 각 아이템: role="option" + aria-selected

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Select: 드롭다운 단일 선택
• Autocomplete: 자유 입력 + 제안