텍스트 필드 위젯(테마 적용 가능)
텍스트 필드 위젯은 양식 내에서 일반적으로 사용되는 입력 요소입니다. 텍스트 필드를 사용하면 사용자가 매쉬업에 텍스트를 입력할 수 있습니다. Text 속성을 사용하여 필드 내에서 텍스트를 설정하거나 검색할 수 있습니다. 텍스트 영역 위젯과 달리 텍스트 필드는 한 줄로 제한됩니다. 공통 위젯 속성 외에도 다음과 같은 방법으로 속성을 사용하여 위젯을 구성할 수 있습니다.
• 최대 문자 수를 구성하고 카운터를 추가합니다.
• 텍스트를 데이터 서비스, 함수 및 기타 위젯의 입력으로 사용합니다.
• 값이 설정되지 않으면 힌트 텍스트를 표시합니다.
• 텍스트 지우기 버튼을 추가합니다.
• 읽기 전용 모드를 사용합니다.
• 암호와 같은 중요한 정보에 대한 입력을 숨깁니다.
• 마스크 패턴을 정의하여 입력이 특정 형식인지 확인합니다.
 |
텍스트 필드 위젯은 플랫폼에서 표준 위젯으로, 웹 부품 SDK에서 가져올 수 있는 웹 부품으로 사용할 수 있습니다.
|
실행 시간에 위젯 값이 업데이트될 때 다음 위젯 이벤트를 사용하여 데이터 서비스 또는 함수를 실행할 수 있습니다.
• EnterKeyPressed - Enter 키를 누를 때 트리거됩니다.
• FocusLost - 위젯 외부의 영역을 클릭하거나 Tab 키를 누를 때 트리거됩니다.
이벤트 작업
텍스트 필드 위젯은 두 개의 바인딩 가능 이벤트를 트리거합니다.
• Changed - 문자가 추가되거나 제거될 때 트리거합니다.
• EnterKeyPressed - 사용자가 Enter 키를 누를 때 트리거합니다.
위젯 이벤트를 사용하면 위젯 내에서 함수, 데이터 서비스 또는 서비스를 트리거할 수 있습니다. 예를 들어, 이벤트를 유효성 검사기 함수에 바인딩하여 입력한 대로 또는 Enter 키를 누를 때 입력의 유효성을 검사할 수 있습니다.
읽기 전용 모드 사용
ReadOnly 속성을 사용하면 런타임에 텍스트가 변경되지 않도록 할 수 있습니다. 예를 들어, 이 속성을 사용하면 전환 버튼이 활성화되거나 매쉬업에서 확인란이 선택될 때까지 변경되지 않습니다. 읽기 전용이 사용되면 텍스트를 선택하고 복사할 수 있지만 현재 값을 편집, 잘라내기 또는 삭제할 수 없습니다. 읽기 전용 텍스트 필드의 텍스트 값을 변경하려면 디자인 타임에 Text 속성의 값을 입력합니다. 데이터 소스를 속성에 바인딩하여 런타임에 텍스트 값을 변경할 수도 있습니다.
문자 수 제한 설정
다음 방법 중 하나를 사용하면 텍스트 필드의 입력을 특정 문자 수로 제한할 수 있습니다.
• MaxNumberOfCharacters 속성을 임의의 숫자 값으로 설정합니다. 기본적으로 텍스트 필드는 최대 100자를 지원합니다.
• Mask 속성을 사용하여 마스크 패턴을 정의합니다. 패턴 내의 특수 문자 수는 문자 제한을 설정하는 데 사용됩니다.
텍스트 필드에 카운터 추가
텍스트 필드에 문자 수를 표시하는 카운터를 추가하려면 Counter 속성을 True로 설정합니다. MaxNumberOfCharacters 속성은 공백을 포함한 문자 제한을 설정하는 데 사용됩니다. 다음 이미지는 카운터가 표시되고 최대 문자 수가 10인 텍스트 필드 위젯을 보여줍니다.
문자 제한에 도달하면 카운터 색상이 변경됩니다.
텍스트 지우기 버튼 추가
ShowClearText 속성을 사용하면 위젯의 입력 상자에 텍스트 버튼을 추가할 수 있습니다. 입력 필드에 값이 있으면 위젯 오른쪽에 버튼이 자동으로 표시됩니다. 이를 통해 사용자는 위젯 내에서 기존 텍스트를 빠르게 제거할 수 있습니다.
아이콘 추가
Icon 속성을 사용하여 텍스트 필드 내에 아이콘을 표시할 수 있습니다. 아이콘은 위젯의 왼쪽에 자동으로 나타납니다. 플랫폼에서 사용할 수 있도록 제공된 SVG 아이콘에서 아이콘을 선택할 수 있습니다. 이러한 아이콘에 대한 자세한 내용은 SVG 아이콘 사용을 참조하십시오.
텍스트 필드 입력 패턴 구성
Mask 속성을 사용하면 숫자, 영문자 및 영숫자 문자에 대한 입력 패턴을 지정할 수 있습니다. 패턴을 정의하면 입력 상자에 자리 표시자 가이드가 추가됩니다. 가이드는 사용자가 텍스트 필드에 입력할 수 있는 텍스트 패턴을 나타내는 데 사용되는 선입니다. 이 속성은 필수 패턴 외에도 텍스트 필드 내의 문자 수를 설정합니다. 다음과 같은 특수 문자를 사용하여 패턴을 생성할 수 있습니다.
• a - 영문자
• 9 - 숫자
• * - 영숫자
패턴을 생성하려면 필수 입력을 나타내는 문자열로 특수 문자를 결합합니다. 예를 들어, 다음 패턴은 여러 유형의 입력을 나타냅니다.
• 9999 - 4자리 숫자
• ***** - 5개의 영숫자 문자
• 99–aa - 두 자리 숫자 뒤에 구분 기호 대시와 두 개의 영문자가 옵니다.
다음 이미지는 런타임에 3자리 숫자가 4개 포함된 999–999–999–999 숫자 패턴에 대한 가이드를 보여줍니다.
패턴은 자릿수와 함께 숫자의 형식을 설정하는 데 사용됩니다. 이 예에서는 256120233234와 같은 12자리 숫자를 입력할 수 있습니다. 입력할 때 밑줄(_) 가이드는 숫자로 대체됩니다.
디자인 타임 동안 패턴 내에서 설정한 총 문자 수를 기준으로 표시기 가이드가 표시됩니다. 패턴보다 적은 자릿수를 입력하면 입력이 불완전하게 유지됩니다. 마스크를 사용하여 전화 번호 또는 우편 번호와 같은 특정 문자 수로 된 패턴을 정의해야 합니다. 입력이 특정 문자 수(예: 금액)가 아닌 경우 마스크를 사용하지 마십시오.
|
|
마침표, 대시, 슬래시 등의 여러 기호 유형을 문자 간 구분 기호로 사용할 수 있습니다.
|
숫자 입력 모드 활성화
텍스트 필드 위젯을 숫자만 입력하도록 구성할 수 있습니다. 이를 통해 사용자가 유효한 숫자 데이터를 입력하도록 지원하고 유효성 검사를 간소화할 수 있습니다. 텍스트 필드에 대해 숫자 입력을 활성화하려면 위젯을 선택한 다음 속성 패널에서 NumericInputMode 속성을 활성화합니다. 이 모드에 대한 추가 구성 속성이 표시됩니다.
AllowDecimals를 사용하면 사용자가 소수 값을 입력할 수 있고, AllowNegativeValues를 사용하면 음수를 허용할 수 있습니다. 소수점 이하 몇 자리까지 표시할지 정의하려면 DecimalPlaces를 설정합니다. 값의 범위를 제한하려면 MinValue 및 MaxValue 유효성 검사 속성을 사용합니다. 또한 MinValueFailureMessage 및 MaxValueFailureMessage를 사용하여 허용된 범위를 벗어난 값을 입력할 때 표시되는 메시지를 사용자 정의할 수 있습니다.
숫자 형식을 제어하려면 FormatToken 속성을 사용합니다. 또한 사용자가 바로 가기 키를 사용할 때 값이 얼마나 변할지를 제어하려면 StepSize 속성을 설정할 수 있습니다. NumericValue 속성을 사용하면 필드를 데이터 소스에 바인딩하여 값을 동적으로 추적하거나 업데이트할 수 있습니다.
텍스트 필드 위젯 크기 조정
AllowResize 속성을 사용하여 사용자가 텍스트 필드 위젯의 크기를 가로로 조정할 수 있는지 여부를 제어할 수 있습니다. 이 속성을 true로 설정하면 위젯에 가로 방향 크기 조절 핸들이 표시되어 사용자가 매쉬업 인터페이스에서 너비를 직접 조정할 수 있습니다. 이를 통해 입력 공간의 유연성이 필요한 레이아웃에서 유용성을 향상시킬 수 있습니다.
다음 표에는 텍스트 필드 위젯 속성이 나열되어 있습니다.
|
속성 이름
|
설명
|
기본 유형
|
기본값
|
바인딩 가능 여부 (Y/N)
|
로컬리제이션 가능 여부 (Y/N)
|
||
|---|---|---|---|---|---|---|---|
|
Text
|
텍스트 필드에 표시되는 텍스트입니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
||
|
Label
|
텍스트 필드의 레이블에 표시되는 텍스트입니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
||
|
AllowResize
|
사용자가 런타임에 텍스트 필드의 크기를 조정할 수 있는 컨트롤을 추가합니다.
|
BOOLEAN
|
False
|
N
|
N
|
||
|
Counter
|
텍스트 필드에 입력되는 문자의 수를 세고 표시합니다.
|
BOOLEAN
|
False
|
N
|
N
|
||
|
MaxNumberOfCharacters
|
텍스트 필드의 최대 문자 수를 설정할 수 있습니다.
|
NUMBER
|
100
|
Y
|
N
|
||
|
NumericInputMode
|
위젯에 대한 숫자 입력 모드를 활성화합니다. 이 모드에서는 숫자 입력만 지원됩니다.
|
위젯을 숫자 입력 모드로 설정합니다. 이 모드에서는 숫자만 허용됩니다.
|
False
|
N
|
N
|
||
|
NumericValue
|
위젯의 숫자 값을 설정하거나 읽어들입니다.
|
NUMBER
|
0
|
Y
|
N
|
||
|
AllowDecimals
|
숫자 입력 모드를 사용할 때 소수 값을 허용합니다.
|
BOOLEAN
|
False
|
N
|
N
|
||
|
AllowNegativeValues
|
숫자 입력 모드를 사용할 때 음수 값을 허용합니다.
|
BOOLEAN
|
False
|
N
|
N
|
||
|
DecimalPLaces
|
숫자 값에 허용되는 소수점 자릿수를 설정합니다.
|
NUMBER
|
0
|
N
|
N
|
||
|
FormatToken
|
숫자 값 형식에 로컬리제이션 토큰을 입력합니다. 형식 토큰이 설정되면 AllowDecimals, AllowNegativeValues, DecimalPlaces 속성을 무시합니다. 지원되는 형식에 대한 자세한 내용은 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat의 Intl.NumberFormat 객체를 참조하십시오.
|
STRING
|
해당 없음
|
N
|
N
|
||
|
StepSize
|
바로 가기 키를 사용할 때 숫자 값의 단계 크기를 제어합니다.
|
NUMBER
|
1
|
N
|
N
|
||
|
HintText
|
필드에 입력해야 하는 내용에 대해 설명하는 자리 표시자 텍스트를 표시합니다.
|
STRING
|
해당 없음
|
N
|
N
|
||
|
Disabled
|
이 속성을 사용하면 매쉬업에서 위젯을 비활성화할 수 있습니다. 위젯이 매쉬업에 표시되지만 클릭할 수는 없습니다.
|
BOOLEAN
|
False
|
Y
|
N
|
||
|
ReadOnly
|
텍스트 필드를 읽기 전용으로 설정하면 사용자가 텍스트를 편집할 수 없습니다.
|
BOOLEAN
|
False
|
N
|
N
|
||
|
Password
|
텍스트 필드 입력을 숨길 수 있습니다.
|
BOOLEAN
|
False
|
N
|
N
|
||
|
ShowClearText
|
텍스트 필드 안에 지우기 버튼을 추가하여 버튼을 클릭할 경우 실행 시간에 사용자가 필드의 텍스트를 지울 수 있습니다.
|
BOOLEAN
|
True
|
N
|
N
|
||
|
LabelAlignment
|
레이블을 왼쪽, 오른쪽 또는 가운데에 정렬할 수 있습니다.
|
STRING
|
Left
|
N
|
N
|
||
|
TextAlignment
|
필드의 왼쪽 또는 오른쪽에 텍스트를 정렬할 수 있습니다.
|
STRING
|
Left
|
N
|
N
|
||
|
Mask
|
텍스트 필드에 미리 정의된 문자를 설정할 수 있습니다. 속성 구성 필드에 영문자 입력을 설정하려면 "a", 숫자 입력은 "9", 영숫자 입력은 "*"를 사용합니다.
|
STRING
|
해당 없음
|
N
|
N
|
||
|
TabSequence
|
사용자가 Tab 키를 누를 때 위젯이 강조 표시되는 순서입니다.
|
NUMBER
|
해당 없음
|
N
|
N
|
||
|
CustomClass
|
위젯의 최상위 div에 CSS를 정의할 수 있습니다. 공백으로 구분하여 여러 클래스를 입력할 수 있습니다.
|
STRING
|
해당 없음
|
Y
|
N
|
||
|
EnterKeyPressed
|
텍스트 값을 편집하는 동안 Enter 키를 누를 때 트리거되는 이벤트입니다.
|
해당 없음
|
해당 없음
|
Y
|
N
|
||
|
FocusLost
|
텍스트 값을 편집하는 동안 사용자가 Tab 키를 누르거나 위젯 외부의 영역을 클릭하여 포커스를 변경할 때 트리거되는 이벤트입니다.
|
해당 없음
|
해당 없음
|
Y
|
N
|
||
|
Changed
|
이 위젯의 데이터가 수정될 때 트리거되는 이벤트입니다.
|
해당 없음
|
해당 없음
|
Y
|
N
|
||
|
ResetToDefaultValue
|
이 위젯에 대한 입력을 기본값으로 재설정합니다.
|
해당 없음
|
해당 없음
|
Y
|
N
|
||
|
Width
|
위젯의 너비입니다.
|
NUMBER
|
273
|
N
|
N
|
||
|
Height
|
위젯의 높이입니다. 기본적으로 자동 계산됩니다. 텍스트 필드에 레이블을 포함하면 높이가 증가합니다.
|
NUMBER
|
자동 크기 조정
|
N
|
N
|
||
|
TooltipField
|
위젯을 마우스로 가리킬 때 표시되는 도구 설명 텍스트를 설정합니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
||
|
TooltipIcon
|
위젯의 도구 설명에 대한 아이콘 이미지를 설정합니다.
이미지를 추가하거나 이미지 URL 경로를 지정할 수 있습니다.
|
미디어 엔티티
|
해당 없음
|
N
|
N
|
||
|
Icon
|
텍스트 상자 안에 표시할 아이콘을 지정합니다.
|
SVG 아이콘 목록
|
해당 없음
|
N
|
N
|
위젯 데이터 유효성 검사
공통 속성 외에도 MaxLength 및 MinLength 유효성 검사 속성을 사용하여 텍스트 필드 위젯 내 문자 수의 유효성을 검사할 수 있습니다.
MaxLengthFailureMessage 및 MinLengthFailureMessage 속성을 사용하여 기본 실패 메시지를 사용자 정의할 수 있습니다. ${value} 매개 변수를 사용하여 최대값 및 최대값이 메시지 내에 표시됩니다.
공통 유효성 검사 속성 사용에 대한 자세한 내용은 위젯에 유효성 검사 적용을 참조하십시오.
다음 표에는 유효성 검사 패널에서 사용할 수 있는 유효성 검사 속성이 나와 있습니다.
|
속성
|
설명
|
기본 유형
|
기본값
|
바인딩 가능 여부(Y/N)
|
로컬리제이션 가능 여부(Y/N)
|
|---|---|---|---|---|---|
|
CriteriaMessage
|
유효성 검사 조건 및 유효성 검사 실패 시 표시할 메시지입니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
|
CriteriaMessageDetails
|
유효성 검사 조건 및 실패 메시지에 대해 표시할 세부 정보입니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
|
MaxLength
|
텍스트 필드 값의 최대 길이입니다.
|
STRING
|
해당 없음
|
Y
|
N
|
|
MaxLengthFailureMessage
|
현재 값이 최대 문자 길이를 초과할 때 표시할 메시지입니다.
|
STRING
|
${value} characters is the maximum
|
Y
|
Y
|
|
MinLength
|
텍스트 필드 값의 최소 길이입니다.
|
STRING
|
해당 없음
|
Y
|
N
|
|
MinLengthFailureMessage
|
현재 값이 최소 문자 길이 미만일 때 표시할 메시지입니다.
|
STRING
|
${value} characters is the minimum
|
Y
|
Y
|
|
MaxValue
|
위젯의 최대 숫자 값을 설정합니다.
|
NUMBER
|
해당 없음
|
Y
|
N
|
|
MaxValueFailureMessage
|
숫자 값이 최대값을 초과할 때 표시할 메시지입니다.
|
STRING
|
값이 최대값을 초과합니다.
|
Y
|
Y
|
|
MinValue
|
위젯의 최소 숫자 값을 설정합니다.
|
NUMBER
|
Y
|
N
|
|
|
MinValueFailureMessage
|
숫자 값이 최소값 미만일 때 표시할 메시지입니다.
|
STRING
|
Y
|
Y
|
|
|
RequiredMessage
|
필수 값이 true로 설정되고 항목이 선택되지 않았을 때 표시할 메시지입니다.
|
STRING
|
값은 필수입니다.
|
Y
|
Y
|
|
ShowValidationCriteria
|
텍스트 필드를 편집할 때 필수 입력에 대한 힌트 메시지를 표시합니다.
|
BOOLEAN
|
False
|
Y
|
N
|
|
ShowValidationFailure
|
입력한 값이 유효성 검사에 실패할 때 실패 메시지를 표시합니다.
|
BOOLEAN
|
False
|
Y
|
N
|
|
ShowValidationSuccess
|
입력한 값이 유효성 검사에 성공할 때 성공 메시지를 표시합니다.
|
BOOLEAN
|
False
|
Y
|
N
|
|
SuccessMessage
|
유효성 검사에 성공했을 때 표시할 메시지입니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
|
SuccessMessageDetails
|
유효성 검사 성공 메시지에 관한 추가 정보를 표시하는 보조 메시지입니다.
|
STRING
|
해당 없음
|
Y
|
Y
|
|
Validate
|
위젯 값이 변경될 때 트리거되는 바인딩 가능한 이벤트입니다. 이 이벤트를 서비스 또는 함수에 바인딩하여 유효성 검사 패턴 또는 식을 적용합니다.
|
이벤트입니다.
|
해당 없음
|
Y
|
N
|
|
ValidationCriteriaIcon
|
유효성 검사 조건에 대해 힌트 메시지 내에 표시할 SVG 아이콘을 설정합니다.
|
IMAGELINK
|
info
|
N
|
N
|
|
ValidationFailureIcon
|
유효성 검사에 실패했을 때 상태 메시지 내에 표시할 SVG 아이콘을 설정합니다.
|
IMAGELINK
|
error
|
N
|
N
|
|
ValidationOutput
|
위젯 유효성 검사의 출력을 검색합니다. 반환된 값은 Undefined, Unvalidated, Valid 또는 Invalid입니다.
|
STRING
|
해당 없음
|
Y
|
N
|
|
ValidationState
|
유효성 검사 상태를 설정하는 바인딩 가능한 속성입니다. 이 속성을 Undefined, Unvalidated, Valid 또는 Invalid로 설정할 수 있습니다.
|
STRING
|
Undefined
|
Y
|
N
|
|
ValidationSuccessIcon
|
유효성 검사에 성공했을 때 상태 메시지 내에 표시할 SVG 아이콘을 선택합니다.
|
IMAGELINK
|
success
|
N
|
N
|
|
ValueRequired
|
목록에서 항목을 선택해야 합니다.
|
BOOLEAN
|
False
|
Y
|
N
|