PhoneInput#

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

Live Preview#

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

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

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

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

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

  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        const PhoneInput(placeholder: 'Phone number').radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor·borderWidth)까지 한 번에.
        const PhoneInput(placeholder: 'Full control').withStyle(
          const CorePhoneInputStyle(
            backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        const PhoneInput(placeholder: 'Phone number').radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor·borderWidth)까지 한 번에.
        const PhoneInput(placeholder: 'Full control').withStyle(
          const CorePhoneInputStyle(
            backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

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

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

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

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

기본 사용법 (Basic Usage)#

Flutter와 Web 모두 PhoneInput 클래스와 CoreCountry 타입을 동일하게 사용합니다. 국가는 CoreCountry.byCode('KR') 룩업, const CoreCountry(...) 리터럴, 또는 전체 목록 CoreCountry.all(247개) 중에서 지정합니다.

// 기본 전화번호 입력 (CoreCountry 사용)
PhoneInput(
  initialCountry: CoreCountry.byCode('KR'),
  onChanged: (phoneNumber) {
    handlePhoneChanged(phoneNumber);
  },
)

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

// 특정 국가만 허용
PhoneInput(
  initialCountry: CoreCountry.byCode('KR'),
  countries: [
    CoreCountry.byCode('KR')!,
    CoreCountry.byCode('US')!,
    CoreCountry.byCode('JP')!,
  ],
  onChanged: handlePhoneChanged,
)

// 기본 전화번호 입력 (CoreCountry 사용)
PhoneInput(
  initialCountry: CoreCountry.byCode('KR'),
  onChanged: (value) {
    handlePhoneChanged(value);
  },
)

// 초기값 설정 (초기 번호 포함)
PhoneInput(
  initialCountry: CoreCountry.unitedStates,
  initialNumber: '5551234567',
  placeholder: '전화번호 입력',
  onChanged: handlePhoneChanged,
)

// 특정 국가만 허용
PhoneInput(
  initialCountry: CoreCountry.byCode('KR'),
  countries: [
    CoreCountry.byCode('KR')!,
    CoreCountry.byCode('US')!,
    CoreCountry.byCode('JP')!,
  ],
  onChanged: handlePhoneChanged,
)

빠른 오버라이드 (Chain)#

이미 만든 PhoneInput 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다. .radius16처럼 Core 토큰 상수 이름과 똑같은 이름의 getter도 있습니다 — withStyle을 한 번 더 줄인 sugar로, 이름이 곧 값이라(radius16 == CoreRadius.radius16) 어느 컴포넌트에서 써도 뜻이 갈리지 않습니다.

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

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        const PhoneInput(placeholder: 'Phone number').radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor·borderWidth)까지 한 번에.
        const PhoneInput(placeholder: 'Full control').withStyle(
          const CorePhoneInputStyle(
            backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        const PhoneInput(placeholder: 'Phone number').radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor·borderWidth)까지 한 번에.
        const PhoneInput(placeholder: 'Full control').withStyle(
          const CorePhoneInputStyle(
            backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

Props / Parameters#

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

PhoneNumber(Flutter)와 PhoneInputValue(Web)는 같은 CorePhoneNumber 의 이름 두 개입니다 — 한쪽에서 저장한 값을 다른 쪽에서 그대로 받습니다. country / number 를 들고, countryCode · dialCode · fullNumber · value 를 파생해 줍니다.

Flutter 전용 파라미터#

CorePhoneInputStyle 필드#

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

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

CoreComponentTheme(
  phoneInput: CorePhoneInputTheme(
    style: CorePhoneInputStyle(
      borderRadius: CoreBorderRadius.all(CoreRadius.radius4),
      flagGapStyle: CoreGapStyle(size: CoreSpace.space8),
      countryGapStyle: CoreGapStyle(size: CoreSpace.space16),
      maxWidth: 200.0,
    ),
  ),
)

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

동작 스펙 (Behavior)#

인터랙션#

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

읽기 규칙 (양쪽 공통)#

타이핑된 것만 제거하고, 나머지는 추측하지 않습니다. filterPlusCode: true(기본)는 선택된 국가의 +다이얼코드로 시작할 때 그것만 벗깁니다. 그 외에는 입력한 그대로 전달됩니다.

입력 칸을 고쳐 쓰는 게 아니라 읽을 때 파생하므로, 같은 텍스트를 두고 국가만 바꾸면 새 다이얼 코드로 다시 해석됩니다. 양 플랫폼이 CorePhoneNumber.fromInput 하나를 호출합니다.

왜 선행 0을 떼지 않나 (0.129 변경)

이전에는 선행 0과 + 없이 적힌 다이얼 코드도 제거했습니다. 둘 다 남은 숫자가 무슨 뜻인지에 대한 추측이고, 어떤 추측도 모든 나라에서 맞지 않습니다:

두 입력은 모양이 같고 다이얼 코드에는 이를 구분할 정보가 없습니다. 그래서 0을 떼면 이탈리아가 깨지고, 안 떼면 영국이 깨집니다 — 손상이 사라지는 게 아니라 옮겨갑니다. 구분하려면 국가별 national prefix 표가 필요한데 CoreCountry(code/dialCode/name)에도 그 원본 데이터셋에도 없습니다.

그래서 지금은 입력한 값을 그대로 읽습니다. 다이얼 코드를 떼고 싶으면 타이핑하면 됩니다 — 그래서 onlyNumber가 켜져 있어도 맨 앞 + 는 입력할 수 있습니다.

검색 (양쪽 공통)#

• 국가 드롭다운 내 검색 입력: name/dialCode/code 기준 필터링
• 양쪽 모두 드롭다운 패널 최상단에 검색 입력창 (autofocus)

상태#

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

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

✅ Do#

PhoneInput(
  initialValue: PhoneNumber(
    country: CoreCountry.byCode('KR')!,
    number: '1012345678',
  ),
  onChanged: handlePhoneChanged,
)

❌ Don't#

// ❌ 0.129부터 두 플래그는 무시된다 — 값은 '0821012345678' 그대로 온다
PhoneInput(
  filterZeroCode: true,
  filterCountryCode: true,
  initialNumber: '0821012345678',
)

// ✅ 다이얼 코드를 떼려면 타이핑된 형태로 받는다
PhoneInput(initialNumber: '+821012345678')  // → number: '1012345678'

접근성 (Accessibility)#

관련 컴포넌트 (Related Components)#

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