TextField
TextField(텍스트필드) 위젯은 사용자가 글자를 입력하는 입력창입니다. 검색어, 이름, 비밀번호 등 텍스트 입력에 사용합니다.
정보
예제 파일: 07_Work_with_Widgets/textfield_objet.lfp
정의 / 역할
TextField 위젯은 사용자가 키보드로 텍스트를 입력하는 영역을 그려줍니다. 입력이 바뀌면 onChanged, 제출하면 onSubmitted 등의 동작이 실행됩니다. 힌트·테두리 같은 꾸밈, 키보드 종류, 최대 글자 수, 비밀번호 가림 등을 설정할 수 있습니다.
- 카테고리: Contents
기능
| 기능 | 설명 |
|---|---|
| 텍스트 입력 | 사용자가 키보드로 글자를 입력하고, 입력·제출 시 동작을 실행합니다. |
| 입력 꾸밈 | 힌트 문구·라벨·테두리 등 입력창 모양을 decoration으로 설정합니다. |
| 입력 제어 | 키보드 종류, 최대 글자 수, 여러 줄 입력, 읽기 전용, 비밀번호 가림 등을 설정합니다. |
| 스크립트 제어 | 스크립트로 텍스트를 읽고/쓰고, 포커스를 옮기고, 텍스트 폭을 측정할 수 있습니다. |
사용 방법
- 왼쪽 위젯 팔레트에서 Contents 카테고리를 엽니다.
- TextField 항목을 캔버스로 끌어다 놓습니다.
decoration에서 힌트 문구·테두리 등 모양을 설정합니다.onChanged(입력 변화)나onSubmitted(제출) 등 이벤트에 실행할 동작을 연결합니다.- 필요하면 키보드 종류(
keyboardType)·최대 글자 수(maxLength)·비밀번호 가림(obscureText) 등을 조정합니다.
속성 (Property)
노트
아래는 속성 패널을 펼쳤을 때 바로 보이는 최상위 속성입니다. decoration·style처럼 묶음(그룹) 속성은 펼치면 하위 옵션이 더 있으며, 여기서는 최상위 항목만 다룹니다.
| 속성 | 설명 | 기본값 | 값 / 타입 |
|---|---|---|---|
text | 입력된 텍스트 | 빈 문자열 | 문자열 |
focusNode | 입력창의 포커스 노드 | 미지정 | 포커스 노드 |
decoration | 입력 꾸밈 (힌트·라벨·테두리 등) | 미지정 | 입력 꾸밈 |
keyboardType | 키보드 종류 | 미지정 | 키보드 타입 |
textInputAction | 키보드 액션 버튼(완료/검색 등) | 미지정 | 키보드 액션 |
textCapitalization | 자동 대문자화 | none | none, words, sentences, characters |
style | 글자 스타일 | 미지정 | 텍스트 스타일 |
strutStyle | 줄 높이 등 스트럿 스타일 | 미지정 | 스트럿 스타일 |
textAlign | 텍스트 정렬 | start | left, right, center, justify, start, end |
textAlignVertical | 세로 정렬 위치 | 미지정 | 숫자(-1.0 ~ 1.0) |
textDirection | 텍스트 방향 | 미지정 | rtl, ltr |
readOnly | 읽기 전용(입력 불가) | 꺼짐(false) | 참 / 거짓 |
howCursor | 커서 표시 방식 - 현재 버전에서는 동작하지 않습니다. | 꺼짐(false) | 참 / 거짓 |
showCursor | 커서 표시 여부 | 미지정 | 참 / 거짓 |
autofocus | 화면이 열릴 때 자동 포커스 | 꺼짐(false) | 참 / 거짓 |
obscuringCharacter | 가릴 때 표시할 문자 | • | 문자 |
obscureText | 입력 가림(비밀번호) | 꺼짐(false) | 참 / 거짓 |
autocorrect | 자동 교정 | 켜짐(true) | 참 / 거짓 |
smartDashesType | 스마트 대시 입력 | 미지정 | disabled, enabled |
smartQuotesType | 스마트 따옴표 입력 | 미지정 | disabled, enabled |
enableSuggestions | 추천 입력 | 켜짐(true) | 참 / 거짓 |
maxLines | 최대 줄 수 | 미지정(1줄) | 정수 |
minLines | 최소 줄 수 | 미지정 | 정수 |
expands | 부모 높이를 채우도록 확장 | 꺼짐(false) | 참 / 거짓 |
maxLength | 최대 글자 수 | 미지정(제한 없음) | 정수 |
maxLengthEnforcement | 최대 글자 수 초과 처리 방식 | 미지정 | none, enforced, truncateAfterCompositionEnds |
inputFormatters | 입력 형식 제한 목록 | 미지정 | 목록 |
enabled | 사용 가능 여부 | 미지정(사용 가능) | 참 / 거짓 |
cursorWidth | 커서 두께 | 2 | 숫자 |
cursorHeight | 커서 높이 | 미지정 | 숫자 |
cursorRadius | 커서 모서리 반경 | 미지정 | 반경 |
cursorColor | 커서 색 | 미지정 | 색상 |
selectionHeightStyle | 선택 영역 높이 기준 | tight | tight, max, includeLineSpacingMiddle, includeLineSpacingTop, includeLineSpacingBottom, strut |
selectionWidthStyle | 선택 영역 너비 기준 | tight | tight, max |
keyboardAppearance | 키보드 밝기 테마 | 미지정 | dark, light |
scrollPadding | 스크롤 시 확보할 여백 | 20 | 여백 |
dragStartBehavior | 드래그 시작 동작 | start | start, down |
enableInteractiveSelection | 선택(복사·붙여넣기 등) 허용 | 미지정 | 참 / 거짓 |
mouseCursor | 마우스 커서 | 미지정 | 커서 |
scrollController | 스크롤 컨트롤러 | 미지정 | 스크롤 컨트롤러 |
scrollPhysics | 스크롤 동작 방식 | 미지정 | 스크롤 방식 |
autofillHints | 자동완성 힌트 목록 | 미지정(빈 목록) | 목록 |
clipBehavior | 영역을 벗어나는 부분 자르기 방식 | hardEdge | none, hardEdge, antiAlias, antiAliasWithSaveLayer |
restorationId | 상태 복원 ID | 미지정 | 문자열 |
scribbleEnabled | 스크리블(펜 입력) 사용 | 켜짐(true) | 참 / 거짓 |
enableIMEPersonalizedLearning | IME 개인화 학습 사용 | 켜짐(true) | 참 / 거짓 |
주의 / 팁
팁
비밀번호 입력창은 obscureText를 켜고, 필요하면 obscuringCharacter로 가림 문자를 바꿉니다.
팁
여러 줄 입력이 필요하면 maxLines(및 minLines)를 늘리거나, 부모 높이를 채우려면 expands를 켭니다.
더 알아보기
팁
이 위젯을 스크립트로 제어하는 Widget Control(Property·Method·Event) 전체는 TextField (텍스트필드) Widget Control 문서에서 확인하세요.