TextField텍스트 필드

텍스트 필드 컴포넌트는 사용자가 페이지에 텍스트를 입력할 수 있도록하며, 일반적으로 양식과 대화 상자에 사용됩니다.

사용법

컴포넌트 가져오기:

import 'mdui/components/text-field.js';

컴포넌트의 TypeScript 타입 가져오기:

import type { TextField } from 'mdui/components/text-field.js';

사용 예시:

<mdui-text-field label="Text Field"></mdui-text-field>

예시

형태

variant 속성으로 텍스트 필드의 형태를 설정합니다.

<mdui-text-field variant="filled" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field variant="outlined" label="Text Field"></mdui-text-field>

소스

보조 텍스트

label 속성으로 텍스트 필드 상단의 레이블 텍스트를 설정합니다.

<mdui-text-field label="Text Field"></mdui-text-field>

소스

placeholder 속성으로 값이 없을 때의 플레이스홀더 텍스트를 설정합니다.

<mdui-text-field label="Text Field" placeholder="Placeholder"></mdui-text-field>

소스

helper 속성으로 텍스트 필드 하단의 도움말 텍스트를 설정합니다. helper 슬롯을 사용해 도움말 텍스트를 설정할 수도 있습니다. helper-on-focus 속성을 추가하면 입력 필드가 포커스를 받을 때만 도움말 텍스트를 표시합니다.

Supporting text

<mdui-text-field label="Text Field" helper="Supporting text"></mdui-text-field>

<mdui-text-field label="Text Field">
  <span slot="helper" style="color: blue">Supporting text</span>
</mdui-text-field>

<mdui-text-field label="Text Field" helper="Supporting text" helper-on-focus></mdui-text-field>

소스

비우기 가능

clearable 속성을 추가하면 텍스트 필드에 값이 있을 때 오른쪽에 비우기 버튼이 추가됩니다.

<mdui-text-field clearable label="Text Field" value="Input Text"></mdui-text-field>

소스

텍스트 오른쪽 정렬

end-aligned 속성을 추가하면 텍스트를 오른쪽으로 정렬할 수 있습니다.

<mdui-text-field end-aligned label="Text Field" value="Input Text"></mdui-text-field>

소스

앞뒤 텍스트 및 아이콘

icon 및 end-icon 속성을 설정하면 텍스트 필드의 왼쪽과 오른쪽에 Material Icons 아이콘을 추가할 수 있습니다. icon 및 end-icon 슬롯을 통해 텍스트 필드의 왼쪽과 오른쪽에 요소를 추가할 수도 있습니다.

<mdui-text-field icon="search" end-icon="mic" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field label="Text Field">
  <mdui-button-icon slot="icon" icon="search"></mdui-button-icon>
  <mdui-button-icon slot="end-icon" icon="mic"></mdui-button-icon>
</mdui-text-field>

소스

prefix 및 suffix 속성을 설정하면 텍스트 필드의 왼쪽과 오른쪽에 텍스트를 추가할 수 있습니다. prefix 및 suffix 슬롯을 통해 텍스트 필드의 왼쪽과 오른쪽에 텍스트 요소를 추가할 수도 있습니다. 이 텍스트는 텍스트 필드가 포커스를 받거나 값이 있을 때만 표시됩니다.

$ /100

<mdui-text-field prefix="$" suffix="/100" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field label="Text Field">
  <span slot="prefix" style="color: blue">$</span>
  <span slot="suffix" style="color: blue">/100</span>
</mdui-text-field>

소스

읽기 전용 모드

readonly 속성을 추가하면 텍스트 필드를 읽기 전용 모드로 설정할 수 있습니다.

<mdui-text-field readonly label="Text Field" value="Input Text"></mdui-text-field>

소스

비활성화 상태

disabled 속성을 추가하면 텍스트 필드를 비활성화할 수 있습니다.

<mdui-text-field disabled label="Text Field" value="Input Text"></mdui-text-field>

소스

여러 줄 텍스트 필드

rows 속성으로 여러 줄 텍스트 필드의 행 수를 설정할 수 있습니다.

<mdui-text-field rows="3" label="Text Field"></mdui-text-field>

소스

autosize 속성을 추가하면 텍스트 필드가 입력 내용의 길이에 따라 자동으로 높이를 조정할 수 있습니다. min-rows 및 max-rows 속성으로 자동 높이 조정 시 최소 행 수와 최대 행 수를 지정할 수 있습니다.

<mdui-text-field autosize label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field autosize min-rows="2" max-rows="5" label="Text Field"></mdui-text-field>

소스

글자 수 통계

maxlength 속성으로 최대 글자 수를 설정한 경우 counter 속성을 추가하여 텍스트 필드 하단에 글자 수 통계를 표시할 수 있습니다.

<mdui-text-field maxlength="20" counter label="Text Field"></mdui-text-field>

소스

비밀번호 필드

type="password"일 때 toggle-password 속성을 추가하면 텍스트 필드 오른쪽에 비밀번호 표시 전환 버튼을 추가할 수 있습니다.

<mdui-text-field type="password" toggle-password label="Text Field"></mdui-text-field>

소스

API

속성

HTML 속성	JavaScript 프로퍼티	유형	기본값
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
텍스트 필드의 모양입니다. 기본값은 `filled`입니다. 사용 가능한 값: `filled`: 배경색이 채워진 텍스트 필드, 시각적 강조 효과가 높습니다. `outlined`: 테두리가 있는 텍스트 필드, 시각적 강조 효과가 낮습니다.
`type`	`type`	`'text' \| 'number' \| 'password' \| 'url' \| 'email' \| 'search' \| 'tel' \| 'hidden' \| 'date' \| 'datetime-local' \| 'month' \| 'time' \| 'week'`	`'text'`
텍스트 필드 입력 유형입니다. 기본값은 `text`입니다. 사용 가능한 값: `text`: 기본값. 텍스트 필드 `number`: 숫자만 입력 가능합니다. 가상 키보드가 있는 장치에서는 숫자 키보드가 표시됩니다. `password`: 비밀번호 입력용이며, 값이 가려집니다. `url`: URL 입력용이며, URL 형식을 확인합니다. 가상 키보드를 지원하는 장치에서는 해당 용도에 맞는 키보드가 표시됩니다. `email`: 이메일 주소 입력용이며, 이메일 형식을 확인합니다. 가상 키보드를 지원하는 장치에서는 해당 용도에 맞는 키보드가 표시됩니다. `search`: 검색 상자용입니다. 가상 키보드가 있는 장치에서 Enter 아이콘이 검색 아이콘으로 변경됩니다. `tel`: 전화번호 입력용입니다. 가상 키보드가 있는 장치에서는 전화 숫자 키보드가 표시됩니다. `hidden`: 컨트롤을 숨기지만 값은 서버에 제출됩니다. `date`: 날짜(년, 월, 일, 시간 제외)를 입력하는 컨트롤입니다. 지원되는 브라우저에서 활성화하면 날짜 선택기 또는 년/월/일 숫자 휠이 열립니다. `datetime-local`: 시간대를 제외한 날짜와 시간을 입력하는 컨트롤입니다. 지원되는 브라우저에서 활성화하면 날짜 선택기 또는 년/월/일 숫자 휠이 열립니다. `month`: 시간대 없이 년과 월을 입력하는 컨트롤입니다. `time`: 시간대 없이 시간을 입력하는 컨트롤입니다. `week`: 시간대 없이 년과 주차로 구성된 날짜를 입력하는 컨트롤입니다.
`name`	`name`	`string`	`''`
텍스트 필드 이름이며, 폼 데이터와 함께 제출됩니다.
`value`	`value`	`string`	`''`
텍스트 필드의 값이며, 폼 데이터와 함께 제출됩니다.
	`defaultValue`	`string`	`''`
기본값입니다. 폼을 재설정할 때 이 기본값으로 재설정됩니다. 이 프로퍼티는 JavaScript 프로퍼티로만 설정할 수 있습니다.
`label`	`label`	`string`	-
레이블 텍스트입니다.
`placeholder`	`placeholder`	`string`	-
플레이스홀더 텍스트입니다.
`helper`	`helper`	`string`	-
텍스트 필드 하단의 도움말 텍스트입니다. `slot="helper"`을 통해서도 설정할 수 있습니다.
`helper-on-focus`	`helperOnFocus`	`boolean`	`false`
포커스를 얻었을 때만 하단 도움말 텍스트를 표시할지 여부를 설정합니다.
`clearable`	`clearable`	`boolean`	`false`
텍스트 필드 콘텐츠를 비울 수 있는지 여부를 설정합니다.
`clear-icon`	`clearIcon`	`string`	-
텍스트 필드를 비울 수 있을 때 텍스트 필드 오른쪽에 표시되는 지우기 버튼의 Material Icons 아이콘 이름입니다. `slot="clear-icon"`을 통해서도 설정할 수 있습니다.
`end-aligned`	`endAligned`	`boolean`	`false`
텍스트를 오른쪽 정렬할지 여부를 설정합니다.
`prefix`	`prefix`	`string`	-
텍스트 필드의 접두사 텍스트입니다. 텍스트 필드가 포커스되거나 값이 있을 때만 표시됩니다. `slot="prefix"`을 통해서도 설정할 수 있습니다.
`suffix`	`suffix`	`string`	-
텍스트 필드의 접미사 텍스트입니다. 텍스트 필드가 포커스되거나 값이 있을 때만 표시됩니다. `slot="suffix"`을 통해서도 설정할 수 있습니다.
`icon`	`icon`	`string`	-
텍스트 필드 앞쪽 아이콘의 Material Icons 아이콘 이름입니다. `slot="icon"`을 통해서도 설정할 수 있습니다.
`end-icon`	`endIcon`	`string`	-
텍스트 필드 뒤쪽 아이콘의 Material Icons 아이콘 이름입니다. `slot="end-icon"`을 통해서도 설정할 수 있습니다.
`error-icon`	`errorIcon`	`string`	-
폼 필드 유효성 검사 실패 시 텍스트 필드 오른쪽에 표시되는 Material Icons 아이콘 이름입니다. `slot="error-icon"`을 통해서도 설정할 수 있습니다.
`form`	`form`	`string`	-
연결된 `<form>` 요소입니다. 이 속성 값은 동일한 페이지에 있는 `<form>` 요소의 `id`여야 합니다. 이 속성을 지정하지 않으면 이 요소는 `<form>` 요소의 자식 요소여야 합니다. 이 속성을 사용하면 요소를 `<form>` 요소의 자식뿐만 아니라 페이지의 어느 곳에나 배치할 수 있습니다.
`readonly`	`readonly`	`boolean`	`false`
읽기 전용 여부를 설정합니다.
`disabled`	`disabled`	`boolean`	`false`
입력 필드를 비활성화할지 여부를 설정합니다.
`required`	`required`	`boolean`	`false`
폼 제출 시 이 필드가 필수인지 여부를 설정합니다.
`rows`	`rows`	`number`	-
텍스트 필드의 고정 줄 수입니다.
`autosize`	`autosize`	`boolean`	`false`
입력 콘텐츠에 따라 텍스트 필드 높이를 자동으로 조정할지 여부를 설정합니다.
`min-rows`	`minRows`	`number`	-
`autosize`가 `true`일 때 텍스트 필드의 최소 줄 수입니다.
`max-rows`	`maxRows`	`number`	-
`autosize`가 `true`일 때 텍스트 필드의 최대 줄 수입니다.
`minlength`	`minlength`	`number`	-
허용되는 최소 문자 수입니다.
`maxlength`	`maxlength`	`number`	-
허용되는 최대 문자 수입니다.
`counter`	`counter`	`boolean`	`false`
글자 수 통계를 표시할지 여부를 설정합니다. `maxlength`가 지정된 경우에만 유효합니다.
`min`	`min`	`number`	-
`type`이 `number`일 때 허용되는 최소 숫자입니다.
`max`	`max`	`number`	-
`type`이 `number`일 때 허용되는 최대 숫자입니다.
`step`	`step`	`number`	-
`type`이 `number`일 때 숫자 증감 단계입니다.
`pattern`	`pattern`	`string`	-
폼 유효성 검사에 사용되는 정규 표현식입니다.
`toggle-password`	`togglePassword`	`boolean`	`false`
`type`이 `password`일 때 이 속성을 설정하면 일반 텍스트와 암호문 간에 전환할 수 있는 토글 버튼이 추가됩니다.
`show-password-icon`	`showPasswordIcon`	`string`	-
비밀번호 토글 버튼의 Material Icons 아이콘으로, 비밀번호가 일반 텍스트일 때 표시됩니다. `slot="show-password-icon"`을 통해서도 설정할 수 있습니다.
`hide-password-icon`	`hidePasswordIcon`	`string`	-
비밀번호 토글 버튼의 Material Icons 아이콘으로, 비밀번호가 암호문일 때 표시됩니다. `slot="hide-password-icon"`을 통해서도 설정할 수 있습니다.
`autocapitalize`	`autocapitalize`	`'none' \| 'sentences' \| 'words' \| 'characters'`	-
iOS의 비표준 속성으로, 텍스트의 첫 글자를 자동으로 대문자로 만들지 여부를 제어합니다. iOS5 이상 버전에서 유효합니다. 사용 가능한 값: `none`: 첫 글자 대문자 변환 비활성화 `sentences`: 문장 첫 글자 대문자 `words`: 단어 첫 글자 대문자 `characters`: 모든 문자 대문자
`autocorrect`	`autocorrect`	`string`	-
`input` 요소의 `autocorrect` 속성입니다.
`autocomplete`	`autocomplete`	`string`	-
`input` 요소의 `autocomplete` 속성입니다.
`enterkeyhint`	`enterkeyhint`	`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`	-
`input` 요소의 `enterkeyhint` 속성으로, 가상 키보드에서 Enter 키의 표시 텍스트 또는 아이콘을 사용자 정의하는 데 사용됩니다. 구체적인 표시 효과는 사용자의 기기와 언어에 따라 다릅니다. 사용 가능한 값: `enter`: 새 줄 삽입 `done`: 입력 완료, 가상 키보드 닫기 `go`: 입력 텍스트의 대상으로 이동 `next`: 다음 입력 항목으로 이동 `previous`: 이전 입력 항목으로 이동 `search`: 검색 결과로 이동 `send`: 텍스트 정보 전송
`spellcheck`	`spellcheck`	`boolean`	`false`
맞춤법 검사를 활성화할지 여부를 설정합니다.
`inputmode`	`inputmode`	`'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`	-
`input` 요소의 `inputmode` 속성으로, 가상 키보드의 유형을 사용자 정의하는 데 사용됩니다. 사용 가능한 값: `none`: 가상 키보드 없음. 자체 키보드 입력 컨트롤을 구현해야 할 때 유용합니다. `text`: 표준 텍스트 입력 키보드 `decimal`: 소수점 입력 키보드로, 숫자 외에 소수점 `.` 또는 천 단위 구분 기호 쉼표 `,`가 포함될 수 있습니다. `numeric`: 0-9 숫자 키보드 표시 `tel`: 전화 숫자 키보드, 0-9 숫자, 별표 `*` 또는 우물정자 `#` 키 포함 `search`: 검색 입력에 최적화된 가상 키보드, 제출 버튼은 일반적으로 `search` 또는 "검색"을 표시합니다. `email`: 이메일 주소 입력에 최적화된 가상 키보드, 일반적으로 `@ .` 등의 키가 있습니다. `url`: URL 입력에 최적화된 가상 키보드, 일반적으로 `. / #` 등의 키가 있습니다.
	`validity`	`ValidityState`	-
폼 유효성 검사 상태 객체입니다. 자세한 내용은 `ValidityState`를 참조하십시오.
	`validationMessage`	`string`	-
폼 유효성 검사를 통과하지 못하면 오류 메시지가 포함되고, 통과하면 빈 문자열입니다.
	`valueAsNumber`	`number`	-
현재 값을 가져와 `number` 유형으로 변환하거나 `number` 유형의 값을 설정합니다. 값을 `number` 유형으로 변환할 수 없으면 `NaN`을 반환합니다.
`autofocus`	`autofocus`	`boolean`	`false`
페이지 로드 후 자동으로 포커스를 받을지 여부를 지정합니다.
`tabindex`	`tabIndex`	`number`	-
Tab 키를 사용하여 포커스를 이동할 때 요소의 순서를 지정합니다.

메서드

이름	매개변수	반환값
`select`		`void`
텍스트 필드의 텍스트를 선택합니다.
`setSelectionRange`	`start: number` `end: number` `direction: 'forward' \| 'backward' \| 'none'`	`void`
텍스트 필드에서 특정 범위의 콘텐츠를 선택합니다.
`setRangeText`	`replacement: string` `start: number` `end: number` `selectMode: 'select' \| 'start' \| 'end' \| 'preserve'`	`void`
텍스트 필드에서 특정 범위의 텍스트를 새 텍스트로 바꿉니다.
`checkValidity`		`boolean`
폼 필드가 유효성 검사를 통과하는지 확인합니다. 통과하지 못하면 `false`를 반환하고 `invalid` 이벤트를 트리거합니다. 통과하면 `true`를 반환합니다.
`reportValidity`		`boolean`
폼 필드가 유효성 검사를 통과하는지 확인합니다. 통과하지 못하면 `false`를 반환하고 `invalid` 이벤트를 트리거합니다. 통과하면 `true`를 반환합니다. 유효성 검사를 통과하지 못하면 컴포넌트에 유효성 검사 실패 메시지가 표시됩니다.
`setCustomValidity`	`message: string`	`void`
사용자 정의 오류 메시지 텍스트를 설정합니다. 이 텍스트가 비어 있지 않으면 필드가 유효성 검사를 통과하지 못했음을 나타냅니다.
`click`		`void`
마우스 클릭을 시뮬레이션합니다.
`focus`	`options: FocusOptions` (선택사항)	`void`
현재 요소에 포커스를 설정합니다. 객체를 인자로 전달할 수 있으며, 객체의 속성은 다음과 같습니다: `preventScroll`: 기본적으로 요소가 포커스를 받으면 페이지가 스크롤되어 해당 요소가 화면에 표시됩니다. 페이지 스크롤을 방지하려면 이 속성을 `true`로 설정하십시오.
`blur`		`void`
현재 요소에서 포커스를 제거합니다.

이벤트

이름
`focus`
포커스를 얻었을 때 발생합니다.
`blur`
포커스를 잃었을 때 발생합니다.
`change`
텍스트 필드의 값이 변경되고 포커스를 잃으면 발생합니다.
`input`
텍스트 필드의 값이 변경될 때 발생합니다.
`invalid`
폼 필드 유효성 검사를 통과하지 못했을 때 발생합니다.
`clear`
`clearable` 속성으로 생성된 지우기 버튼을 클릭할 때 발생합니다. `event.preventDefault()`를 호출하여 텍스트 필드 비우기를 막을 수 있습니다.

Slots

이름
`icon`
왼쪽 아이콘
`end-icon`
오른쪽 아이콘
`error-icon`
유효성 검사 실패 상태의 오른쪽 아이콘
`prefix`
왼쪽 텍스트
`suffix`
오른쪽 텍스트
`clear-button`
지우기 버튼
`clear-icon`
지우기 버튼 내의 아이콘
`toggle-password-button`
비밀번호 표시 상태 토글 버튼
`show-password-icon`
비밀번호 표시 상태에서 비밀번호 표시 상태 토글 버튼 내의 아이콘
`hide-password-icon`
비밀번호 숨김 상태에서 비밀번호 표시 상태 토글 버튼 내의 아이콘
`helper`
하단의 도움말 텍스트

CSS Parts

이름
`container`
텍스트 필드 컨테이너
`icon`
왼쪽 아이콘
`end-icon`
오른쪽 아이콘
`error-icon`
유효성 검사 실패 상태의 오른쪽 아이콘
`prefix`
왼쪽 텍스트
`suffix`
오른쪽 텍스트
`label`
상단의 레이블 텍스트
`input`
내부의 `<input>` 또는 `<textarea>` 요소
`clear-button`
지우기 버튼
`clear-icon`
지우기 버튼 내의 아이콘
`toggle-password-button`
비밀번호 표시 상태 토글 버튼
`show-password-icon`
비밀번호 표시 상태에서 비밀번호 표시 상태 토글 버튼 내의 아이콘
`hide-password-icon`
비밀번호 숨김 상태에서 비밀번호 표시 상태 토글 버튼 내의 아이콘
`supporting`
하단 보조 정보 컨테이너(helper, error, counter 포함)
`helper`
하단의 도움말 텍스트
`error`
하단의 오류 설명 텍스트
`counter`
하단 오른쪽의 글자 수 통계

이전 장

Tabs 탭

다음 장

Tooltip 툴팁