跳至主要内容

[note] dayjs 筆記

顯示時間（Display）​

基本 format​

import dayjs from 'dayjs';

const now = dayjs();
const format = now.format('DD/MM/YYYY'); // 07/08/2020

Time from X​

  • 需要使用 relativeTime 這個 plugin
import dayjs from 'dayjs';

// 使用 relativeTime plugin
import relativeTime from 'dayjs/plugin/relativeTime';
dayjs.extend(relativeTime);

const anHourAgo = dayjs().subtract(1, 'hour');
const timeFromNow = anHourAgo.fromNow(); // an hour ago

Difference​

取得兩個時間點之間的長度。

date1.diff('2018-06-05', <unit: string>, <float: bool>)
  • 在 diff 的第二個參數可以放入要取得單位，預設是毫秒
  • 在 diff 的第三個參數可以決定要不要顯示到小數點後位數

⚠️ 留意：如果要計算的是兩個時間點的間隔長度，而且需要取得多個時間單位，則要搭配使用 days#duration 這個 plugin。

import dayjs from 'dayjs';

const date1 = dayjs('2019-01-25');
const date2 = dayjs('2018-06-05');
const diffWithMS = date1.diff(date2); // 預設會顯示到毫秒，20214000000 default milliseconds
const diffWithMonth = date1.diff(date2, 'month'); // 7

i18n​

使用 locale 檔​

import 'dayjs/locale/zh-tw';

import dayjs from 'dayjs';

dayjs.locale('zh-tw'); // use locale

const formatLocale = dayjs('2019-01-25').format('DD/MMM/YYYY 星期dd'); // 25/1月/2019 星期五

Duration​

在 dayjs 中，dayjs 物件表示的是「時間點」；這裡的 duration 則是表示「一段時間的長度」，概念上比較像是「兩小時」而非「介於 2 點到 4 點之間」，如果你要計算是的是兩個時間點的差距，而且只需要一個時間單位時，應該要使用的是 dayjs#diff 方法。

⚠️ 留意：如果要計算的是兩個時間點的間隔長度，而且只需要一個時間單位時，可以直接使用 days#diff 方法即可。

使用前需要先載入 duration plugin：

import dayjs from 'dayjs';
import duration from 'dayjs/plugin/duration';
dayjs.extend(duration);

Humanize​

  • 除了 duration plugin 之外，需要再搭配 relativeTime plugin
  • humanize 的時間可能沒這麼精確，但是人讀得懂的
// <durationObject>.humanize(<hasPrefix: bool>)

import dayjs from 'dayjs';
import duration from 'dayjs/plugin/duration';
import relativeTime from 'dayjs/plugin/relativeTime';
dayjs.extend(duration);
dayjs.extend(relativeTime);

const twoMonths = dayjs.duration({ months: 2 });
const humanizeDuration = twoMonths.humanize(false); // 2 months（沒有 prefix）
const humanizeDuration = twoMonths.humanize(true); // in 2 months（有 prefix）

Get Seconds, Minutes, Hours, Days, Weeks, Months, Years​

import dayjs from 'dayjs';
import duration from 'dayjs/plugin/duration';

dayjs.extend(duration);

const twoMonths = dayjs.duration(2, 'months');
const months = twoMonths.months(); // 2

搭配 diff 使用 duration​

若你希望搭配 dayjs#diff 來使用 duration 可以這麼做：

import dayjs from 'dayjs';
import duration from 'dayjs/plugin/duration';

dayjs.extend(duration);

const date1 = dayjs('2019-01-25');
const date2 = dayjs('2018-06-05');
const diffWithMonth = date1.diff(date2);

const durationWithDiff = dayjs.duration(diffWithMonth);
const months = durationWithDiff.months(); // 7
const days = durationWithDiff.days(); // 24（？）

直接使用 dayjs#diff 和搭配使用 dayjs#duration 的差異​

  • 透過 dayjs#diff 可以取得某兩個時間點之間的時間長度，但只能使用一個單位。
  • 若搭配 duration 使用的話，可以把 diff 取得的時間長度，轉換成多個不同的單位。
import dayjs from 'dayjs';
import duration from 'dayjs/plugin/duration';
import relativeTime from 'dayjs/plugin/relativeTime';

dayjs.extend(duration);
dayjs.extend(relativeTime);

const date1 = dayjs('2020-08-07T04:53:26.337Z');
const date2 = dayjs('2020-08-06T02:50:47.811Z');

const diffWithDay = date1.diff(date2, 'day');
const diffWithHour = date1.diff(date2, 'hour');
const diffWithMinute = date1.diff(date2, 'minute');

console.log({
  diffWithDay,
  diffWithHour,
  diffWithMinute,
});

const diff = date1.diff(date2);
const durationWithDiff = dayjs.duration(diff);
const months = durationWithDiff.months(); // 7
const days = durationWithDiff.days(); // 24（？）
const hours = durationWithDiff.hours();
const minutes = durationWithDiff.minutes(); // 24（？）
console.log({
  months,
  days,
  hours,
  minutes,
});

console.log('after humanize', durationWithDiff.humanize(true)); // after humanize in a day

Timezone​

const dateTime = '2025-10-17 12:00:00';

// 如果一開始的時間沒有時區資訊，dayjs 預設會直接用 browser time
dayjs(dateTime).format(); // 2025-10-17T12:00:00+08:00

// 進行時區轉換
dayjs(dateTime).tz("America/Toronto"); // 2025-10-17T00:00:00-04:00

// 如果在 tz 的第二個參數使用 true 則不會做時區轉換，而是把該時間套上指定的時區
dayjs(dateTime).tz("America/Toronto", true); // 2025-10-17T12:00:00-04:00

Tips​

dayjs 的物件在 JSON.stringify() 後，會自動轉換成 ISO String：

const now = dayjs();

// "{\"today\":\"2022-10-26T06:56:13.483Z\"}"
JSON.stringify({
    today: now,
})

Giscus