d3-time-format

此模組提供一個近似的 JavaScript 執行版本，來自於 C 標準函式庫中備受推崇的 strptime 和 strftime 函式，可用於解析或格式化 日期，並提供各種特定於區域的表示方式。若要格式化日期，請從規格說明 (一個包含所需格式 指令 的字串，由 % 表示) 中建立一個 格式化器；然後將一個日期傳遞給格式化器，它會回傳一個字串。例如，將目前日期轉換為人類可讀的字串

const formatTime = d3.utcFormat("%B %d, %Y");
formatTime(new Date()); // "May 31, 2023"

同樣地，若要將字串轉換回日期，請建立一個 解析器

const parseTime = d3.utcParse("%B %d, %Y");
parseTime("June 30, 2015"); // 2023-05-31

您也可以實作更精細的條件式時間格式。例如，以下是使用 時間區間 的多重縮放時間格式

const formatMillisecond = d3.utcFormat(".%L"),
    formatSecond = d3.utcFormat(":%S"),
    formatMinute = d3.utcFormat("%I:%M"),
    formatHour = d3.utcFormat("%I %p"),
    formatDay = d3.utcFormat("%a %d"),
    formatWeek = d3.utcFormat("%b %d"),
    formatMonth = d3.utcFormat("%B"),
    formatYear = d3.utcFormat("%Y");

function multiFormat(date) {
  return (d3.utcSecond(date) < date ? formatMillisecond
      : d3.utcMinute(date) < date ? formatSecond
      : d3.utcHour(date) < date ? formatMinute
      : d3.utcDay(date) < date ? formatHour
      : d3.utcMonth(date) < date ? (d3.utcWeek(date) < date ? formatDay : formatWeek)
      : d3.utcYear(date) < date ? formatMonth
      : formatYear)(date);
}

此模組由 D3 時間比例尺 使用，以產生人類可讀的刻度。

另請參閱 date.toLocaleString。

timeFormat(specifier)

d3.timeFormat("%b %d")

在 預設區域 上的 locale.format 別名。

timeParse(specifier)

d3.timeParse("%b %d")

locale.parse 的別名，在 預設區域設定 上。

utcFormat(specifier)

d3.utcFormat("%b %d")

locale.utcFormat 的別名，在 預設區域設定 上。

utcParse(specifier)

d3.utcParse("%b %d")

locale.utcParse 的別名，在 預設區域設定 上。

isoFormat

d3.isoFormat(new Date()) // "2023-05-31T18:17:36.788Z"

原始碼 · 完整的 ISO 8601 UTC 時間格式化器。在可用的情況下，此方法會使用 Date.toISOString 來格式化。

isoParse

d3.isoParse("2023-05-31T18:17:36.788Z")

原始碼 · 完整的 ISO 8601 UTC 時間剖析器。在可用的情況下，此方法會使用 日期建構函式 來剖析字串。如果您依賴根據 ISO 8601 對輸入格式進行嚴格驗證，您應該建構一個 UTC 剖析器函式

const strictIsoParse = d3.utcParse("%Y-%m-%dT%H:%M:%S.%LZ");

locale.format(specifier)

d3.timeFormat("%b %d")

原始碼 · 傳回給定字串 specifier 的新格式化器。specifier 字串可能包含下列指令

• %a - 縮寫的星期名稱.*
• %A - 完整的星期名稱.*
• %b - 縮寫的月份名稱.*
• %B - 完整的月份名稱.*
• %c - 區域設定的日期和時間，例如 %x, %X.*
• %d - 以十進位數字表示的月份中第幾天，前面補零 [01,31]。
• %e - 以十進位數字表示的月份中第幾天，前面補空格 [ 1,31]；等於 %_d。
• %f - 微秒，以十進位數字表示 [000000, 999999]。
• %g - ISO 8601 週為基礎的年，不含世紀，以十進位數字表示 [00,99]。
• %G - ISO 8601 週為基礎的年，含世紀，以十進位數字表示。
• %H - 小時（24 小時制），以十進位數字表示 [00,23]。
• %I - 小時（12 小時制），以十進位數字表示 [01,12]。
• %j - 一年中的第幾天，以十進位數字表示 [001,366]。
• %m - 月份，以十進位數字表示 [01,12]。
• %M - 分鐘，以十進位數字表示 [00,59]。
• %L - 毫秒，以十進位數字表示 [000, 999]。
• %p - 上午或下午*。
• %q - 一年中的第幾個季度，以十進位數字表示 [1,4]。
• %Q - 自 UNIX 紀元以來的毫秒數。
• %s - 自 UNIX 紀元以來的秒數。
• %S - 秒，以十進位數字表示 [00,61]。
• %u - 以星期一為基礎的（ISO 8601）星期，以十進位數字表示 [1,7]。
• %U - 以星期日為基礎的一年中的第幾週，以十進位數字表示 [00,53]。
• %V - ISO 8601 一年中的第幾週，以十進位數字表示 [01, 53]。
• %w - 以星期日為基礎的星期，以十進位數字表示 [0,6]。
• %W - 以星期一為基礎的一年中的第幾週，以十進位數字表示 [00,53]。
• %x - 地區的日期，例如 %-m/%-d/%Y*。
• %X - 地區的時間，例如 %-I:%M:%S %p*。
• %y - 不含世紀的年，以十進位數字表示 [00,99]。
• %Y - 含世紀的年，以十進位數字表示，例如 1999。
• %Z - 時區偏移，例如 -0700、-07:00、-07 或 Z。
• %% - 百分號字元 (%)。

標有星號 (*) 的指令可能會受到 地區定義 的影響。

對於 %U，新的一年在第一個星期日之前的日子都被視為第 0 週。對於 %W，新的一年在第一個星期一之前的日子都被視為第 0 週。週數使用 interval.count 計算。例如，2015-52 和 2016-00 表示 2015 年 12 月 28 日星期一，而 2015-53 和 2016-01 表示 2016 年 1 月 4 日星期一。這與 ISO 週日期 規範（%V）不同，後者使用更複雜的定義！

對於 %V、%g 和 %G，根據 strftime 手冊頁

在這個系統中，星期從星期一開始，從第一個星期開始編號為 01，最後一個星期編號為 52 或 53。第 1 週是新的一年開始後，有四天或四天以上落在該週的第一個星期（或者同義地說，第 01 週是：該年包含星期四的第一個星期；或者，是包含 1 月 4 日的星期）。如果 ISO 週數屬於前一年或下一年，則使用該年。

表示指令的 % 符號後面可以緊接著一個填充修飾符

• 0 - 零填充
• _ - 空格填充
• - - 停用填充

如果沒有指定填充修飾符，則所有指令的預設值為 0，但 %e 例外，其預設值為 _。（在 strftime 和 strptime 的某些實作中，指令可以包含一個選用的欄位寬度或精度；此功能尚未實作。）

回傳的函數會格式化指定的 日期，並回傳對應的字串。

const formatMonth = d3.timeFormat("%B"),
    formatDay = d3.timeFormat("%A"),
    date = new Date(2014, 4, 1); // Thu May 01 2014 00:00:00 GMT-0700 (PDT)

formatMonth(date); // "May"
formatDay(date); // "Thursday"

locale.parse(specifier)

d3.timeParse("%b %d")

原始碼 · 回傳給定字串 specifier 的新剖析器。specifier 字串可以包含與 locale.format 相同的指令。%d 和 %e 指令在剖析時被視為相同。

回傳的函數會剖析指定的 字串，並回傳對應的 日期，或者如果無法根據此格式的 specifier 剖析字串，則回傳 null。剖析很嚴格：如果指定的 字串 與關聯的 specifier 不完全相符，則此方法會回傳 null。例如，如果關聯的 specifier 是 %Y-%m-%dT%H:%M:%SZ，則字串 "2011-07-01T19:15:28Z" 會如預期般被剖析，但 "2011-07-01T19:15:28"、"2011-07-01 19:15:28" 和 "2011-07-01" 會回傳 null。（請注意，此處的文字 Z 與時區偏移指令 %Z 不同。）如果需要更彈性的剖析器，請依序嘗試多種格式，直到其中一種回傳非 null 為止。

locale.utcFormat(specifier)

d3.utcFormat("%b %d")

原始碼 · 等同於 locale.format，但所有指令都會被詮釋為 世界協調時間 (UTC)，而不是當地時間。

locale.utcParse(specifier)

d3.utcParse("%b %d")

原始碼 · 等同於 locale.parse，但所有指令都會被詮釋為 世界協調時間 (UTC)，而不是當地時間。

timeFormatLocale(定義)

const enUs = d3.timeFormatLocale({
  dateTime: "%x, %X",
  date: "%-m/%-d/%Y",
  time: "%-I:%M:%S %p",
  periods: ["AM", "PM"],
  days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
  shortDays: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
  months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
  shortMonths: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
});

原始碼 · 傳回一個地區物件，其具有 地區.format、地區.parse、地區.utcFormat、地區.utcParse 方法，用於指定的定義。定義必須包含下列屬性

• dateTime - 日期和時間 (%c) 格式規範符號 (例如，"%a %b %e %X %Y")。
• date - 日期 (%x) 格式規範符號 (例如，"%m/%d/%Y")。
• time - 時間 (%X) 格式規範符號 (例如，"%H:%M:%S")。
• periods - 上午和下午的等效字 (例如，["AM", "PM"])。
• days - 星期的全名，從星期日開始。
• shortDays - 星期的簡稱，從星期日開始。
• months - 月份的全名 (從一月開始)。
• shortMonths - 月份的簡稱 (從一月開始)。

timeFormatDefaultLocale(定義)

const enUs = d3.timeFormatDefaultLocale({
  dateTime: "%x, %X",
  date: "%-m/%-d/%Y",
  time: "%-I:%M:%S %p",
  periods: ["AM", "PM"],
  days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
  shortDays: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
  months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
  shortMonths: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
});

原始碼 · 等同於 d3.timeFormatLocale，但它也會將 d3.timeFormat、d3.timeParse、d3.utcFormat 和 d3.utcParse 重新定義為新的地區的 地區.format、地區.parse、地區.utcFormat 和 地區.utcParse。如果您未設定預設地區，它會預設為 美國英語。