10 入力の検証および変換
oj-combobox、oj-input*、oj-text-areaなど、多数のOracle JET編集可能要素に対するバリデータおよびコンバータが含まれています。これらをそのまま使用することも、Oracle JETアプリケーションでの入力を検証および変換するためにカスタマイズすることもできます。oj-checkboxset、oj-radioset、oj-selectなどの一部の編集可能要素には、組込みバリデータを暗黙的に作成するrequired値の単純な属性が含まれます。
ノート:
前述のoj-input*は、特に、oj-input-date-time、oj-input-text、oj-input-passwordなどの入力コンポーネントのファミリを指します。
Oracle JETバリデータおよびコンバータについて
Oracle JETには、ユーザー入力文字列をアプリケーションで使用できるデータ型に変換するコンバータ・クラス、およびそれらの入力文字列に検証ルールを強制するバリデータ・クラスが用意されています。
たとえば、Oracle JETのIntlDateTimeConverterを使用して、ユーザー入力の日付を日付のみのISO文字列に変換し、次にDateTimeRangeValidatorを使用して、指定した日付範囲に対してその入力を検証できます。Oracle JETに含まれるコンバータまたはバリデータがアプリケーションにとって十分でない場合は、カスタムのコンバータまたはバリデータを作成できます。
バリデータについて
すべてのOracle JET編集可能要素はvalue属性をサポートし、ユーザーが値を入力または選択できるUI要素を提供します。これらの要素は、要素に対して値の検証方法を指示するために設定できる、その他の属性もサポートしています。
編集可能要素では、特定の属性が設定されると、標準機能に対する組込みコンバータまたは組込みバリデータ(あるいはその両方)を暗黙的に作成できます。たとえば、requiredプロパティをサポートする編集可能要素では、プロパティがtrueに設定されると必須バリデータを暗黙的に作成します。oj-input-date、oj-input-date-time、oj-input-timeなどの要素では、日時コンバータを作成してその基本機能を実装します。
Oracle JETバリデータについて
次の表では、Oracle JETバリデータについて説明し、APIドキュメントへのリンクを示します。
| バリデータ | 説明 | APIへのリンク | モジュール |
|---|---|---|---|
|
|
入力日付が、2つの日付間、2つの時刻間、または2つの日時範囲内にあることを検証します |
|
|
|
|
入力日付が制限された日付でないことを検証します |
|
|
|
|
入力文字列が指定された長さ以内であることを検証します |
|
|
|
|
入力数値が指定された範囲内であることを検証します |
|
|
|
|
正規表現が指定のパターンに一致していることを検証します |
|
|
|
|
必須エントリが存在していることを検証します |
|
Oracle JETコンポーネントの検証属性について
コンポーネントがサポートする属性はAPIの一部で、次の検証固有の属性がほとんどの編集可能要素に適用されます。
| 要素の属性 | 説明 |
|---|---|
|
|
指定すると、要素で作成される内部コンバータに対して |
|
|
|
|
|
Oracle JET要素( |
|
|
Oracle JET要素( |
|
|
Oracle JET要素に対して指定すると、要素では暗黙的な必須バリデータを作成します。 |
|
|
指定すると、要素ではこれらのバリデータと暗黙的なバリデータを使用して、UI値を検証します。 |
一部の編集可能要素は、固有の機能に関連がないため特定の検証属性をサポートしていません。たとえば、oj-radiosetおよびoj-checkboxsetは、コンバータが変換する対象がないため、converter属性をサポートしていません。属性の正確なリストおよび使用方法は、要素のAPIドキュメントの属性に関する項を参照してください。Oracle JETのAPIドキュメントについては、『Oracle® JavaScript Extension Toolkit (OracleJET) APIリファレンス』を参照してください。APIリストから表示するコンポーネントを選択してください。
Oracle JETコンポーネントの検証メソッドについて
Oracle JET編集可能要素は、検証目的で次のメソッドをサポートしています。このメソッドのコール方法、およびパラメータと戻り値の詳細は、コンポーネントのAPIドキュメントを参照してください。
| 要素メソッド | 説明 |
|---|---|
|
|
このメソッドは、すべてのメッセージおよびメッセージ属性( |
|
|
このメソッドは、現在の表示値を使用してコンポーネントを検証するために使用します。 |
要素のメソッドのコール方法、パラメータおよび戻り値の詳細は、『Oracle® JavaScript Extension Toolkit (Oracle JET) APIリファレンス』で、要素のAPIドキュメントのMethodsに関する項を参照してください。コールバックの登録方法、イベントへのバインド方法、およびイベントがトリガーする対象の詳細も記載されています。APIリストから表示するコンポーネントを選択してください。
Oracle JETコンバータについて
Oracle JETでは、日付、日時、数値、色および文字列を変換するコンバータが提供されます。
これらのコンバータは、コンバータ実装の基本契約を定義するConverterオブジェクトを拡張します。コンバータAPIは、ECMAScript国際化API仕様(ECMA-402 Edition 1.0)に基づき、ロケール・データに対してUnicode共通ロケール・データ・リポジトリ(CLDR)を使用します。両方のコンバータはコンストラクタを介して初期化され、API仕様で定義されたオプションを受け入れます。ECMA-402 API仕様の詳細は、https://www.ecma-international.org/publications-and-standards/standards/ecma-402/を参照してください。Unicode CLDRの詳細は、http://cldr.unicode.orgを参照してください。
Oracle JET実装では、追加オプションを導入することによって、ECMA-402仕様が拡張されます。コンバータは、Oracle JETコンポーネントで使用したり、ページで直接インスタンス化して使用できます。各コンバータには、サポートする変換オプションを指定するConverterOptions型定義があります。次の表では、使用可能なコンバータについて説明し、各コンバータのConverterOptions型定義でサポートされているプロパティの詳細説明など、各コンバータのAPIドキュメントへのリンクを示します。
| コンバータ | 説明 | APIへのリンク |
|---|---|---|
|
|
Colorオブジェクト形式を変換します |
|
|
|
文字列をISO文字列形式(
|
|
|
|
文字列を数値に変換し、数値をロケール固有の文字列に書式設定します |
|
|
|
BigDecimal文字列をロケール固有の文字列に変換します。非常に大きい数値( |
|
|
|
日付のみのISO文字列を書式設定された文字列に、または文字列を日付のみのISO文字列に変換します |
APIドキュメントに加えて、使用中のコンバータを示すOracle JETクックブックの次のデモを参照してください:
Oracle JETコンバータは、ユーザー入力が適切なパターンと完全に一致しない場合に、数値および日付の寛大な解析をサポートしています。パーサーは、特定のコンバータの寛大さルールに基づいて寛大な解析を実行します。たとえば、NumberConverterとBigDecimalStringConverterの両方が予期しない文字を削除します。ConverterOptions型定義には通常、lenientParseプロパティが含まれます。このプロパティは、ユーザー入力が予想される入力と一致する、または例外がスローされるようにnoneに設定できます。詳細は、使用しているコンバータのAPIドキュメントを参照してください。
RequireJSおよびojs/ojvalidation-datetimeまたはojs/ojvalidation-numberモジュールを使用する場合、Oracle JETコンバータで使用するロケール記号およびデータを保持するリソース・バンドルは、ページに設定されたロケールに基づいて自動的にダウンロードされます。アプリケーションでRequireJSを使用しない場合、ロケール・データは自動的にダウンロードされません。
コンバータは、Oracle JETコンポーネントで使用したり、ページで直接インスタンス化して使用できます。
Oracle JETコンポーネントでのOracle JETコンバータの使用
ユーザー入力を受け入れるOracle JETコンポーネント(oj-c-input-date-textなど)には、ユーザー入力を解析する暗黙的なコンバータがすでに含まれています。ただし、データの変換時にかわりに使用される明示的なコンバータをコンポーネントに指定することもできます。
Oracle JETクックブックのoj-c-input-date-textコンポーネントの概要デモから抜粋した次の例では、コンポーネントが12/25/24の入力を受け入れ、暗黙的なコンバータを使用して12/25/2024としてレンダリングする間に、abcと入力するとエラー・メッセージが表示されます。
解析操作または書式設定操作時にエラーが発生した場合にコンバータがスローするエラーはConverterErrorオブジェクトで表され、エラー・メッセージはタイプがMessageのオブジェクトで表されます。Oracle JETコンバータが使用するメッセージは、Oracle JETに付属している翻訳バンドルに定義されたリソースです。
コンバータをコンポーネントのコンバータattributeに直接指定することもできます(存在する場合)。たとえば、oj-c-input-date-textコンポーネントは、converter属性を使用して、コンポーネントがレンダリングする日付スタイルを、LocalDateConverterでサポートされているコンバータ・オプションの1つに変更します。
Oracle JETクックブックには、次の場所で説明されているオプションの実装が含まれています。次を参照してください:
Oracle JETにおけるタイムゾーン・サポートの理解
Oracle JET入力コンポーネント(oj-input-date-timeなど)では、ローカル・タイムゾーン入力をサポートしています。JavaScriptのIntl.DateTimeFormat APIに依存するOracle JETのIntlDateTimeConverterを使用して、タイムゾーン・サポートを有効にできます。
次のイメージでは、入力日時コンポーネントのconverter属性は、タイムゾーンがAmerica/Los_AngelesかAsia/Hong_Kongかに応じて、2013-12-02T04:00:00Zの入力時間を適切にレンダリングするコードを参照します。
Oracle JETクックブックには、次の場所で説明されているオプションの実装が含まれています。日時の入力 - タイム・ゾーンに関する項を参照してください。
Oracle JETのIntlDateTimeConverterの詳細は、IntlDateTimeConverterを参照してください。
Oracle JETでのカスタム・コンバータの使用
Converterを拡張して、カスタム・コンバータをOracle JETに作成できます。カスタム・コンバータは、Oracle JETコンポーネントの整合性に違反しないかぎり、Oracle JETコンポーネントで使用できます。組込みのOracle JETコンバータと同様に、ページで直接使用することもできます。
次の図は、現在の日付を相対的な期間に変換するカスタム・コンバータの実装を示しています。Schedule For列では、RelativeDateTimeConverterを使用して、ページが実行されている日付をen-USロケールで変換し、Today、Tomorrow、および2日間の日付を表示します。
Oracle JETでカスタム・コンバータを作成および使用するには:
Oracle JETコンポーネント以外でのOracle JETコンバータの使用
コンバータをOracle JETコンポーネントにバインドせずに使用する場合は、選択したコンバータに対するコンストラクタを使用してコンバータを作成します。
Oracle JETクックブックには、数値コンバータおよび日時コンバータをOracle JETコンポーネントにバインドせずに、直接ページで使用する方法を示すデモが含まれています。デモの図では、給与は通貨として書式設定された数値で、開始日は日付として書式設定されたISO文字列です。
viewModelでは、Amy Flanaganの給与と開始日の次のスニペットに示すように、数値を通貨として書式設定するsalaryConverterメソッドと、日付書式スタイルと標準の日付書式を使用して開始日を書式設定するdateConverterを定義し、HTMLの表示は戻り値にバインドされます。
. . .
<p>Product Manager</p>
<span style="white-space:nowrap;"><b>Salary</b>:
<span>
<oj-bind-text value="[[amySalary]]"></oj-bind-text>
</span>
</span>
<br />
<span style="white-space:nowrap;"><b>Joined</b>:
<span>
<oj-bind-text value="[[amyStartDate]]"></oj-bind-text>
</span>
. . . Oracle JETクックブックには、次の場所で説明されているオプションの実装が含まれています。コンバータの作成に関する項を参照してください。
Oracle JETバリデータについて
Oracle JETバリデータは、コール元がバリデータ・インスタンスをカスタマイズできるようにするプロパティを提供します。プロパティはバリデータのAPIの一部として記述されます。コンバータのインスタンスを1つしか要素に設定できないコンバータとは異なり、1つ以上のバリデータを要素に関連付けることができます。
ユーザーが要素と対話してその値を変更すると、その要素に関連付けられたバリデータが順に実行されます。値が検証ルールに違反する場合、value属性は移入されず、バリデータによって、エラーが発生した要素が強調表示されます。
バリデータは、Oracle JET要素で使用したり、ページで直接インスタンス化して使用できます。
Oracle JETコンポーネントでのOracle JETバリデータの使用
Oracle JET編集可能要素(oj-input-text、oj-input-dateなど)は、サポートする特定の属性(required、min、maxなど)に基づいて暗黙的にバリデータを設定したり、コンポーネントのvalidators属性を使用して1つ以上のバリデータを設定する方法を提供して明示的にバリデータを設定できます。
たとえば、次のコードは、コンポーネントによって暗黙的に提供されるデフォルト・バリデータを使用するoj-input-date要素を示しています。oj-input-dateは、minおよびmax属性を読み取ると、暗黙的なDateTimeRangeValidatorを作成します。
<oj-form-layout id="validator-example">
<oj-input-date
id="dateTimeRange1"
value="{{dateValue1}}"
min="2000-01-01T08:00:00.000"
help.instruction="enter a date that falls in the current
millenium and not greater than today's date."
max="[[todayIsoDate]]"
label-hint="'min' attribute and 'max' option">
</oj-input-date>
</oj-form-layout>次に、この例のビュー・モデルを作成するためのスクリプトを示します。
import * as ko from "knockout";
import * as ConverterUtilsI18n from "ojs/ojconverterutils-i18n";
import "ojs/ojknockout";
import "ojs/ojformlayout";
import "ojs/ojdatetimepicker";
class DemoViewModel {
dateValue1: ko.Observable<string>;
dateValue2: ko.Observable<string>;
todayIsoDate: ko.Observable<string>;
milleniumStartIsoDate: ko.Observable<string>;
constructor() {
this.dateValue1 = ko.observable("");
this.dateValue2 = ko.observable("");
this.todayIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date())
);
this.milleniumStartIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date(2000, 0, 1))
);
}
}
export = DemoViewModel;define([
"knockout",
"ojs/ojconverterutils-i18n",
"ojs/ojknockout",
"ojs/ojdatetimepicker",
"ojs/ojformlayout",
], function (
ko,
ConverterUtilsI18n
) {
function DemoViewModel() {
this.dateValue1 = ko.observable();
this.dateValue2 = ko.observable();
this.todayIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date())
);
this.milleniumStartIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date(2000, 0, 1))
);
}
return DemoViewModel;
});
ユーザーがページを実行すると、oj-input-date要素により、カレンダ・アイコンの付いた入力フィールドが表示されます。要素に設定されたhelp.instruction属性は、入力フィールドをクリックすると入力フィールドの下に表示されます。 入力したデータが適切な範囲内でない場合は、組込みバリデータによってエラー・メッセージと適切な範囲が表示されます。
検証が失敗したときにOracle JETバリデータがスローするエラーはValidatorErrorオブジェクトで表され、エラー・メッセージはタイプがMessageのオブジェクトで表されます。Oracle JETバリデータがエラーをスローするときに使用するメッセージとヒントは、Oracle JETに付属している翻訳バンドルに定義されたリソースです。Oracle JETでのメッセージの詳細は、「ユーザー支援の使用」を参照してください。
要素のvalidators属性にバリデータを指定することもできます(存在する場合)。次のコード・サンプルは、DateTimeRangeValidatorバリデータ(dateTimeRange)をvalidators属性に指定する関数をコールする別のoj-input-date要素を示しています。
<oj-form-layout id="validator-example">
<oj-input-date
id="dateTimeRange2"
value="{{dateValue2}}"
validators="[[validators]]"
help.instruction="enter a date that falls in the current millenium and
not greater than today's date."
label-hint="'dateTimeRange' type in 'validators' option">
</oj-input-date>
</oj-form-layout>
次のコードは、有効な最小日付と最大日付を設定するオプション、およびユーザーがフィールドにフォーカスを設定すると表示されるヒントを設定するオプションを使用したviewModelへの追加を示しています。
import * as ko from "knockout";
import * as ConverterUtilsI18n from "ojs/ojconverterutils-i18n";
import AsyncDateTimeRangeValidator
= require("ojs/ojasyncvalidator-datetimerange");
import * as DateTimeConverter from "ojs/ojconverter-datetime";
import "ojs/ojknockout";
import "ojs/ojformlayout";
import "ojs/ojdatetimepicker";
class DemoViewModel {
dateValue1: ko.Observable<string>;
dateValue2: ko.Observable<string>;
todayIsoDate: ko.Observable<string>;
milleniumStartIsoDate: ko.Observable<string>;
validators: ko.Computed<AsyncDateTimeRangeValidator<string>[]>;
constructor() {
this.dateValue1 = ko.observable("");
this.dateValue2 = ko.observable("");
this.todayIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date())
);
this.milleniumStartIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.
dateToLocalIso(new Date(2000, 0, 1))
);
this.validators = ko.computed(() => {
return [
new AsyncDateTimeRangeValidator({
max: this.todayIsoDate(),
min: this.milleniumStartIsoDate(),
hint: {
inRange: "Enter a date that falls in the
current millennium.",
},
converter: new DateTimeConverter.IntlDateTimeConverter({
day: "2-digit",
month: "2-digit",
year: "2-digit",
}),
}),
];
});
}
}
export = DemoViewModel;define([
"knockout",
"ojs/ojconverterutils-i18n",
"ojs/ojasyncvalidator-datetimerange",
"ojs/ojconverter-datetime",
"ojs/ojknockout",
"ojs/ojdatetimepicker",
"ojs/ojformlayout",
], function (
ko,
ConverterUtilsI18n,
AsyncDateTimeRangeValidator,
DateTimeConverter
) {
function DemoViewModel() {
this.dateValue1 = ko.observable();
this.dateValue2 = ko.observable();
this.todayIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.
dateToLocalIso(new Date())
);
this.milleniumStartIsoDate = ko.observable(
ConverterUtilsI18n.IntlConverterUtils.
dateToLocalIso(new Date(2000, 0, 1))
);
this.validators = ko.computed(
function () {
return [
new AsyncDateTimeRangeValidator({
max: this.todayIsoDate(),
min: this.milleniumStartIsoDate(),
hint: {
inRange: "Enter a date that falls
in the current millennium.",
},
converter: new DateTimeConverter.
IntlDateTimeConverter({
day: "2-digit",
month: "2-digit",
year: "2-digit",
}),
}),
];
}.bind(this)
);
}
return DemoViewModel;
});ユーザーがen-USロケールでページを実行すると、oj-input-date要素によって入力フィールドが表示されます。このフィールドは、ユーザーの入力日付が01/01/2000から現在日付の間である必要があります。日付値をフィールドに入力するとき、日付コンバータは、日付を明確に解析できる場合にかぎり代替入力を受け入れます。これによって、エンド・ユーザーが日付値を入力するときの許容範囲が大きく広がります。たとえば、1-2-3と入力すると、Dateは2003年1月2日に変換されます。Date値が、バリデータに設定されたDate範囲内である場合も、その値は受け入れられます。検証に失敗すると、コンポーネントでエラーが表示されます。
Oracle JET要素では、regExpバリデータも使用できます。正規表現パターンにバックスラッシュが必要で、Oracle JET要素内に式を指定する場合、二重のバックスラッシュを使用する必要があります。各バリデータが受け入れるオプションは、『Oracle® JavaScript Extension Toolkit (Oracle JET) APIリファレンス』に指定されています。
Oracle JETクックブックには、この項で説明した完全な例に加え、日付制限、長さ、数値範囲、正規表現および必須フィールドに対する組込みバリデータを示す例があります。詳細は、バリデータを参照してください。
Oracle JETコンポーネントの検証の詳細は、「Oracle JET編集可能コンポーネントでの検証およびメッセージ機能の理解」を参照してください。
Oracle JETでのカスタム・バリデータの使用
Oracle JETでは、validators属性から組込みバリデータのように参照できるカスタム・バリデータを作成できます。
次の図は、ユーザーのパスワードが一致しない場合にエラー・メッセージを表示するカスタム・バリデータを示しています。
カスタム・バリデータを作成および使用するには:
非同期バリデータについて
Oracle JET入力コンポーネントでは、validators属性を介した非同期サーバー側検証をサポートしています。つまり、フォームを送信したり、ページをリフレッシュすることなく、サーバー・データに対する入力値をチェックできます。
次の2つのシナリオ例は、どのような場合に、非同期のサーバー側検証を使用できるかを示しています:
- 新しいユーザー・データを収集するフォームで、電子メール・フィールドの入力内容を検証し、入力値が事前に登録されているかどうかを確認します。
- 揮発性データを確認する数値範囲バリデータを設定します。たとえば、e-コマースのWebサイトで、ユーザーのカートを利用可能在庫に対してチェックし、商品の利用可能在庫がなければ、ユーザーがカートを送信して支払に進む前に、そのことをユーザーに通知できます。
Oracle JET Cookbookには、validators属性およびダミー・データを使用してサーバー側検証をシミュレーションするサンプルが用意されています。
次のコードはoj-input-text要素を示しています。ここでは、validators属性がviewModelコードでvalidatorsおよびasyncValidatorオブザーバブルに設定されています。非同期バリデータの作成に必要なAPI規約に準拠するためには、validators属性はタイプをAsyncValidatorにする必要があります。
<oj-form-layout id="fl1">
<oj-c-input-text
id="input-text"
required
label-hint="Quantity Limit"
on-valid-changed="[[validChangedListener]]"
validators="[[[validators, asyncValidator]]]"
value="{{quantityLimit}}"
converter="[[currencyConverter]]">
</oj-c-input-text>
</oj-form-layout>viewModelコードには、asyncValidatorオブジェクトに作成された、Promiseを返す数値範囲バリデータが含まれています。Promiseオブジェクトとは、まだ利用可能になっていない可能性があるが、将来のある時点で解決される値を表しています。非同期検証では、AsyncValidator.validate()関数は、検証に合格すればBoolean trueに評価されるPromiseを返し、検証に合格しなければErrorを返します。詳細は、「入力テキスト」のvalidators属性の項を参照するか、「Promise (MDN)」を参照してください。
Oracle JETクックブックには、次の場所で説明されているオプションの実装が含まれています。非同期バリデータに関する項を参照してください。