date-fns sub関数：使い方、オプション、サンプルコード、その他方法まで完全解説

date-fns の Common Helpers における sub 関数の詳細解説

sub 関数は、date-fns ライブラリの Common Helpers における重要な関数の一つです。この関数は、指定された日付から指定された期間を減算するために使用されます。期間は、日数、週数、月数、年数など、さまざまな単位で指定できます。

使い方

sub 関数の基本的な使い方は以下の通りです。

import { sub } from 'date-fns';

const date = new Date(2024, 3, 2);

// 日付から 10 日間減算
const newDate1 = sub(date, { days: 10 });
console.log(newDate1); // 2024-03-22

// 日付から 2 週間減算
const newDate2 = sub(date, { weeks: 2 });
console.log(newDate2); // 2024-02-28

// 日付から 3 ヶ月減算
const newDate3 = sub(date, { months: 3 });
console.log(newDate3); // 2023-12-02

// 日付から 1 年減算
const newDate4 = sub(date, { years: 1 });
console.log(newDate4); // 2023-03-02

上記のように、sub 関数の第 1 引数には減算対象となる日付オブジェクト、第 2 引数には減算する期間を指定するオブジェクトを渡します。

オプション

sub 関数は、減算する期間をより詳細に設定するためのオプションをいくつか提供しています。

• startOfWeek: 週の開始曜日を指定します。デフォルトは日曜日です。
• weekStartsOn: 週の開始曜日を指定します。デフォルトは 'locale' に基づいて決定されます。
• locale:ロケールを指定します。デフォルトは 'en-US' です。

これらのオプションは、以下の例のように使用できます。

import { sub } from 'date-fns';

const date = new Date(2024, 3, 2);

// 日付から 10 日間減算、週の開始曜日を月曜日に設定
const newDate1 = sub(date, { days: 10, weekStartsOn: 1 });
console.log(newDate1); // 2024-03-23

// 日付から 2 週間減算、ロケールを日本語に設定
const newDate2 = sub(date, { weeks: 2, locale: 'ja' });
console.log(newDate2); // 2024-02-20

• sub 関数は、Immutable な関数です。つまり、元の Date オブジェクトは変更されません。
• sub 関数は、さまざまな日付ライブラリと互換性があります。

補足

sub 関数は、日付操作において非常に便利な関数です。上記の説明を参考に、ぜひさまざまな場面で使用してみてください。

関連関数

• add
• differenceInDays
• differenceInWeeks
• differenceInMonths
• differenceInYears

sub 関数のサンプルコード

import { sub } from 'date-fns';

const date = new Date(2024, 3, 2);

// 10 日間減算
const newDate1 = sub(date, { days: 10 });
console.log(newDate1); // 2024-03-22

// 2 週間減算
const newDate2 = sub(date, { weeks: 2 });
console.log(newDate2); // 2024-02-28

// 3 ヶ月減算
const newDate3 = sub(date, { months: 3 });
console.log(newDate3); // 2023-12-02

// 1 年減算
const newDate4 = sub(date, { years: 1 });
console.log(newDate4); // 2023-03-02

現在の時刻から減算

import { sub } from 'date-fns';

// 現在時刻から 1 時間減算
const newDate1 = sub(new Date(), { hours: 1 });
console.log(newDate1); // 2024-04-02T10:59:00.000Z

// 現在時刻から 30 分減算
const newDate2 = sub(new Date(), { minutes: 30 });
console.log(newDate2); // 2024-04-02T11:29:00.000Z

// 現在時刻から 10 秒減算
const newDate3 = sub(new Date(), { seconds: 10 });
console.log(newDate3); // 2024-04-02T11:59:50.000Z

動的な期間を減算

import { sub } from 'date-fns';

const days = 10;
const weeks = 2;

// 日付から days 日間減算
const newDate1 = sub(new Date(), { days });
console.log(newDate1); // 2024-03-23

// 日付から weeks 週間減算
const newDate2 = sub(new Date(), { weeks });
console.log(newDate2); // 2024-02-28

オプションの使用

import { sub } from 'date-fns';

const date = new Date(2024, 3, 2);

// 週の開始曜日を月曜日に設定して 10 日間減算
const newDate1 = sub(date, { days: 10, weekStartsOn: 1 });
console.log(newDate1); // 2024-03-23

// ロケールを日本語に設定して 2 週間減算
const newDate2 = sub(date, { weeks: 2, locale: 'ja' });
console.log(newDate2); // 2024-02-20

他の関数との組み合わせ

import { sub, differenceInDays } from 'date-fns';

const date1 = new Date(2024, 3, 2);
const date2 = new Date(2024, 2, 28);

// date1 から date2 を減算
const daysDiff = differenceInDays(date1, date2);
console.log(daysDiff); // 35

// date1 から daysDiff 日間減算
const newDate = sub(date1, { days: daysDiff });
console.log(newDate); // 2024-02-28

sub 関数以外の方法

手動計算

単純な減算であれば、手動で計算することも可能です。例えば、2024 年 4 月 2 日から 10 日間減算したい場合は、以下の式で計算できます。

2024 年 4 月 2 日 - 10 日 = 2024 年 3 月 22 日

ただし、複雑な減算や、さまざまな単位での減算を行う場合は、手動計算は誤りやすくなります。

ライブラリの使用

date-fns 以外にも、さまざまな日付ライブラリが提供されています。これらのライブラリには、sub 関数と同様の機能を持つ関数などが含まれている場合があります。

以下は、代表的な日付ライブラリの例です。

これらのライブラリは、date-fns と同様の使い方で、日付の減算を行うことができます。

JavaScript の組み込み関数

JavaScript には、日付操作用の組み込み関数がいくつか用意されています。これらの関数を使用して、日付から期間を減算することも可能です。

以下は、代表的な組み込み関数の例です。

• Date.prototype.setDate()
• Date.prototype.setMonth()
• Date.prototype.setFullYear()

これらの関数は、直接的に日付を減算する関数ではありませんが、日付の各要素を個別に設定することで、間接的に減算を行うことができます。

自作関数

上記の方法以外にも、必要に応じて自作関数を作成することも可能です。自作関数を作成する場合は、以下の点に注意する必要があります。

• 日付のフォーマット
• 減算する単位
• エラー処理

自作関数は、柔軟なカスタマイズが可能です。ただし、複雑な処理になると、コード量が増えたり、バグが発生しやすくなったりするため、注意が必要です。

どの方法を選択するべきかは、以下の要素を考慮する必要があります。

• 減算の複雑さ
• 使用するライブラリ
• 開発者のスキル

単純な減算であれば、手動計算や JavaScript の組み込み関数で十分対応できます。複雑な減算や、さまざまな単位での減算を行う場合は、date-fns などのライブラリを使用するのがおすすめです。

sub 関数は、日付から期間を減算するための便利な関数です。ただし、上記で紹介した他の方法も状況に応じて有効活用できます。