PhoneInput#

국가 선택과 함께 전화번호를 입력하는 컴포넌트입니다. Flutter/Web 양쪽에서 동일한 API(CoPhoneInput)를 제공합니다.

Live Preview#

class PhoneInputDefaultExample extends StatelessComponent {
  const PhoneInputDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoPhoneInput(placeholder: 'Phone number');
  }
}

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

  @override
  Widget build(BuildContext context) {
    return const CoPhoneInput(placeholder: 'Phone number');
  }
}

사용 시기 (When to Use)#

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

• 글로벌 서비스에서 여러 국가의 전화번호를 입력받아야 할 때
• 국가 코드(다이얼 코드)와 함께 전화번호를 저장해야 할 때

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

• Input: 단일 국가 내수 서비스에서 단순 숫자 입력으로 충분할 때
• Select + Input 조합: 국가 선택과 번호 입력을 완전히 독립 제어해야 할 때

기본 사용법 (Basic Usage)#

Flutter와 Web 모두 CoPhoneInput 클래스를 사용합니다. 국가 타입만 플랫폼별로 다릅니다.

// 기본 전화번호 입력 (Country enum 사용)
CoPhoneInput(
  initialCountry: Country.korea,
  onChanged: (phoneNumber) {
    handlePhoneChanged(phoneNumber);
  },
)

// 초기값 설정 (초기 번호 포함)
CoPhoneInput(
  initialCountry: Country.unitedStates,
  initialNumber: '5551234567',
  onChanged: handlePhoneChanged,
)

// 특정 국가만 허용
CoPhoneInput(
  initialCountry: Country.korea,
  countries: [Country.korea, Country.unitedStates, Country.japan],
  onChanged: handlePhoneChanged,
)

// 기본 전화번호 입력 (CoreCountry 사용)
CoPhoneInput(
  initialCountry: CoreCountry(code: 'KR', dialCode: '+82', name: 'Korea'),
  onChanged: (value) {
    handlePhoneChanged(value);
  },
)

// 초기값 설정
CoPhoneInput(
  initialCountry: CoreCountry(code: 'US', dialCode: '+1', name: 'United States'),
  initialNumber: '5551234567',
  placeholder: '전화번호 입력',
  onChanged: handlePhoneChanged,
)

// 특정 국가만 허용
CoPhoneInput(
  initialCountry: CoreCountry(code: 'KR', dialCode: '+82', name: 'Korea'),
  countries: [
    CoreCountry(code: 'KR', dialCode: '+82', name: 'Korea'),
    CoreCountry(code: 'US', dialCode: '+1', name: 'United States'),
  ],
  onChanged: handlePhoneChanged,
)

Props / Parameters#

CoPhoneInput은 Flutter/Web에서 동일한 파라미터 이름을 사용합니다. 타입만 플랫폼별로 다릅니다.

Flutter 전용 파라미터#

테마 커스터마이징 (Theme)#

CorePhoneInputTheme으로 프로젝트 기본 스타일을 오버라이드:

CoreComponentTheme(
  phoneInput: CorePhoneInputTheme(
    borderRadius: 6.0,
    flagGap: 8.0,
    countryGap: 16.0,
    maxWidth: 200.0,
    padding: 8.0,
  ),
)

Resolve 우선순위: 위젯 파라미터 > CorePhoneInputTheme > 디자인 시스템 기본값.

동작 스펙 (Behavior)#

인터랙션#

• 국가 선택: 다이얼 코드 버튼 클릭 시 국가 목록 팝업
• 번호 입력: onlyNumber: true 시 숫자만 허용
• 키보드: TextInputType.phone / inputmode="tel" 로 전화번호 키패드 활성화
• 자동완성: autocomplete="tel" / AutofillHints.telephoneNumber

필터링 (Flutter)#

• filterPlusCode: true: + 자동 제거
• filterZeroCode: true: 선행 0 제거 (국제 규약)
• filterCountryCode: true: 다이얼 코드 중복 입력 자동 제거

검색 (양쪽 공통)#

• 국가 드롭다운 내 검색 입력: name/dialCode/code 기준 필터링
• Flutter는 Select 내장 search, Web은 드롭다운 최상단 입력창

상태#

• enabled: false: 전체 컴포넌트 opacity 50% + 인터랙션 차단

접근성 (Accessibility)#

관련 컴포넌트 (Related Components)#

• Input: 단일 국가용 일반 전화번호 입력
• Select: 국가 선택만 독립 제공
• Form: 폼 내에서 PhoneInput 사용