Tinyrack

OTP Field

하나의 접근 가능한 입력을 개별 슬롯으로 표시해 인증 코드를 받아요.

하나의 접근 가능한 입력을 개별 슬롯으로 표시해 인증 코드를 받아요.

핵심 속성

속성설명
값기본 생성자는 비제어 방식이에요. defaultValue로 초기값을 주거나, TROtpFieldController를 넘겨 바깥에서 코드를 읽고 지우세요. TROtpField.controlled는 대신 value를 받고, onValueChange로 전달된 다음 코드를 직접 보관해야 해요.
입력슬롯 아래에 숨겨진 TextField 하나가 있어서 입력, 코드 전체 붙여넣기, 삭제, AutofillHints.oneTimeCode를 통한 플랫폼 자동 완성이 모두 값 전체에 적용돼요. 입력은 항상 끝에 덧붙고, 슬롯마다 옮겨 다니는 커서는 없어요.
허용 문자allowedPattern은 기본값이 RegExp("[0-9]")이고 FilteringTextInputFormatter로 강제되므로 그 밖의 문자는 들어오는 즉시 버려져요. 거부는 조용히 일어나고 별도의 콜백이 없으니, 기대하는 형식을 helperText로 알려 주세요.
길이와 크기length는 값을 잘라내고 onCompleted가 호출되는 시점을 결정해요. uiSize는 공용 컨트롤 높이 스케일에 맞춰 정사각형 슬롯 크기를 조절하므로, md·lg가 같은 크기의 TRTextField나 TRButton과 나란히 맞아요.

다른 기기에 온 짧은 고정 길이 코드를 옮겨 적을 때 TROtpField를 쓰세요. 더 길거나 자유로운 입력에는 TRTextField를 쓰세요.

설치

패키지를 추가한 뒤 공개 라이브러리를 가져오세요.

flutter pub add tinyrack_ui
import 'package:tinyrack_ui/tinyrack_ui.dart';

플레이그라운드

사용법

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

TROtpField(
  label: 'Verification code',
  length: 6,
  helperText: 'Enter the code we sent to your device.',
  onCompleted: verifyCode,
)

예시

크기 고유 링크

옆에 놓인 `TRTextField`, `TRButton`, `TRNumberField`와 나란히 맞도록 `uiSize`를 고르세요. 숫자 스타일은 어떤 크기에서도 그대로이고, 정사각형 슬롯과 기본 간격만 달라져요.

길이와 사용 가능 여부 고유 링크

`length`는 슬롯 개수를 정하고 `onCompleted` 호출 시점을 결정해요. `readOnly`는 코드를 보여 주고 포커스도 유지하면서 편집만 막고, `enabled: false`는 필드 전체를 흐리게 하며 포커스까지 막아요.

필수 코드와 복구 고유 링크

`TROtpFieldFormField`는 상위 `Form`에 참여하므로 `validator`가 반환한 문구가 `errorText`가 되고 슬롯 테두리가 빨갛게 바뀌어요. `AutovalidateMode.onUserInteraction`을 쓰면 제출할 때뿐 아니라 입력하는 중에도 자릿수가 모자란 것을 알려 줘요.

가려진 입력과 초기화 고유 링크

`obscureText`는 각 자리를 점으로 바꾸고 값이 `Semantics`에 전달되지 않게 하므로, 입력 후에도 비밀로 남아야 하는 코드에만 쓰세요. `TROtpFieldController`는 다시 시도 동작에서 입력을 비우고, `separatorBuilder`는 `index` 슬롯 뒤의 간격을 대체해요. 비워 둘 자리에는 일반 `SizedBox`를 반환하세요.

API

TROtpField 속성

Prop타입 / 기본값용도
lengthint · 6슬롯 개수를 정하고 값을 그 길이로 잘라내며 onCompleted 호출 조건이 돼요. 0보다 커야 해요.
defaultValueString · ''비제어 기본 생성자의 초기값이에요. TROtpField.controlled에서는 무시돼요.
valueString · required on .controlled제어 생성자에서 표시할 코드를 결정해요. onValueChange와 함께 쓰면서 다음 코드를 직접 보관하세요.
controllerTROtpFieldController? · null제어 생성자로 바꾸지 않고도 위젯 바깥에서 코드를 읽거나 교체하거나 지울 수 있어요.
onValueChangeValueChanged<String>? · null허용된 편집마다 잘린 값과 함께 호출돼요. 걸러진 문자는 전달되지 않아요.
onCompletedValueChanged<String>? · null값이 length에 도달할 때 호출되고, 붙여넣기로 한 번에 채워질 때도 호출돼요. 값이 가득 찬 채로 이뤄지는 모든 편집에서 실행되므로 반복 호출에 안전하게 작성하세요.
allowedPatternPattern? · RegExp("[0-9]")허용 문자를 제한해요. 영숫자 코드라면 RegExp("[A-Z0-9]")처럼 범위를 넓히세요.
obscureTextbool · false채워진 슬롯을 점으로 대체하고, Semantics로 값이 노출되지 않게 해요.
uiSizeTRUiSize · TRUiSize.md정사각형 슬롯과 기본 간격을 md·lg 컨트롤 높이에 맞춰 조절해요. separatorBuilder는 간격을 완전히 대체하므로, 그 안에서 직접 크기를 정하세요.
labelString? · null슬롯 위에 대문자 캡션을 표시하고, semanticLabel이 없으면 보조 기술에도 이 이름을 전달해요.
semanticLabelString? · null보조 기술에서는 label보다 우선해요. 눈에 보이는 캡션만으로는 설명이 부족할 때 쓰세요.
helperTextString? · null슬롯 아래에 흐린 보조 텍스트를 표시해요. 오류가 있는 동안에는 errorText가 대신 표시돼요.
errorTextString? · null슬롯 테두리를 위험 색으로 바꾸고 보조 문구를 대체해요. null이 아니면 그 자체로 오류 상태가 되며, 검증은 직접 수행해야 해요.
enabledbool · truefalse이면 슬롯을 흐리게 하고 탭 포커스와 편집을 막으며 레이블도 흐려져요.
readOnlybool · false값을 보여 주고 포커스도 유지하면서 편집만 막아요. 읽기만 하고 바꾸면 안 되는 코드에 쓰세요.
autofocusbool · false첫 빌드에서 포커스를 잡아요. 코드 입력이 화면의 유일한 목적일 때만 쓰세요.
separatorBuilderTROtpSeparatorBuilder? · nullindex 슬롯 뒤의 간격을 대체해요. 비워 둘 자리에는 일반 SizedBox를 반환하세요. 아무것도 반환하지 않을 수는 없어요.

TROtpFieldController

Prop타입 / 기본값용도
valueString현재 코드를 읽거나 교체해요. 값을 넣으면 리스너에 알리고 슬롯을 다시 그리며, 같은 문자열을 넣으면 아무 일도 일어나지 않아요.
clear()void입력을 비워요. 코드가 거부된 뒤의 다시 시도 동작과 함께 쓰세요.

TROtpFieldFormField

Prop타입 / 기본값용도
initialValueString · ''FormField 상태의 초기값이에요. 이후 값은 FormField가 관리해요.
validatorFormFieldValidator<String>? · nullerrorText로 표시할 메시지를 반환해요. 코드가 올바르면 null을 반환하세요.
autovalidateModeAutovalidateMode? · null검증 시점을 정해요. onUserInteraction은 사용자가 편집하는 즉시 짧은 코드를 알려 줘요.
onSavedFormFieldSetter<String>? · null상위 Form이 저장될 때 코드를 전달받아요.
restorationIdString? · null플랫폼이 라우트를 다시 만든 뒤 입력한 코드를 복원해요.