西暦データから和暦を取得

西暦データから和暦を取得します。正確な日付の場合はもちろん、「2000年1月」など曖昧なデータの場合も極力特定を試みます。

内部的には Intl.DateTimeFormat を使用しており、将来的に新しい元号に切り替わっても（ブラウザや Node.js のアップデートにより）自動的に対応されます。また「明治」より前の元号（「慶応」以前）にも対応しています。

例

import Wareki from '@w0s/wareki';

const wareki1 = new Wareki(new Date(2000, 0, 1));
wareki1.getYear(); // 平成12
wareki1.getYearParts(); // [ { type: 'era', value: '平成' }, { type: 'year', value: '12' }, { type: 'literal', value: '年' } ]

const wareki2 = new Wareki('2000'); // 年月または年のみのデータでも極力特定を試みます
wareki2.getYear({ era: 'narrow' }); // H12
wareki3.getYearParts({ era: 'narrow' }); // [ { type: 'era', value: 'H' }, { type: 'year', value: '12' }, { type: 'literal', value: '年' } ]

const wareki3 = new Wareki('1989-01'); // 1989年1月は昭和64年と平成元年の両方が考えられるため、特定が不可能です
wareki3.getYear(); // undefined
wareki3.getYearParts(); // undefined

try {
  new Wareki('2000/01/01'); // 指定外のフォーマットは `Error` がスローされます
} catch {
}

コンストラクター

new Wareki(date: Date | string)

パラメーター

日付データの注意点

• 第一引数の日付データは Date オブジェクトまたは String 型で指定することができます。ごくわずかですが Date オブジェクトの方が処理効率は高いです。
• String 型の場合、指定できるフォーマットは YYYY-MM-DD, YYYY-MM, YYYY のいずれかとなります。
• String 型で指定外のフォーマットを指定した場合は Error がスローされます。

メソッド

Option

interface FormatOption {
	era?: 'long' | 'short' | 'narrow'; // 元号の表現方法（`Intl.DateTimeFormat()` コンストラクターの `era` オプションと同等）
}