入力マスク

入力マスクは、期待する入力形式を定義する書式文字列です。入力をマスクすると、入力ミスによるエラーの可能性が減り、データベース内の一貫性が維持されるため、データの解析、処理などを容易に実行できます。 入力マスクは、パターン、プレースホルダー、マスク文字などで構成され、ユーザー定義のルールを使用して作成できます。

SpreadJS は、入力マスクを設定するための mask プロパティと pattern オプションを提供します。placeholder オプションを使用してプレースホルダーを指定します。プレースホルダーは、入力フィールドで表示される文字列で、予期される入力形式を表し、その形式の値を入力するようにユーザーをガイドします。ユーザーが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 は現在のフィールドの最初の 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);
}

マスクパターンは2種類あります。

• 文字列パターン

• 日付パターン

文字列パターン

文字列パターンは入力形式を定義する最も簡単な方法であり、最小パターン単位を使用して構築できます。最小パターン単位は、文字制限と、文字長制限（オプション）で構成されます。 文字長制限を指定しない場合は1文字と考慮します。次の表では、2 種類の制限を使用してパターンを作成するさまざまなルールを定義しています。

動的なパターンでは、

• プレースホルダーは、最小長のみを表します。 たとえば、0{2,10} で「__」が表示され、0{0,1} の場合何も表示されません。

• {n,m} の「m」を指定しない場合、動的パターンの最大長は 2147483648 になります。

日付パターン

日付パターンは、日付値と時刻値の形式を指定します。固定形式のパターンであり、文字長の制限を受け入れません。日付パターンの場合、SpreadJS は日付ルールを元にユーザー入力を自動的に修正します。ただし、yyyy、MM などの日付時刻項目を 1 つのパターンで繰り返して使用できません。たとえば、「yyyy/MM/dd yyyy」は、「yyyy」が 2 回使用されているので、無効なパターンです。

次の表は、日付パターンのマスク文字とその使用を例で説明します。

名前付きパターン

名前付きパターンを定義し、他のパターンで再利用することもできます。ただし、namedPatterns 内のいずれかの名前と一致する文字列がパターン内にある場合、マスクはそれを名前付きパターンに置き換えます。 したがって、繰り返しの可能性を最小限に抑えた名前でパターンを定義することをお勧めします。すべての名前パターンのリストを取得するには、SpreadJS に静的メソッド getNamedPatterns が用意されています。

// 名前付きパターンを定義します。
GC.Spread.Sheets.InputMask.namedPattern('enterdate', 'MM/dd/yyyy hh:mm tt');
let style = new GC.Spread.Sheets.Style();
style.mask = {
  // 別のパターンで再利用します。
  pattern: '(start): enterdate'
};
sheet.setStyle(0, 0, style);

数式パターン

SpreadJSは数式パターン（数式形式で作成され、「=」で始まるパターン）に対応します。例えば、ワークシートのA1からA3のセルの値が「Chris」、「Icey」、「Ian」である場合、次の2つのパターンは同じ結果になります。

パターンの有効性を確認するvalidatePatternの静的メソッドは、数式パターンに対応しません。数式パターンの有効性を確認するには、validatePatternメソッドを呼び出す前に、GC.Spread.Sheets.CalcEngine.evaluateFormulaを使用します。

• () パターン内の文字は静的文字列なので、(am|pm) はエスケープ文字を使用せずにそのまま記述できます。

• グループ制限で一つのグループ項目である場合、静的文字列として見なされます。

• デフォルトで、マスク部分にグループ制限の最初の項目を表示します。ユーザーの入力を受け取ると、マスク部分にはグループ項目のテキストが自動的に補完されます。

• 入力エクスペリエンスを向上させるため、グループ制限では大文字と小文字が区別されません。

• 静的文字列またはグループ テキストの場合、SpreadJS は数量子をサポートしないので、1234{1,5}、(12|34){1,5} などのパターンを設定しないでください。

• SpreadJS は、グループ「()」とオプションの「[]」のネストをサポートしていません。

• マスクされたセルが編集モードに入ると、内部の数式テキストボックスは禁止され、外部の数式テキストボックスは読み取り専用になります。

• 数式セルが編集モードに入ったとき、マスクは有効になりません。

• マスク編集後、エディタの値が「=」、「-」、「+」で始まる場合は、quotePrefix が自動的に追加されます。

サンプルパターン

次の表は、通常使用されるパターンを一覧します。