d3-time-format

本模块提供了经典 C 标准库中 strptime 和 strftime 函数的近似 JavaScript 实现，可用于解析或格式化各种特定区域表示的 日期。要格式化日期，请从一个格式说明符（带有所需格式 指令 的字符串，指示符为 %）创建一个 formatter；然后将日期传递给格式化器，它将返回一个字符串。例如，要将当前日期转换为可读字符串:

🌐 This module provides an approximate JavaScript implementation of the venerable strptime and strftime functions from the C standard library, and can be used to parse or format dates in a variety of locale-specific representations. To format a date, create a formatter from a specifier (a string with the desired format directives, indicated by %); then pass a date to the formatter, which returns a string. For example, to convert the current date to a human-readable string:

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

同样，要将字符串转换回日期，请创建一个解析器：

🌐 Likewise, to convert a string back to a date, create a parser:

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

你也可以实现更复杂的条件时间格式。例如，这里有一个使用时间间隔的多尺度时间格式：

🌐 You can implement more elaborate conditional time formats, too. For example, here’s a multi-scale time format using time intervals:

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 时间刻度 用于生成可读的刻度。

🌐 This module is used by D3 time scales to generate human-readable ticks.

另请参见 date.toLocaleString。

🌐 Also see date.toLocaleString.

timeFormat(specifier)

d3.timeFormat("%b %d")

locale.format 在 默认语言环境 下的别名。

🌐 An alias for locale.format on the default locale.

timeParse(specifier)

d3.timeParse("%b %d")

locale.parse 在 默认语言环境 下的别名。

🌐 An alias for locale.parse on the default locale.

utcFormat(specifier)

d3.utcFormat("%b %d")

在默认语言环境中，locale.utcFormat 的别名。

🌐 An alias for locale.utcFormat on the default locale.

utcParse(specifier)

d3.utcParse("%b %d")

在默认语言环境中，locale.utcParse 的别名。

🌐 An alias for locale.utcParse on the default locale.

iso格式

🌐 isoFormat

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

来源 · 完整的 ISO 8601 UTC 时间格式化器。在可用的情况下，此方法将使用 Date.toISOString 进行格式化。

iso解析

🌐 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 返回一个新的格式化器。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。
• %% - 一个字面上的百分号（%）。

带星号（*）的指令可能会受到区域设置定义的影响。

🌐 Directives marked with an asterisk (*) may be affected by the locale definition.

对于 %U，新年的第一天之前的所有日期都被视为第0周。对于 %W，新年的第一周一之前的所有日期都被视为第0周。周数是使用 [*interval*.count](./d3-time.md#interval_count) 计算的。例如，2015-52 和 2016-00 表示 2015 年 12 月 28 日星期一，而 2015-53 和 2016-01 表示 2016 年 1 月 4 日星期一。这与 [ISO 周日期](https://en.wikipedia.org/wiki/ISO_week_date) 规范（%V`）不同，后者使用了更复杂的定义!

🌐 For %U, all days in a new year preceding the first Sunday are considered to be in week 0. For %W, all days in a new year preceding the first Monday are considered to be in week 0. Week numbers are computed using interval.count. For example, 2015-52 and 2016-00 represent Monday, December 28, 2015, while 2015-53 and 2016-01 represent Monday, January 4, 2016. This differs from the ISO week date specification (%V), which uses a more complicated definition!

对于 %V、%g 和 %G，根据 strftime 手册页：

🌐 For %V,%g and %G, per the strftime man page:

在这个系统中，星期从星期一开始，并且编号从01开始，第一周为01，最后一周为52或53。第1周是指新年中包含四天或更多天数的第一周（或者，同义地，第01周是：包含星期四的那一年的第一周；或者，包含1月4日的那一周）。如果ISO周数属于前一年或下一年，则使用该年。

% 标志表示指令，后面可以紧跟一个填充修饰符：

🌐 The % sign indicating a directive may be immediately followed by a padding modifier:

• 0 - zero-padding
• _ - space-padding
• - - 禁用填充

如果没有指定填充修饰符，所有指令的默认值都是 0，除了 %e，其默认值为 _。（在某些 strftime 和 strptime 的实现中，指令可能包含可选的字段宽度或精度；此功能尚未实现。）

🌐 If no padding modifier is specified, the default is 0 for all directives except %e, which defaults to _. (In some implementations of strftime and strptime, a directive may include an optional field width or precision; this feature is not yet implemented.)

返回的函数格式化指定的*日期*，并返回相应的字符串。

🌐 The returned function formats a specified date, returning the corresponding string.

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 指令在解析时被视为等效。

返回的函数解析指定的字符串，返回对应的日期，如果字符串无法根据此格式说明符解析，则返回 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 不同。）如果需要更灵活的解析器，可尝试按顺序使用多种格式，直到一个返回非 null。

locale.utcFormat(specifier)

d3.utcFormat("%b %d")

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

locale.utcParse(specifier)

d3.utcParse("%b %d")

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

timeFormatLocale(定义)

🌐 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 - 上午和下午的等价物（例如 <i>，["AM", "PM"]）。
• days - 星期几的全名，从星期日开始。
• shortDays - 工作日的缩写，从周日开始。
• months - 月份的全名（从一月开始）。
• shortMonths - 月份的缩写（从一月开始）。

timeFormatDefaultLocale(定义)

🌐 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。如果你不设置默认语言环境，它会默认使用 美式英语。