HOWTO · JavaScript

在 JavaScript 中以 12 小時 AM/PM 格式顯示日期時間

本教程展示瞭如何以 12 小時 AM/PM 格式顯示 JavaScript 日期時間。使用不同的方法,例如建立我們自己的函式,Date.prototype.toLocaleString,Date.prototype.toLocaleTimeString,和 moment.js 方法來實現這一點。

本頁內容

JavaScript 的 Date 儲存的是時間值,本身沒有唯一通用的顯示格式。各種方法會將這個值轉成文字,而結果可能取決於你使用本地時間、地區設定,或自訂格式規則。本指南說明如何產生包含小時、分鐘、秒與 AM/PM 標記的 12 小時制時間,也會介紹如何只顯示時間或同時顯示日期。

使用原生 JavaScript 函式格式化日期

簡短的輔助函式可讓你在不使用函式庫的情況下,精確控制標點符號與大小寫。getHours()、getMinutes() 和 getSeconds() 會依照執行環境的本地時區讀取日期。取餘數運算可將小時轉成 12 小時制;由於午夜和中午取餘數後都會得到 0,因此要將這個值轉成 12。分鐘和秒數不足十時要補零,讓它們維持兩位數。

執行以下範例:

本節中的程式碼以及顯示的標籤或輸出仍為英文。

function formatAmPm(date) {
  const hour24 = date.getHours();
  const period = hour24 < 12 ? 'AM' : 'PM';
  const hour12 = hour24 % 12 || 12;
  const twoDigits = (value) => String(value).padStart(2, '0');

  return `${twoDigits(hour12)}:${twoDigits(date.getMinutes())}:${twoDigits(date.getSeconds())} ${period}`;
}

const sample = new Date(2024, 0, 1, 0, 5, 9);
console.log(formatAmPm(sample));

數值形式的 Date 建構子使用從零開始計算的月份,因此 0 代表一月。這個範例會建立 2024 年 1 月 1 日本地時間的午夜。當時間是中午(12:00:00 PM)或下午時,輔助函式也會正確切換標記,並將小時轉換為 1 到 12 的範圍。如果要以 UTC 格式化時間,請改用 getUTC... 方法;不要混用本地時間的 getter 與 UTC getter。

使用 Date.prototype.toLocaleString 顯示地區化日期與時間

若結果需要同時包含日期和時間,並遵循特定地區的慣例,請使用 Date.prototype.toLocaleString。hour、minute 和 second 選項會指定要顯示的時間部分,而 hour12: true 則會要求使用 12 小時制。地區設定可能會改變排列順序、標點、空格和 AM/PM 標記,因此不要假設不同環境產生的整段字串都會完全相同。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

const date = new Date(2024, 0, 1, 13, 5, 9);
const formatted = date.toLocaleString('en-US', {
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
  hour: 'numeric',
  minute: '2-digit',
  second: '2-digit',
  hour12: true,
});
console.log(formatted);

這裡的選項會要求同時顯示日期與時間。在支援的環境中,minute 和 second 會使用兩位數;hour12 則會選用 12 小時制。最後的排列方式和標記由地區資料決定;顯示時請直接使用回傳的字串,不要假設每個瀏覽器都會插入相同的逗號或空格。

使用 Date.prototype.toLocaleTimeString 僅顯示地區化時間

不需要日期時,請使用 Date.prototype.toLocaleTimeString。它接受與前一個範例相同的地區和時間選項,但只會格式化時間部分。因此,當 toLocaleString 包含日期時,兩者的用途並不相同。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

const date = new Date(2024, 0, 1, 13, 5, 9);
const formatted = date.toLocaleTimeString('en-US', {
  hour: 'numeric',
  minute: '2-digit',
  second: '2-digit',
  hour12: true,
});
console.log(formatted);

明確指定選項能清楚表達要顯示哪些部分,但標點和確切的 AM/PM 標記等細節仍由地區化實作決定。如果產品需要固定字串格式,請使用自訂輔助函式,不要依賴地區化呈現方式。

使用 Moment.js 格式化日期

如果專案已載入函式庫,便可使用 Moment.js 格式化日期。它是額外的相依項目:以下運算式假設應用程式已匯入或載入 moment。格式標記 hh、mm 和 ss 分別要求以兩位數顯示 12 小時制的小時、分鐘和秒;A 則會輸出大寫的 AM/PM 標記。例如,可使用 moment(date).format('hh:mm:ss A')。如果純 JavaScript 檔案尚未載入 Moment.js,請勿直接複製這個運算式。新專案可以使用內建的 Intl 方法或簡短的原生輔助函式,避免增加這項相依性。

選擇合適的方法並檢查邊界案例

若輸出必須符合 hh:mm:ss AM 這類固定格式,請選用原生輔助函式。若只需要地區化時間,請使用 Date.prototype.toLocaleTimeString;若需要同時顯示日期與時間,則使用 Date.prototype.toLocaleString。當應用程式已使用 Moment.js,且以格式標記指定輸出符合專案需求時,可以選用它。這些方法不保證輸出完全相同:原生輔助函式會產生特定版面,地區化方法會配合地區資料,而 Moment.js 則依照格式標記輸出。

調整格式化程式時,請檢查幾個具代表性的本地時間:午夜應顯示為 12 和 AM,中午應維持 12 和 PM,而個位數的分鐘和秒數應補零。也要檢查下午的時間,確認以 24 小時制小時減去十二後,顯示結果正確。這些檢查能找出常見錯誤,例如把午夜或中午顯示成 0,或承諾輸出 HH:MM:SS,範例卻漏掉秒數。如果輸入代表另一個時區的時間戳記,請先決定介面要顯示瀏覽者的本地時間還是 UTC,再進行格式化。