Question

这个模块提供了来自 C 标准库 strptime 和 strftime 的 JavaScript 实现, 并且可以用来对多种区域形式的 dates 进行解析或格式化。格式化日期，首先根据指定的说明符(由 % 表示的用来描述格式的directives)创建一个 formatter；然后将日期传递给 formatter 返回一个字符串。例如将当前日期转换为人类友好的字符串:

var formatTime = d3.timeFormat("%B %d, %Y");
formatTime(new Date); // "June 30, 2015"

同样的，将字符串解析为日期类型，需要创建一个 parser:

var parseTime = d3.timeParse("%B %d, %Y");
parseTime("June 30, 2015"); // Tue Jun 30 2015 00:00:00 GMT-0700 (PDT)

你也可以实现更复杂的条件时间格式。例如使用 time intervals 实现的 multi-scale time format:

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

function multiFormat(date) {
  return (d3.timeSecond(date) < date ? formatMillisecond
      : d3.timeMinute(date) < date ? formatSecond
      : d3.timeHour(date) < date ? formatMinute
      : d3.timeDay(date) < date ? formatHour
      : d3.timeMonth(date) < date ? (d3.timeWeek(date) < date ? formatDay : formatWeek)
      : d3.timeYear(date) < date ? formatMonth
      : formatYear)(date);
}

这个模块可以被 time scales 用来生成人类友好的刻度.

Installing

NPM 安装: npm install d3-time-format. 此外还可以下载 latest release. 可以直接从 d3js.org 以 standalone library 或作为 D3 4.0 的一部分直接载入. 支持 AMD, CommonJS 以及基本的标签引入形式，如果使用标签引入则会暴露全局 d3 变量:

<script src="https://d3js.org/d3-time.v1.min.js"></script>
<script src="https://d3js.org/d3-time-format.v2.min.js"></script>
<script>

var format = d3.timeFormat("%x");

</script>

区域文件托管在 unpkg，可以直接使用 d3.json 加载. 例如，将默认的区域配置设置为 Russian：

d3.json("https://unpkg.com/d3-time-format@2/locale/ru-RU.json", function(error, locale) {
  if (error) throw error;

  d3.timeFormatDefaultLocale(locale);

  var format = d3.timeFormat("%c");

  console.log(format(new Date)); // понедельник,  5 декабря 2016 г. 10:31:59
});

在浏览器中测试 d3-time-format.

API Reference

d3.timeFormat(specifier) <源码>

default locale(默认区域设置) 下 locale.format 的别名。

d3.timeParse(specifier) <源码>

default locale(默认区域设置) 下 locale.parse 的别名。

d3.utcFormat(specifier) <源码>

default locale(默认区域设置) 下 locale.utcFormat 的别名。

d3.utcParse(specifier) <源码>

default locale(默认区域设置) 下 locale.utcParse 的别名。

d3.isoFormat <>

符合 ISO 8601 的 UTC 日期格式化器。这个方法使用 Date.toISOString 来格式化日期。

d3.isoParse <>

符合 ISO 8601 的 UTC 日期解析器。这个方法使用 Date constructor 来解析字符串。如果字符串严格依据 ISO 8601 标准，则可以构建一个 UTC parser function:

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

locale.format(specifier) <源码>

根据指定的 specifier 返回一个新的日期格式化工具。指定的 specifier 必须包含以下指令符:

• %a - 简写的周?.*
• %A - 周?的全称.*
• %b - 简写的月.*
• %B - 月的全称.*
• %c - 区域日期和时间, 比如 %x, %X.*
• %d - 使用 0 填补位数的天 [01,31].
• %e - 使用空格填补位数的天 [ 1,31]; 等价于 %_d.
• %f - 微秒 [000000, 999999].
• %H - 24 小时制小时 [00,23].
• %I - 12 小时制小时 [01,12].
• %j - 一年中的第几天 [001,366].
• %m - 月份 [01,12].
• %M - 分钟 [00,59].
• %L - 毫秒 [000, 999].
• %p - AM 或 PM.*
• %Q - UNIX 毫秒.
• %s - UNIX 秒.
• %S - 秒 [00,61].
• %u - 一周中的第几天 [1, 7] (ISO 8601)
• %U - 一年中的第几周 [00,53].
• %V - 一年中的第几周 [01,53] (ISO 8601)
• %w - 从周日开始算起，是所在周的第几天 [0,6].
• %W - 一年中的第几周，从周一开始算新的一周 [00,53].
• %x - 区域日期格式, 比如 %m/%d/%Y.不同地方格式不一样*
• %X - 区域时间格式, 比如 %H:%M:%S.不同地方格式不一样*
• %y - 所在世纪的第几年( 16 ) [00,99].
• %Y - 年的全写( 2016 ).
• %Z - 返回当前时区，比如 -0700, -07:00, -07, or Z.
• %% - 百分比 (%).

带有星号 (*) 的指令符可能会受 locale definition 的影响。

对于 %U 来说，在第一个星期日之前的新年里的所有日子都被认为是在第 0 周. 对于 %W ，在第一个星期一之前的新年里的所有日子都被认为是在第 0 周。周的数量可以使用 interval.count 来计算。例如 2015-52 和 2016-00 代表 Monday, December 28, 2015 而 2015-53 和 2016-01 代表 Monday, January 4, 2016. 这与 ISO week date 说明符 %V 不同，它是一个更复杂的定义。

对于 %V, strftime man page 里是这样解释的:

在这个系统中，周起始于 Monday，第一周从 01 开始而最后一周为 52 或 53。Week 1 是第 1 周，其中 4 天或更多天处于新的一年中(或者同理，week 01 是包含 Thursday 的第一周；或者包含一月四号).

% 符号后面可能会跟着一个填充字符:

• 0 - 0 填充
• _ - 空格填充
• - - 禁止填充

如果没有指定填充修饰符，则默认除了 %e 以外所有的指令符使用 0 填充，%e 默认的填充符为 _. (在某些 strftime 和 strptime 的实现中，一个指令符可能包括一个可选的字段宽度或精度，但是这个特性在此模块中没有被实现)

返回的函数可以格式化指定的 date， 返回对应的字符串。

var 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) <源码>

根据指定的 specifier 返回一个新的解析器。指定的字符串可以包含和 Locales

d3.timeFormatLocale(definition) <源码>

根据指定的 definition 定义的 locale.format, locale.parse, locale.utcFormat, locale.utcParse 方法返回一个 locale 对象。definition 必须包含以下属性:

• dateTime - 日期和时间 (%c) 格式化说明符 (例如., "%a %b %e %X %Y").
• date - 日期 (%x) 格式化说明符 (例如, "%m/%d/%Y").
• time - 时间 (%X) 格式化说明符 (例如, "%H:%M:%S").
• periods - A.M. 和 P.M. (例如, ["AM", "PM"]).
• days - 以 Sunday 为起始的周几的全称.
• shortDays - 以 Sunday 为起始的周几的简称.
• months - 以 January 为起始的月份的全称.
• shortMonths - 以 January 为起始的月份的简称.

参考 Localized Time Axis II.

d3.timeFormatDefaultLocale(definition) <源码>

等价于 d3.timeFormatLocale, 只不过为 locale.format, locale.parse, locale.utcFormat 和 locale.utcParse 重新定义了 d3.timeFormat, d3.timeParse, d3.utcFormat 和 d3.utcParse。如果没有设置默认的时区，则默认为 U.S. English.

参考 Localized Time Axis.