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 时间解析器。如果可用，此方法将使用 Date 构造函数 解析字符串。如果您依赖于根据 ISO 8601 对输入格式进行严格验证，则应构造一个 UTC 解析函数

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

locale.format(specifier)

d3.timeFormat("%b %d")

源代码 · 返回给定字符串 *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 - AM 或 PM。*
• %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 周是新的一年里至少有 4 天的那一周（或者，等效地，第 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* 的新解析器。规范符字符串可以包含与 locale.format 相同的指令。%d 和 %e 指令在解析时被认为是等效的。

返回的函数解析指定的字符串，返回相应的日期，如果字符串无法根据此格式的规范解析，则返回 null。解析是严格的：如果指定的字符串不完全匹配关联的规范，则此方法返回 null。例如，如果关联的规范为%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不同。）如果需要更灵活的解析器，请尝试按顺序使用多个格式，直到其中一个返回非空值。

locale.utcFormat(specifier)

d3.utcFormat("%b %d")

源代码 · 等同于 locale.format，但所有指令都被解释为协调世界时 (UTC)，而不是本地时间。

locale.utcParse(specifier)

d3.utcParse("%b %d")

源代码 · 等同于 locale.parse，但所有指令都被解释为协调世界时 (UTC)，而不是本地时间。

timeFormatLocale(definition)

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"]
});

源代码 · 返回针对指定definition的locale对象，包含locale.format、locale.parse、locale.utcFormat、locale.utcParse方法。definition必须包含以下属性

• 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(definition)

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 重新定义为新区域设置的 locale.format、locale.parse、locale.utcFormat 和 locale.utcParse。如果您没有设置默认区域设置，它将默认为美式英语。