API

このページは TextInputGuard の利用者向け API リファレンスです。
基本的な使い方は Getting Started、実際の挙動は Demo を先に見ると理解しやすくなります。

インポート

import { attach, attachAll, autoAttach, rules } from "text-input-guard";

エントリーポイント

attach()

/**
 * @param {HTMLInputElement|HTMLTextAreaElement} element
 * @param {AttachOptions} [options]
 * @returns {Guard}
 */
declare function attach(element, options = {}): Guard;

単一の要素にガードを適用します。戻り値は Guard オブジェクトです。

const guard = attach(input, {
	rules: [
		rules.numeric({ allowFullWidth: true, allowMinus: true, allowDecimal: true }),
		rules.digits({ int: 8, frac: 2 }),
		rules.comma()
	]
});

attachAll()

/**
 * @param {Iterable<HTMLInputElement|HTMLTextAreaElement>} elements
 * @param {AttachOptions} [options]
 * @returns {GuardGroup}
 */
declare function attachAll(
	elements: Iterable<HTMLInputElement | HTMLTextAreaElement>,
	options?: AttachOptions
): GuardGroup;

複数要素へ同一設定をまとめて適用します。戻り値は GuardGroup オブジェクトです。

const group = attachAll(document.querySelectorAll(".price"), {
	rules: [
		rules.numeric({ allowFullWidth: true, allowMinus: true, allowDecimal: true }),
		rules.digits({ int: 8, frac: 2 }),
		rules.comma()
	]
});
const guard = group.getGuards()[0];

autoAttach()

/**
 * @param {Document|DocumentFragment|ShadowRoot|Element} [root=document]
 * @returns {GuardGroup}
 */
declare function autoAttach(root?: HTMLElement | Document): GuardGroup;

HTML の data-tig-* 属性からルールを読み取り、自動的に適用します。戻り値は GuardGroup オブジェクトです。

html

<input
	id="price"
	type="text"
	inputmode="decimal"
	style="text-align: right"
	data-tig-rules-numeric
	data-tig-rules-numeric-allow-full-width="true"
	data-tig-rules-numeric-allow-minus="true"
	data-tig-rules-numeric-allow-decimal="true"
/>

const guards = autoAttach();
const guard = guards.getGuards()[0];

戻り値／引数の詳細

AttachOptions

attach() に渡す設定オプションです。
入力のルール・エラー表示・コールバックなどを指定できます。

option	type	default	説明
`rules`	`Rule[]`	`[]`	適用するルール配列。配列の順番が各フェーズ内での実行順になります。
`warn`	`boolean`	`true`	非対応ルールや不正な設定があった場合に `console.warn` を出力するかどうか。
`invalidClass`	`string`	`"is-invalid"`	エラーが存在する場合に `displayElement` に付与される CSS クラス名。
`historySize`	`number`	`50`	Undo/Redo を受け付ける履歴の最大数。
`onValidate`	`(result: ValidateResult) => void`	-	バリデーション評価が完了した際に呼び出されるコールバック。入力中 (`input`) と確定時 (`commit`) の両方で呼ばれます。
`onInput`	`(result: Guard) => void`	-	入力後に値が変更されていた際に呼び出されるコールバック。
`onChange`	`(result: Guard) => void`	-	フォーカスが外れた値が変更されていた際に呼び出されるコールバック。

Guard

attach() が返す Guard の公開メソッドです。

detach()

detach(): void

ガードを解除します。

イベントリスナーを削除
swap モード時は元の状態に復元

guard.detach();

isValid()

isValid(): boolean

現在エラーが無い場合は true を返します。

guard.isValid();

getErrors()

getErrors(): TigError[]

現在のエラー一覧を返します。返却値はコピーであり、外部から直接変更できません。

guard.getErrors();

getRawValue()

getRawValue(): string

送信用の値（正規化済み値）を取得します。

swap モード時は hidden 側の値
通常モード時は表示要素の値

guard.getRawValue();

getDisplayValue()

getDisplayValue(): string

ユーザーが実際に操作している要素の値を取得します。

guard.getDisplayValue();

getRawElement()

getRawElement(): HTMLInputElement | HTMLTextAreaElement

送信用の要素を取得します。

swap モード時は hidden 要素
通常モード時は元の要素

guard.getRawElement();

getDisplayElement()

getDisplayElement(): HTMLInputElement | HTMLTextAreaElement

ユーザーが操作している表示用要素を取得します。

guard.getDisplayElement();

evaluate()

evaluate(): void

入力中評価を手動実行します。

実行フェーズ:

normalizeChar
normalizeStructure
validate

通常は入力中、IME確定時に実行されます。

guard.evaluate();

commit()

commit(): void

確定評価を手動実行します。

実行フェーズ:

normalizeChar
normalizeStructure
validate
fix
validate（再評価）
format

通常は blur 時に自動実行されます。

setValue()

setValue(value: string | number | null | undefined, mode?: "evaluate" | "commit"): void

値をプログラムから設定します。

valuestring | number | null | undefined
mode（省略可） "none" | "input" | "commit"（既定値 "commit"）

null や undefined は空文字として扱われます。 NaN や Infinity は空文字に変換されます。

guard.setValue(1234);
guard.setValue("0012", "input");
guard.setValue("", "none");

GuardGroup

attachAll() / autoAttach() が返す GuardGroup の公開メソッドです。

/**
 * @typedef {Object} GuardGroup
 * @property {() => void} detach - 全部 detach
 * @property {() => boolean} isValid - 全部 valid なら true
 * @property {() => TigError[]} getErrors - 全部のエラーを集約
 * @property {() => Guard[]} getGuards - 個別Guard配列
 */

onValidate

onValidate は評価完了時に呼び出され、現在のエラー状態を受け取ることができます。
エラーが存在しない場合でも呼び出されます。

コールバックには ValidateResult が渡されます。

property	type	説明
`guard`	`Guard`	この結果を発生させた Guard インスタンス
`source`	`"input" \| "commit"`	評価が実行されたタイミング
`errors`	`TigError[]`	発生しているエラー一覧
`isValid`	`boolean`	エラーが存在しない場合 `true`

onInput

onInput は入力欄の内容に変更があった際に呼び出されます。

コールバックには Guard が渡されます。変更後に何か処理をしたい場合は、このコールバック内で guard.getRawValue() を利用して変更後の値を取得し、処理をすることを想定しています。入力途中のため文字列に対してカンマ等を付けていない状態になり guard.getDisplayValue() の値は guard.getRawValue() の値と等しい情報となります。

onChange

onChange はフォーカスが外れた値が変更されていた際に呼び出されます。

コールバックには Guard が渡されます。変更後に何か処理をしたい場合は、このコールバック内で guard.getRawValue(), guard.getDisplayValue() を利用して変更後の値を取得し、処理をすることを想定しています。

TigError

バリデーションエラーを表すオブジェクトです。
ルールの評価中に制約違反が発生した場合に生成されます。

エラーは以下の方法で取得できます。

guard.getErrors()
onValidate コールバック

構造

property	type	説明
`code`	`string`	エラー識別子
`rule`	`string`	エラーを発生させたルール名
`phase`	`PhaseName`	エラーが発生したフェーズ
`detail`	`any`	エラーの追加情報（制限値など）

code

code は "rule.reason" 形式の文字列です。

例

code	説明
`length.max_overflow`	最大文字数を超えている
`width.max_overflow`	表示幅の制限を超えている
`bytes.max_overflow`	バイト数の制限を超えている
`digits.int_overflow`	整数部の桁数を超えている
`digits.frac_overflow`	小数部の桁数を超えている
`filter.invalid_char`	許可されていない文字が含まれている

phase

エラーが発生した処理フェーズを表します。通常バリデーションで発生します。

phase	説明
`normalizeChar`	文字単位の正規化
`normalizeStructure`	構造の正規化
`validate`	バリデーション
`fix`	確定時の補正
`format`	表示フォーマット

detail

detail にはエラーの追加情報が格納されます。

文字数制限系

制限エラーでは以下の形式になります。

property	type	説明
`limit`	`number`	設定されている制限値
`actual`	`number`	実際の値

例

json

{
	"code": "length.max_overflow",
	"rule": "length",
	"phase": "validate",
	"detail": {
		"limit": 10,
		"actual": 12
	}
}

filter

filter.invalid_char の場合は以下の情報が含まれます。

property	type	説明
`count`	`number`	不正文字の総数
`chars`	`string[]`	検出された不正文字
`category`	`string[]`	許可カテゴリ
`hasAllow`	`boolean`	`allow` オプションが指定されているか
`hasDeny`	`boolean`	`deny` オプションが指定されているか

Rules

公開されているルール生成関数 rules.xxx(...) の仕様（オプション・挙動）をまとめます。ルールは 配列順に実行 されます。

推奨の並び順

数値入力: numeric() → digits() → comma() → prefix() / suffix()
文字列入力: ascii() / kana() / trim() → filter()

表示整形系（comma / prefix / suffix）は、基本的に最後に置くのを推奨します。

文字列系

氏名・コード・メモなど「文字列として扱う入力」に使用します。

`kana()`

かな文字の正規化を行います。

例

rules.kana({
	target: "katakana-full"
});

オプション

option	type	default	説明
`target`	`"katakana-full" \| "katakana-half" \| "hiragana"`	`"katakana-full"`	統一先
`nfkc`	`boolean`	`true`	事前に Unicode NFKC 正規化を行う（合体文字などを正規化）

`imeOff()`

ASCII入力欄に日本語IMEで入った文字を、IMEオフ入力相当の ASCII 文字へ寄せます。

主に次のような文字を変換します。

、 → ,
。 → .
「 → [
」 → ]
￥ → \
全角ASCII (ＡＢＣ１２３！ など) → 半角ASCII

例

rules.imeOff();

補足

単なる「半角化」ではなく、日本語IME入力で入りやすい文字を ASCII 入力向けに矯正するルールです。
IMEのデフォルトをOFFにする inputmode="url" と併用することを推奨します。

`ascii()`

ASCII範囲へ正規化します（カナは対象外）。全角英数字・全角記号・全角スペースなどを半角ASCIIへ正規化し、必要に応じて英字の大文字/小文字を統一します。

例

rules.ascii();

オプション

option	type	default	説明
`case`	`"none" \| "upper" \| "lower"`	`"none"`	統一先

補足

ascii() は ASCII 相当文字の半角化・英字統一を行うルールです。
、 や 。 などは ascii() だけでは ASCII の , や . になりません。これらも半角にしたい場合、先に imeOff() で ASCII 入力相当に寄せ、その後に ascii() を適用する組み合わせをおすすめします。

`filter()`

許可/禁止文字の制御を行います。

例

rules.filter({
	category: ["digits"],
	mode: "error"
});

オプション

option	type	default	説明
`category`	`FilterCategory[]`	-	許可カテゴリ（配列）
`mode`	`"drop" \| "error"`	`"drop"`	不許可文字の扱い（drop: 削除 / error: 削除せずエラーを積む）
`allow`	`RegExp \| string`	-	追加で許可する正規表現（1文字にマッチさせる想定）
`allowFlags`	`string`	-	`allow` が文字列のときの flags（`"iu"` など。`g` / `y` は無視）
`deny`	`RegExp \| string`	-	除外する正規表現（1文字にマッチさせる想定）
`denyFlags`	`string`	-	`deny` が文字列のときの flags（`"iu"` など。`g` / `y` は無視）

補足

category で指定できる値は次の通りです。

"digits" : ASCII 数字 (0-9)
"alpha-upper" : ASCII 英字大文字 (A-Z)
"alpha-lower" : ASCII 英字小文字 (a-z)
"ascii" : ASCII 可視文字 + スペース含む (U+0020–U+007E)
"hiragana" : ひらがな (U+3040–U+309F)
"katakana-full" : 全角カタカナ (U+30A0–U+30FF)
"katakana-half" : 半角カタカナ (U+FF65–U+FF9F)
"bmp-only" : BMP のみ許可（U+0000–U+FFFF、サロゲートペア禁止、補助平面禁止）
"sjis-only" : 正規 Shift_JIS（JIS X 0208 + 1バイト領域）のみ許可
"cp932-only" : Windows-31J (CP932) でエンコード可能な文字のみ許可
"single-codepoint-only" : 単一コードポイントのみ許可（結合文字や異体字セレクタを含まない）

運用上の注意

allow / deny は「1文字にマッチさせる想定」です。長さをまたぐパターンを入れると意図とズレる可能性があります。
allow / deny を文字列で渡す場合に、flags を分けて指定したいときは allowFlags / denyFlags を使います（g / y は無視されます）。

`trim()`

前後の空白を削除します。

rules.trim();

`length()`

入力値の最大長を制御します。単位は「グラフェム」「UTF-16コード単位」「UTF-32コード単位」から選べます。

例

rules.length({
	max: 10,
	mode: "block",
	unit: "grapheme"
});

オプション

option	type	default	説明
`max`	`number`	-	最大長。未指定なら制限なし
`mode`	`"block" \| "error"`	`"block"`	最大長を超えたときの挙動（`block`: 超過分を入力時にカット / `error`: 変更せずエラー扱い）
`unit`	`"grapheme" \| "utf-16" \| "utf-32"`	`"grapheme"`	長さの単位

補足

"grapheme": 見た目の「1文字」単位に近い数え方（結合文字や絵文字シーケンスをまとめて扱う想定）
"utf-16": UTF-16コード単位で数えます。サロゲートペアは 2 として数えられます。
"utf-32": コードポイント単位（例："é" は 2 になる）

運用上の注意

"utf-16" は JavaScript の string.length と同じ数え方であり、HTML の maxlength 属性と実質的に同じ動作になります。既存の maxlength と揃えたい場合は "utf-16" を選ぶと挙動が一致します。
"utf-16" を選ぶと、絵文字などのサロゲートペアは「2」としてカウントされます。
"utf-32" は結合文字（ダイアクリティカルマーク等）や異体字セレクタを含むと 2 以上になりやすいです。
ユーザー体験を優先するなら "grapheme"、既存Web仕様との互換性を優先するなら "utf-16"、コードポイント単位で厳密に制御したい場合は "utf-32" が向いています。

`width()`

入力値の最大幅を制御します。半角は 1、全角は 2 として数えます（0幅要素も考慮）。

例

rules.width({
	max: 20,
	mode: "block"
});

オプション

option	type	default	説明
`max`	`number`	-	最大幅（半角=1、全角=2）。未指定なら制限なし
`mode`	`"block" \| "error"`	`"block"`	最大幅を超えたときの挙動（`block`: 超過分を入力時にカット / `error`: 変更せずエラー扱い）

補足

数え方のルール

0幅: グラフェムを構成する要素（結合文字、異体字セレクタ、スキントーン修飾子、Tag Sequence 構成文字、ZWSP / ZWNJ / ZWJ / WJ など）
1幅: ASCII 文字、半角カタカナ、Regional Indicator（単体）
2幅: 上記以外

※ 目的が Shift_JIS 時代の半角全角に近いため、Unicode 公式の EastAsianWidth.txt は使っていません。

運用上の注意

width() は「見た目の横幅」をざっくり揃える用途（氏名・住所・品名の“見た目の桁揃え”など）に向いています。
絵文字や異体字セレクタなどは 0幅要素を含むため、「見た目は 1 文字でも内部要素が複数」になりがちです。length(unit: "grapheme") と目的が近いですが、width() は半角全角の混在を強く意識したカウントになります。
「見た目を揃えたい」なら width()、「文字数を揃えたい」なら length() を選ぶのが基本です。

`bytes()`

入力値の最大サイズ（バイト数）を制御します。単位は "utf-8" | "utf-16" | "utf-32" | "sjis" | "cp932" から選べます。改行コードの扱いも指定でき、バイト数の計算に反映されます。

例

rules.bytes({
	max: 64,
	mode: "block",
	unit: "utf-8",
	newline: "\r\n"
});

オプション

option	type	default	説明
`max`	`number`	-	最大サイズ（バイト数）。未指定なら制限なし
`mode`	`"block" \| "error"`	`"block"`	最大サイズを超えたときの挙動（`block`: 超過分を入力時にカット / `error`: 変更せずエラー扱い）
`unit`	`"utf-8" \| "utf-16" \| "utf-32" \| "sjis" \| "cp932"`	`"utf-8"`	サイズの単位（バイト数の数え方）
`newline`	`"\n" \| "\r" \| "\r\n"`	`"\n"`	改行コードの扱い。内部で改行は正規化され、指定した改行コードとしてバイト数が計算される

補足

"utf-8": UTF-8 にエンコードしたときのバイト数（ASCII=1、ひらがな/漢字は多くが 3、絵文字は 4 など）
"utf-16": UTF-16 のコードユニット数 × 2（サロゲートペアは 4 bytes）
"utf-32": コードポイント数 × 4（例："é" は 8 bytes）
"sjis" / "cp932": Shift_JIS（Windows-31J 系）にエンコードしたときのバイト数
- 「旧Windows互換」「Shift_JIS 前提の外部I/F」などに合わせる用途です。エンコード不能になるので、 filter()（"sjis-only" / "cp932-only" など）とセットで使用してください。
- ライブラリ内部では Shift_JIS で算出します（sjis/cp932 の差異はフィルタ側の許可範囲で制御する想定）
入力中の改行コード（\r\n, \r, \n）は内部で一度 \n へ正規化後に計算を行います

運用上の注意

DB カラムのバイト制限（例：VARCHAR2(XX BYTE) 相当）や、外部システムの「○○ bytes まで」制約に合わせたいときは bytes() が向いています。
"utf-8" は実運用で一番遭遇しやすいバイト制限（API/DB/ログ/外部I/F）なので、迷ったらまず "utf-8" が無難です。
「ユーザー体験優先で自然に“文字数っぽく”止めたい」なら length(unit: "grapheme")、「見た目の桁揃え」なら width()、「外部制約（bytes）」に合わせたいなら bytes()、という棲み分けがしやすいです。

数値系

金額・数量など「数値として扱う入力」に使用します。

`numeric()`

数値入力の土台となるルールです。全角→半角変換や、- / . の構造整理を行います。

例

rules.numeric({
	allowFullWidth: true,
	allowMinus: true,
	allowDecimal: true
});

オプション

option	type	default	説明
`allowFullWidth`	`boolean`	`true`	全角数字・記号を許可し半角へ正規化
`allowMinus`	`boolean`	`false`	`-` を許可（先頭のみ）
`allowDecimal`	`boolean`	`false`	`.` を許可（1つのみ）
`allowEmpty`	`boolean`	`true`	空文字を許可する

補足

allowEmpty: false の場合、確定時（blur）に空文字が 0 へ補正される想定です（numeric の fix フェーズ）。
整数入力の inputmode="numeric" 又は実数入力の inputmode="decimal" と併用することを推奨します。

`digits()`

桁数制限・丸め・入力超過時の挙動を制御します。

例

rules.digits({
	int: 8,
	frac: 2,
	modeInt: "block",
	modeFrac: "block",
	fixFracOnBlur: "round",
	forceFracOnBlur: true
});

オプション

option	type	default	説明
`int`	`number`	-	整数部の最大桁数（省略可）
`frac`	`number`	-	小数部の最大桁数（省略可）
`countLeadingZeros`	`boolean`	`false`	整数部の先頭ゼロを桁数に含める
`modeInt`	`"block" \| "error"`	`"block"`	入力中：整数部が最大桁を超える入力の挙動
`modeFrac`	`"block" \| "error"`	`"block"`	入力中：小数部が最大桁を超える入力の挙動
`fixIntOnBlur`	`"none" \| "truncateLeft" \| "truncateRight" \| "clamp"`	`"none"`	blur時の整数部補正
`fixFracOnBlur`	`"none" \| "truncate" \| "round"`	`"none"`	blur時の小数部補正
`forceFracOnBlur`	`boolean`	`false`	blur時に小数部を必ず表示（`frac` 桁まで0埋め）

補足

forceFracOnBlur: true は、frac が指定されていることを前提に、小数部を frac 桁まで 0 埋めして表示する用途です。

`comma()`

整数部に3桁区切りカンマを付与します。

rules.comma();

補足

確定時（blur）および表示整形フェーズで適用されます。
数値系ルールの最後に配置してください（prefix / suffix よりは前が基本）。

`prefix()`

表示用の先頭文字列を付与します。

rules.prefix({ text: "¥" });

オプション

option	type	default	説明
`text`	`string`	必須	先頭に付ける文字列
`showWhenEmpty`	`boolean`	`false`	値が空でも表示するか

`suffix()`

表示用の末尾文字列を付与します。

rules.suffix({ text: "円" });

オプション

option	type	default	説明
`text`	`string`	必須	末尾に付ける文字列
`showWhenEmpty`	`boolean`	`false`	値が空でも表示するか

autoAttach 向け data 属性方法

autoAttach() では data-tig-rules-ルール名 から始まるデータ属性を読み取り自動で設定できます。

numeric ルールを適用したい場合、まず numeric を付けてください。さらに各オプションを続けて allow-full-width のようにケバブケースで記載します。省略した場合はデフォルトが使用されます。

オプションの filter.category(["A", "B"]) のような文字列の配列を入れたい場合は、カンマ区切り "A, B"で入れてください。

例

html

<input
	data-tig-rules-numeric
	data-tig-rules-numeric-allow-full-width="true"
	data-tig-rules-numeric-allow-minus="true"
	data-tig-rules-numeric-allow-decimal="true"
	data-tig-rules-digits
	data-tig-rules-digits-int="8"
	data-tig-rules-digits-frac="2"
	data-tig-rules-comma
/>

API ​

インポート ​

エントリーポイント ​

attach() ​

attachAll() ​

autoAttach() ​

戻り値／引数の詳細 ​

AttachOptions ​

Guard ​

detach() ​

isValid() ​

getErrors() ​

getRawValue() ​

getDisplayValue() ​

getRawElement() ​

getDisplayElement() ​

evaluate() ​

commit() ​

setValue() ​

GuardGroup ​

onValidate ​

onInput ​

onChange ​

TigError ​

構造 ​

code ​

phase ​

detail ​

文字数制限系 ​

filter ​

Rules ​

文字列系 ​

kana() ​

imeOff() ​

ascii() ​

filter() ​

trim() ​

length() ​

width() ​

bytes() ​

数値系 ​

numeric() ​

digits() ​

comma() ​

prefix() ​

suffix() ​

autoAttach 向け data 属性方法 ​

API

インポート

エントリーポイント

attach()

attachAll()

autoAttach()

戻り値／引数の詳細

AttachOptions

Guard

detach()

isValid()

getErrors()

getRawValue()

getDisplayValue()

getRawElement()

getDisplayElement()

evaluate()

commit()

setValue()

GuardGroup

onValidate

onInput

onChange

TigError

構造

code

phase

detail

文字数制限系

filter

Rules

文字列系

`kana()`

`imeOff()`

`ascii()`

`filter()`

`trim()`

`length()`

`width()`

`bytes()`

数値系

`numeric()`

`digits()`

`comma()`

`prefix()`

`suffix()`

autoAttach 向け data 属性方法