SwitchField#

라벨과 보조 설명이 포함된 폼 친화적인 스위치 컴포넌트입니다.

Live Preview#

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

  @override
  State<SwitchFieldDefaultExample> createState() =>
      _SwitchFieldDefaultExampleState();
}

class _SwitchFieldDefaultExampleState
    extends State<SwitchFieldDefaultExample> {
  bool _value = false;

  @override
  Component build(BuildContext context) {
    return CoSwitchField(
      label: 'Enable notifications',
      description: 'Receive push notifications.',
      value: _value,
      onChanged: (v) => setState(() => _value = v),
    );
  }
}

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

  @override
  State<SwitchFieldDefaultExample> createState() =>
      _SwitchFieldDefaultExampleState();
}

class _SwitchFieldDefaultExampleState
    extends State<SwitchFieldDefaultExample> {
  bool _value = false;

  @override
  Widget build(BuildContext context) {
    return CoSwitchField(
      label: 'Enable notifications',
      description: 'Receive push notifications.',
      value: _value,
      onChanged: (v) => setState(() => _value = v),
    );
  }
}

사용 시기 (When to Use)#

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

• 설정 화면에서 기능을 켜거나 끄는 이진 상태를 제어하는 경우
• 라벨과 설명 텍스트가 함께 필요한 스위치 형태의 폼 필드
• 알림, 다크 모드, 자동 저장 등 즉각 효과가 있는 토글 설정
• 폼 내에서 체크박스보다 직관적인 ON/OFF 표현이 필요한 경우

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

• Toggle: 라벨 없이 단독으로 사용하는 간단한 스위치
• Checkbox: 여러 항목의 선택 여부를 폼 내에서 관리하는 경우
• RadioGroup: 상호 배타적인 여러 옵션 중 하나를 선택하는 경우

기본 사용법 (Basic Usage)#

// 기본 스위치 필드
CoSwitchField(
  value: isNotificationEnabled,
  onChanged: handleNotificationToggled,
  label: '알림 수신',
)

// 설명 포함
CoSwitchField(
  value: isDarkMode,
  onChanged: handleDarkModeToggled,
  label: '다크 모드',
  description: '어두운 테마를 사용합니다',
  activeColor: Colors.indigo,
)

// 큰 크기
CoSwitchField(
  value: isAutoSave,
  onChanged: handleAutoSaveToggled,
  label: '자동 저장',
  description: '변경 사항을 자동으로 저장합니다',
  size: SwitchSize.lg,
)

// 기본 스위치 필드
CoSwitchField(
  value: isNotificationEnabled,
  onChanged: handleNotificationToggled,
  label: '알림 수신',
)

// 설명 텍스트 포함 — description으로 보조 설명 표시
CoSwitchField(
  value: isDarkMode,
  onChanged: handleDarkModeToggled,
  label: '다크 모드',
  description: '어두운 테마를 사용합니다',
)

// 비활성화 상태 — enabled: false로 상호작용 차단
CoSwitchField(
  value: isAutoSave,
  onChanged: handleAutoSaveToggled,
  label: '자동 저장',
  description: '변경 사항을 자동으로 저장합니다',
  enabled: false,
)

Props / Parameters#

변형 (Variants)#

기본#

CoSwitchField(
  value: emailMarketing,
  onChanged: handleEmailMarketingToggled,
  label: '마케팅 이메일 수신',
)

설명 포함#

CoSwitchField(
  value: biometricLogin,
  onChanged: handleBiometricToggled,
  label: '생체 인증 로그인',
  description: '지문 또는 얼굴 인식으로 로그인합니다',
  activeColor: Colors.green,
)

동작 스펙 (Behavior)#

인터랙션#

• 클릭/탭: 스위치 토글 또는 레이블/설명 영역 클릭으로 상태 전환
• 호버: 포인터 오버 시 스위치에 시각적 강조 표시
• 포커스: 포커스 링으로 현재 포커스 상태 표시

상태 전환#

• off → on (클릭 또는 Space/Enter 입력)
• on → off (다시 클릭 또는 Space/Enter 입력)
• disabled 상태에서는 모든 인터랙션 무시

즉각 반영 vs 폼 제출#

• 설정 페이지에서 SwitchField는 일반적으로 클릭 즉시 효과 반영
• 폼 내에서 사용 시 다른 필드와 함께 제출 시 반영

사용 가이드라인 (Usage Guidelines)#

✅ Do#

CouiCoSwitchField(
  value: locationTracking,
  onChanged: handleLocationTrackingToggled,
  label: '위치 정보 수집',
  description: '앱 사용 중 위치 데이터를 수집하여 맞춤 서비스를 제공합니다',
)

❌ Don't#

// ❌ 여러 항목 중 다수를 선택해야 하는 경우 Checkbox가 적합
Column(
  children: [
    CouiCoSwitchField(value: receiveEmail, onChanged: handleEmailToggled, label: '이메일'),
    CouiCoSwitchField(value: receiveSms, onChanged: handleSmsToggled, label: 'SMS'),
    CouiCoSwitchField(value: receivePush, onChanged: handlePushToggled, label: '푸시 알림'),
    // 이런 경우 CheckboxGroup이 더 적합
  ],
)

✅ Do#

CouiCoSwitchField(
  value: isFeatureEnabled,
  onChanged: (value) async {
    unawaited(settingsService.updateFeature(value));
    handleFeatureToggled(value);
  },
  label: '베타 기능 사용',
  enabled: !isLoading, // API 호출 중 비활성화
)

❌ Don't#

// ❌ 부정 표현은 ON/OFF 상태와 혼란을 야기함
CouiCoSwitchField(
  value: isNotificationsDisabled, // 부정 상태를 저장
  onChanged: handleNotificationsDisabledToggled,
  label: '알림 끄기', // ON이 "알림 끄기"? 혼란스러움
)

✅ Do#

CouiCoSwitchField(
  label: '마케팅 알림 수신',
  description: '이벤트 및 프로모션 알림을 받습니다.',
  value: marketingEnabled,
  onChanged: handleMarketingToggled,
)

❌ Don't#

// ❌ Switch 토글 즉시 계정 삭제 시작
CouiCoSwitchField(
  label: '계정 비활성화',
  value: isDeactivated,
  onChanged: (value) {
    if (value) deactivateAccountImmediately();  // 위험한 즉시 실행
  },
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Semantics로 switch role, label, checked 상태 전달 (예: "다크 모드, 스위치, 켜짐")
• Web: role="switch", aria-checked, aria-label(label 텍스트), aria-describedby(description) 자동 적용

터치 타겟#

• 최소 터치 타겟 크기: 48x48dp
• 스위치 + 레이블 전체 영역이 터치 가능 영역

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

v3.0부터 기본 API (enabled, onChanged, value 등)가 통일되었습니다. 아래는 플랫폼 고유 차이점만 나열합니다.

관련 컴포넌트 (Related Components)#

• Toggle: 라벨 없이 단독으로 사용하는 최소한의 스위치
• Checkbox: 폼에서 항목 선택 여부를 관리하는 경우
• RadioGroup: 여러 옵션 중 하나를 배타적으로 선택하는 경우

조합 예제#

// SwitchField 목록 + Fieldset 조합: 알림 설정 섹션
CouiFieldset(
  legend: '알림 설정',
  children: [
    CouiCoSwitchField(
      value: pushEnabled,
      onChanged: handlePushToggled,
      label: '푸시 알림',
      description: '새 메시지와 업데이트를 알려드립니다',
    ),
    CouiCoSwitchField(
      value: emailEnabled,
      onChanged: handleEmailToggled,
      label: '이메일 알림',
      description: '주간 요약 및 중요 공지를 이메일로 받습니다',
    ),
    CouiCoSwitchField(
      value: marketingEnabled,
      onChanged: handleMarketingToggled,
      label: '마케팅 알림',
      description: '할인 혜택 및 이벤트 정보를 받습니다',
    ),
  ],
)