마스크 입력

입력 마스크(Input Mask)는 사용자로부터 기대되는 입력 형식을 정의하는 문자들의 문자열입니다. 입력 마스크를 사용하면 데이터 오류 가능성을 줄이고 데이터베이스의 일관성을 유지할 수 있어, 데이터 분석 및 처리 과정이 더 쉬워집니다. 마스크는 패턴, 플레이스홀더, 마스킹 문자 등으로 구성된 사용자 지정 규칙을 사용해 생성할 수 있습니다.

SpreadJS는 mask 속성과 pattern 옵션을 사용해 입력 마스크를 설정할 수 있습니다. placeholder 옵션을 사용하면 플레이스홀더 문자를 지정할 수 있습니다. 플레이스홀더는 입력 필드에 표시되어 예상 입력 형식을 나타내며, 사용자가 해당 형식에 맞게 입력하도록 안내합니다. 사용자가 플레이스홀더를 지정하지 않으면, SpreadJS는 기본적으로 "_" 문자를 사용합니다. excludePlaceholder 옵션을 사용하면 입력 문자열에 플레이스홀더 문자를 포함할지 여부를 선택할 수 있습니다.

예를 들어, 마스크 패턴이 "000000"이고 플레이스홀더가 "_"일 경우, 빈 입력 필드는 "______"처럼 표시되어 6자리 숫자 입력이 필요함을 나타냅니다. excludePlaceholder 옵션이 기본값인 false일 때 사용자가 "1234"를 입력하고 편집 모드에서 나가면 입력값은 "1234__"로 저장됩니다. 반면 이 옵션이 true로 설정되면 입력값은 "1234"로 저장되어 플레이스홀더 문자가 제외됩니다.

마찬가지로, excludeLiteral 을 true로 설정하면 리터럴 문자도 제외할 수 있습니다. 리터럴은 해당 위치에서 그대로 표시되며 다른 문자로 대체할 수 없는 문자입니다. 예를 들어, 전화번호에 사용되는 괄호나 하이픈, 날짜 형식에서의 슬래시(/) 등이 리터럴 문자에 해당합니다.

다음 코드는 입력 마스크를 설정하는 방법을 보여줍니다:

    style = new GC.Spread.Sheets.Style();
    style.mask = {
        pattern: "[a0]{8}",
        excludePlaceholder: true
    };
    sheet.setStyle(14, 0, style);

    style1 = new GC.Spread.Sheets.Style();
    style1.mask = {
        pattern: "Au\\t\\hor: (Chris|Icey|Victor|Ian|Johnson|Ivan)",
        excludeLiteral: true
    };
    sheet.setStyle(15, 0, style1);

사용자가 커서가 플레이스홀더 위치에 있을 때 문자를 입력하면, 해당 위치의 플레이스홀더 문자가 새로운 문자로 대체됩니다. 다른 위치일 경우에는 새 문자가 삽입됩니다. 사용자의 입력이 패턴과 일치하지 않는 경우, SpreadJS는 입력 문자열의 왼쪽부터 오른쪽 방향으로 패턴과 일치하는 부분만 유지하고, 나머지 유효하지 않은 부분은 제거합니다.

하지만 사용자가 일부 텍스트를 삭제하는 경우, 현재 제한된 입력 범위 내의 내용만 삭제됩니다. 예를 들어, 패턴이 'a{3}0{3}'일 경우 사용자가 입력의 가장 왼쪽 문자부터 삭제하기 시작하면, SpreadJS는 첫 번째 제한인 'a{3}'에 해당하는 세 문자를 삭제할 수 있도록 허용합니다. 나머지 입력을 삭제하려면, 사용자는 커서를 다음 제한 항목의 시작 위치로 옮겨야 합니다.

패턴이 유효한지 확인하기 위해, SpreadJS는 validatePattern이라는 정적 메서드를 제공합니다. 다음 코드는 validatePattern 메서드를 사용해 패턴을 유효성 검사하는 방법을 보여줍니다:

let sheet = spread.getActiveSheet();
let style = new GC.Spread.Sheets.Style();
let pattern = 'ISBN 0-00000-000-0';
let verifyResult = GC.Spread.Sheets.InputMask.validatePattern('[a0_]{8}');
if (verifyResult.success) {
  style.mask = {
    pattern: 'ISBN 0-00000-000-0'
  };
  sheet.setStyle(0,0,style);
}

마스크 패턴은 두 가지 유형으로 나뉩니다:

• 문자열 패턴

• 날짜 패턴

문자열 패턴

문자열 패턴은 입력 형식을 정의하는 가장 간단한 방식이며, 최소 패턴 단위를 사용해 구성됩니다. 최소 패턴 단위는 문자 제한과 선택적으로 문자 길이 제한으로 이루어집니다. 문자 길이 제한이 지정되지 않으면 기본적으로 한 글자로 간주됩니다.

다음 표는 문자 제한과 길이 제한을 사용하여 패턴을 만드는 다양한 규칙을 설명합니다.

날짜 패턴

날짜 패턴은 날짜 및 시간 값을 포맷하는 방식을 지정하는 방법입니다. 이는 고정 형식 패턴이며 문자 길이 제한은 허용되지 않습니다. 날짜 패턴의 경우, SpreadJS는 날짜 규칙에 따라 사용자 입력을 자동으로 고정합니다. 단, yyyy, MM과 같은 날짜 시간 항목을 하나의 패턴에서 중복해서 사용해서는 안 됩니다. 예: "yyyy/MM/dd yyyy"는 "yyyy"가 두 번 사용되었기 때문에 잘못된 패턴입니다.

아래 표는 날짜 패턴의 다양한 마스킹 문자와 그 사용 방법을 샘플 패턴과 함께 설명합니다.

명명된 패턴

사용자는 명명된 패턴을 정의하고 이를 다른 패턴 내에서 재사용할 수 있습니다.

하지만 주의할 점은, 패턴 내의 문자열이 namedPatterns에 정의된 이름과 일치하면, 해당 이름은 해당 명명된 패턴으로 자동 대체됩니다. 따라서 일반적인 단어나 자주 사용되는 문자열과 중복되지 않도록 가능한 반복 가능성이 적은 이름으로 정의하는 것이 좋습니다.

SpreadJS는 정의된 모든 명명된 패턴의 목록을 가져올 수 있도록 정적 메서드 getNamedPatterns를 제공합니다.

// 명명된 패턴 정의 
GC.Spread.Sheets.InputMask.namedPattern('enterdate', 'MM/dd/yyyy hh:mm tt');
let style = new GC.Spread.Sheets.Style();
style.mask = {
  // reuse it in another pattern
  pattern: '(start): enterdate'
};
sheet.setStyle(0, 0, style);

수식 패턴

SpreadJS는 "=" 기호로 시작하는 **수식 형태의 패턴(Formula Pattern)**도 지원합니다. 즉, 입력 마스크 패턴이 동적으로 수식으로 구성될 수 있습니다. 예를 들어, 워크시트의 셀 A1~A3에 "Chris", "Icey", "Ian"이라는 작가 이름이 입력되어 있다면 다음 두 패턴은 동일한 결과를 나타냅니다.

패턴이 유효한지 확인하는 정적 메서드인 validatePattern 은 수식 패턴을 지원하지 않습니다. 수식 패턴을 평가하려면 validatePattern 메서드를 호출하기 전에GC.Spread.Sheets.CalcEngine.evaluateFormula를 사용하시기 바랍니다.

패턴 예시

이어지는 표에서 주요 마스크 패턴을 빠르게 참고할 수 있습니다.