事実上、JSF 日時コンバーターは、Java™ SimpleDateFormat クラスの JavaScript 実装です。
日時コンバーターは、 ストリング (入力フィールドの値であることが多い) を JavaScript 日付オブジェクトに変換し、また、その逆を行います。この変換は 日付のフォーマット (例えば、日付コンポーネントの順序、各コンポーネントのフォーマット、 セパレーター) を記述する Java DateFormat パターン によって制御されています。
DateConverter が使用するフォーマットは、 「ロケール依存」です。このフォーマットは、日付コンポーネントの順序 (例えば、コンポーネントの表示が、月、日、年の順か年、月、日の順か) を正確に定義します。 また、コンポーネント間のセパレーターとして使用する文字を正確に定義します (例えば、すべてのコンポーネントを / 文字で区切る、 または最初の 2 つのコンポーネント間でスペースを使用し、 次の 2 つのコンポーネント間でコンマ - スペースを使用するなど)。日付/時刻で使用されるすべての「語」は、 ページに含まれた (または発行された) ローカライズ済みのストリング・ファイルから取得されます。 ページ内でのすべての変換では、同じ語のセットが 使用されます (例えば、すべての変換がフランス語になります)。現在は、一部の変換で使用した言語とは別の言語を、 別の変換で使用することはできません。
DateConverter は、Java DateFormat クラスで使用されるのと同じアルゴリズムを使用して日付/ストリングを変換するため、クライアント・サイド変換とサーバー・サイド変換は同じになり、非常に実用的です。
コンバーターは、JSFBehaviorValidate、DateTimeAssist (日付/時刻のキーボード補助機構)、 クライアント・サイド・データ・キャッシングなどの他のクライアント・サイド・コンポーネントによって使用されます。 また、フォーマット済みの日付が含まれるストリングを JavaScript 日付オブジェクトに 「キャスト」する必要があるプログラマーが直接使用することもできます。
hX_5.addConverter("id", new hX_5.DateTimeConverter(attributes)); 各部の意味は次のとおりです。
id |
コンポーネントが付加される HTML タグの ID。 |
属性名 |
説明 |
||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
format |
この値を変換する際に 使用する Java の 日付/時刻パターン。 詳しくは、以下を参照してください。 |
||||||||||
ICU4J |
この属性が提供されている (かつ false でない) 場合、 アスタリスクとプラス記号がパターン文字として解析され、 さらにパターン内の 2 次グループ化記号が解析されます。 |
||||||||||
base-2digit-span |
2 桁の年を解析する場合、 現在の日付より前で、この数に相当する年は「前の世紀」として処理されます。 例えば、今年が 2003 年で、 スパンが 30 の場合、「73」から「99」までの間の年は 「1973 年から 1999 年まで」として処理されます。 この値の Microsoft® での 基準値は 30 ですが、Java での 基準値は 80 になりますので、注意してください。 |
||||||||||
first-day-of-week |
「週数」の計算に使用する曜日を指定します
(0 は日曜日、1 は月曜日、というようになります) (曜日を提供する場合)。
注: これは、必ず指定する必要があります (「w」と「Y」を正しく計算するために、
ICU4J が未設定であっても指定してください)。
|
||||||||||
digits |
西ヨーロッパ言語の「0」文字以外で、Unicode 文字セットにおいて 有効なゼロ数字を表す、単一文字の表記 (表記を指定する場合)。 この文字と、Unicode 文字セット内の以下の 9 文字とが、 値のフォーマット設定時に「digits」として出力され、 ストリングから値を変換するときに数字として解析されます。 これにより、 正式のアラビア数字および/またはインド・アラビア数字などの、 西ヨーロッパ言語以外の数字をサポートできるようになります。 この値は、この文字の Unicode コード・ポイントによって、10 進数で表されます。 例えば、アラビア数字のゼロは 16 進数では 660 になります。 この場合、1632 がこの属性の値になります。 |
||||||||||
epoch |
使用する暦/時代。
ICU4J が未設定であっても指定できます。
以下のシステムがサポートされています。
|
||||||||||
strict |
0 (自由) の場合、 値の解析中、すべての「リテラル」が無視され、 順不同のコンポーネントが再配列されます。 さらに、現在の日付/時刻を使用して、 欠落しているコンポーネントがすべて提供され、 つづりの誤りと不完全なつづりが許容されます (これは評価可能な程度で行われます)。 また、「E」およびその他の非固有コンポーネントは無視されます。 1 (厳密) の場合、 値の解析中、すべての「リテラル」が無視されます。 さらに、現在の日付/時刻を使用して、 欠落しているコンポーネントが提供され、 つづりの誤りと不完全なつづりが許容されます (これは評価可能な程度に行われます)。 また、「E」およびその他の非固有コンポーネントは無視されます。 例えば、パターンが MMMM dd, yyyy である場合、 ユーザーは「Feb/02/04」と入力することができます。 これは、2004 年 2 月 2 日と解析されます。 2 (非常に厳密) の場合、 長い月名を固有の最小文字数に「短縮」できる場合を除き、 完全一致が必要です。 また、「E」およびその他の非固有コンポーネントは無視されます。 リテラルは、完全に一致する必要があります。 |
Java 10 進形式数値パターンについて詳しくは、http://java.sun.com/j2se/1.4.2/docs/api/java/text/DateFormat.html (ICU4J が使用不可の場合) および http://icu.sourceforge.net/apiref/icu4j/ (ICU4J が使用可能な場合) を参照してください。構文を要約するため、パターンは、 フォーマット文字のシーケンスで構成されています。ここでの各文字は、日付/時刻内のその位置で許可されるものを表しています。 基本的なフォーマット文字は以下のとおりです。
GGGG |
フル・ストリングの年号で、例えば「Heisei」または「Anno Domini」。 GGGG の Java Util 1.4x 実装は、 正しく機能しません。Anno Domini ではなく、AD と表示されます。 |
GGG, GG, G |
短ストリングの年号で、例えば「A.D」または「Hei」。 |
yyyy |
最大 3 つの先行ゼロが付く 4 桁ストリングで表される年で、例えば 1993。 |
yyy |
日本語以外の場合は、yy と同じです。日本語の場合、3 桁ストリングで表される年で、 最大 2 つの先行ゼロが付きます。 |
yy |
日本語以外の場合、2 桁ストリングで表される年で、例えば 1993 に対して 93。 入力データには、世紀計算規則が適用されます (上記を参照、base-2digit-span)。 日本語の場合、最大 1 つの先行ゼロが付いたストリングで表される年 (例えば、「Heisei 02」)。 |
y |
日本語以外の場合は、yy と同じです。日本語の場合、先行ゼロが付かない 年です。 |
IYYYY, YYY, YY, Y |
「w」パターン文字の使用を除いて、「y」と同じです。年は、 年の最初/最終の週に正しくなるように調整されます (例えば、 2005 年 1 月 1 日を「w YYYY」を使用して表示すると、「53 2004」)。 |
MMMM |
フル・ストリングで表される月で、例えば「January」。 |
MMM |
省略ストリングで表される月で、例えば「Jan」(Java では、通常 3 文字の略語であることに注意してください)。 |
MM |
必要に応じて先行ゼロが含まれる数値で表される月で、例えば「09」。 |
M |
先行ゼロが除外される数値で表される月で、例えば「9」。 |
EEEE |
フル・ストリングで表される曜日で、例えば「Wednesday」。 |
EEE, EE, E |
省略ストリングで表される曜日で、例えば「Wed」(Java では、通常 3 文字の略語であることに注意してください)。 |
Ie |
数値で表される曜日。値は 1 をベースとし、ローカライズされます。 例えば、週の初日が火曜日である場合、水曜日は「2」となります。 |
dd |
必要に応じて先行ゼロが含まれる数値で表される、1 カ月における日で、 例えば「04」。 |
d |
先行ゼロが除外される数値で表される、1 カ月における日で、例えば「4」。 |
DDD |
必要に応じて、最大 2 つの先行ゼロが含まれる、1 年における日 (数値) で、 例えば 002。 |
DD |
必要に応じて最大 1 つの先行ゼロが含まれる、1 年における日 (数値) で、 例えば 020。 |
D |
先行ゼロが除外される、1 年における日 (数値) で、例えば 189。 |
F |
1 カ月における曜日 (数値) で、例えば 2 (その月の第 2 水曜日を意味します)。 注: ストリングを構文解析する場合、F は無視されます。 |
Ig, gg ... gggggggg |
... gggggggg ユリウス日付。つまり、紀元前 4713 年 1 月 1 日以降の日 (0 をベースとする値)。 |
ww |
必要に応じて先行ゼロが含まれる、1 年における週 (数値) で、 例えば 05。 |
w |
先行ゼロが除外される、1 年における週 (数値) で、例えば 51。 |
W |
1 カ月における週 (数値) で、例えば 2。注: ストリングが日付に変換されるとき、w および W は 無視されます。また、日付からストリングへ変換するとき、 Java の規則が使用されます。Java では、 1 年の Week 1 はその年の最初の土曜日に終了し (7 日未満の場合もあります)、その後の週は、 翌日の日曜日を開始点として計算されます。 |
hh |
必要に応じて先行ゼロが含まれる、12 時間クロック形式での時間で、 例えば 06。 |
h |
先行ゼロが除外される 12 時間クロック形式での時間で、例えば 6。 |
HH |
必要に応じて先行ゼロが付く、24 時間クロック形式での時間で、 例えば 07 および 17。 |
H |
先行ゼロが除外される 24 時間クロック形式での時間で、例えば 7 および 17。 |
kk |
HH と似ていますが、1 をベースとします (つまり 01 から 24)。 |
k |
H と似ていますが、1 をベースとします (つまり 1 から 24)。 |
KK |
hh と似ていますが、1 をベースとします (つまり 01 から 12)。 |
K |
h と似ていますが、1 をベースとします (つまり 1 から 12)。 |
mm |
必要に応じて先行ゼロが付く分で、例えば 08。 |
m |
先行ゼロが除外される分で、例えば 8。 |
ss |
必要に応じて先行ゼロが付く秒で、例えば 09。 |
s |
先行ゼロが除外される秒で、例えば 9。 |
SSS |
ミリ秒で、3 桁すべてが表示されます。 |
SS |
ミリ秒で、最初の 2 桁が表示されます。 |
S |
ミリ秒で、最初の桁が表示されます。 |
a |
AM/PM マーカー (ロケールで必要なサイズに拡張されます)。 |
IA, AA ... AAAAAAAA |
日におけるミリ秒。 |
z |
タイム・ゾーン (ロケールで必要なサイズに拡張されます)。タイム・ゾーンの 通常のフォーマットは GMT+nn:nn です (nn:nn は GMT からのオフセット)。特定の言語 (例えば、英語) の場合、代わりに、「共通形式」のタイム・ゾーン (例えば、 EST、PST) が使用される場合があります。 |
Iv |
「夏時間調整」インディケーターのないタイム・ゾーン。クライアントは常に、 夏時間調整の時間であることが多いクライアント上のゾーンを使用して時間を表示するため、 サポートされていません。 |
IZ |
RFC 822 フォーマットで表されるタイム・ゾーン。これは +/-nnnn です ( nn:nn は GMT からのオフセット)。 |
zzzz |
タイム・ゾーンの「長形式」。これは構文解析できないため、 サポートされていません。 |
o |
月における序数日。これはローカライズできないため、サポートされていません。 |
Iu |
ICU4J 拡張された年。hxclient がサポートする年には意味がないため、 サポートされていません。 |
' |
記号と競合するリテラル・テキストは、単一引用符で囲みます。 |
'' |
単一引用符であるリテラル文字を指定するには、2 つの単一引用符を使用します。 |
フォーマットは、ストリングで上記の文字を組み合わせることによって構成されます (上記はそれぞれ、多くても 1 度しかパターンに使用されません)。上記のフォーマット文字以外の フォーマット・ストリングの文字は、「区切り文字」(リテラル・テキスト) として処理されます。 例えば、フォーマット・ストリング 「MM/dd/yyyy」で、スラッシュはリテラルとして処理されます。何らかの事情でリテラル・テキストにフォーマット文字が 含まれないということに注意する必要があります (一部が覆い隠されている場合や、それらがフォーマット文字であるということに 多くの人が気付かない場合があります)。フォーマット・ストリング文字と競合する可能性があるテキストの周りに、 単一引用符を使用します。例えば、「hh o'' clock」は「12 o'clock」を戻さず、 「o」がフォーマット文字であるため、「12 12th' cl12thck」を戻します。Java は、 英字がフォーマットに含まれ、その文字がフォーマット文字ではなく、引用符で囲まれていない場合に、 エラーをスローする場合がありますが、フォーマット文字ではないすべての英字に対してこれが行われるわけではありません。
ストリングから日付オブジェクトへの変換に使用されるパターンを構成する場合には、 ストリングが明確に解釈されるように、十分なコンポーネントが提供されていることを 確認する必要があります。例えば、「z」(タイム・ゾーン) を含む場合、 タイムゾーンは日付が分からないと解釈できないため、フォーマットに「日付」を含む必要があります (フォーマットに日付がない場合、 デフォルトで今日の日付が使用されます)。
ICU4J をオンにすると、 既存パターンの解釈方法が変更されることに注意してください。例えば、値「Jan 1, 2005」に適用される パターン「Y: yyyy」は、ICU4J がオフになっていると「Y: 2005」と表示されます。 ICU4J がオンになっていると、「04: 2005」と表示されます。ICU4J がオフになっているとき、「Y」はパターン文字ではないため、 リテラルと解釈されます。ICU4J がオンになっているときは、パターン文字です。
API 呼び出し |
説明 |
---|---|
number = stringToValue(string) |
ストリング を JavaScript の 数値オブジェクトに変換します。 失敗した場合は NULL を戻します。 |
string = valueToString(date) |
JavaScript の 日付オブジェクトを、ストリングに変換します。 失敗した場合は NULL を戻します。 |
string = lastError() |
変換が失敗すると、 失敗の理由をローカライズされたストリングとして戻します。 |
object = setAttribute(attribute) |
属性を設定します。 属性がすでに設定されたものである場合は、 その値を変更します。 |
string = getAttribute(attribute-name) |
属性の現行値を取得します。 |
Java の日付/時刻オブジェクトの処理、および 日付/時刻オブジェクトの変換には、多数の問題/制限があります。 これらと同じ問題/制限が、JavaScript コンバーターにも当てはまります。 すべての問題の包括的な説明は、この文書では省略します。 以下のリストでは、より重要な制限および問題の一部について説明します。
1582 年 10 月 15 日は、ユリウス暦が はじめてグレゴリオ暦に変更された日です。ユリウス暦では、4 年に 1 度 (4 で割り切れる年) はうるう年になります。 グレゴリオ暦では、4 年に 1 度 (100 で割り切れるが、400 で割り切れないものを除く) はうるう年になります (そのため、1900 年はうるう年では ありませんが、2000 年はうるう年です)。カレンダーをユリウス暦からグレゴリオ暦に変更するときは、 「余分なうるう日」をカレンダーから削除する必要があります (つまり、グレゴリオ暦の規則に従っていない、ユリウス暦で追加されていたうるう日)。 そのため、1582 年にユリウス暦からグレゴリオ暦に変更した国では、 10 月 5 日から 10 月 14 日までの日付がカレンダーから除去されました (つまり、10 月 4 日の次は 10 月 15 日)。ユリウス暦からグレゴリオ暦への変更は最初に、イタリア、ポルトガル、スペイン、 およびポーランドで実施されました。世界の他の場所では、それより後に変更が行われました。 例えば、英国および同国の植民地 (例えば、ボストン) では、 1752 年に変更されました。世界の一部の場所では、20 世紀まで変更されませんでした (例えば、ギリシャは 1924 年、トルコは 1927 年、中国のほとんどの地域は 1949 年)。
DateTimeConverter は、 グレゴリオ暦の切り替え日を変更する ICU4J グレゴリオ暦オプションをサポートしていない (つまり、 setGregorianChange() をサポートしない) ため、1582 年のこの切り替え日が常に存在することに注意してください。
ユリウス暦からグレゴリオ暦への切り替えを処理するために、Java は 1582 年より前の日付に対してユリウス暦の規則を使用し、10 月 5 日から 10 月 14 日を除去し、 1582 年 10 月 15 日より後の日付に対してグレゴリオ暦の規則を使用します。 そのため、1582 年 10 月 10 日は有効な日付ではなく、1300 年 2 月 29 日は有効な日付となり、 1900 年 2 月 29 日は有効な日付ではありません。さらに、ユリウス日付の変換 (4713 年 1 月 1 日から始まる絶対日番号) は、これと同じパターンに従います (例えば、西暦 1000 年 1 月 1 日はユリウス日付 2086308 です)。紀元前 64 年は ユリウス暦が使われ始めた年ですが、その年より前の日付にも ユリウス暦の規則が使用されることに注意してください (ローマ法王グレゴリー 13 世による制定以前にグレゴリオ暦はなかったのと同様に、 ジュリアス・シーザーによる制定以前にユリウス暦はありませんでした)。
JavaScript は 同じ方法で日付を処理しません。JavaScript はグレゴリオ暦の規則を すべての日付に適用します。そのため、1582 年 10 月 10 日は有効な日付です。1300 年 2 月 29 日は有効な日付ではなく、 1900 年 2 月 29 日は有効な日付ではありません。同様に、JavaScript が ユリウス日付をサポートする場合、西暦 1000 年 1 月 1 日はユリウス日付 2086303 となります (上記と 5 日の差分)。 言い換えれば、JavaScript での 1582 年 10 月 15 日より前の日付の処理は、 Java の場合とは異なります。
日時コンバーターは、 可能な限り Java と同じ規則を使用します。そのため、 ユリウス日付を Java と同様に計算します。 ただし、グレゴリオ暦では許可されない 1582 年より前の年の日付として 2 月 29 日を入力することはできません。(JavaScript は、 これらの日付を単純に 3 月 1 日に変換し、これを回避する方法はないようです)。 そのため、1582 年より前は、どの暦でも (グレゴリオ暦またはそれ以外でも)、日付が構文解析され、コンポーネントが JavaScript 日付に変換されると、 うるう年の 2 月 29 日は再表示されません。
例えば、 Windows® では、 ユーザーは必要なフォーマットを「short」および「long」の日付で指定することができます。ブラウザー (またはサーバー) は、 この情報を読み取ることができないため、日付のフォーマットには使用されません。日付の表示に使用される唯一の情報は、 日時コンバーターに渡されるフォーマットおよびロケール情報です。
日付/時刻フォーマットを設計する場合、設計者は正確に指定 (フォーマットを提供) するか、ロケール依存フォーマット (「short」、「medium」、「long」) を 使用できます。ロケール依存フォーマットが選択された場合は、 そのロケールのすべてのユーザーに対して定義されたフォーマットが使用されます (個々のユーザー設定は無視されます)。 この制限に関して過度の不平不満があっても、変更は行われません。
入力フィールドの値を JavaScript 日付に変換し、 1 を加算し、結果を保管します。
// フォーマット MMMM dd, yyyy を使用してコンバーターを構成します hX.addConverter("AZ1", new hX.DateTimeConverter("format:MMMM dd, yyyy", "strict:2", "base-2digit-span:30")); // 入力フィールドの値を、このパターンを使用してフォーマットされたストリングから JS 日付に変換します var x = document.getElementById("form1:text1"); var cvt = hX.getConverterById("AZ1"); var d = cvt.stringToValue(x.value); // エラーを検査します if (d==null) alert ("ERROR: " + cvt.lastError()); // 値を増分して戻します else { d.setDate(d.getDate()+1); x.value = cvt.valueToString(d); }