时间间隔 · D3.js API 中文手册

> [Wiki](Home) ▸ [[API Reference]] ▸ [[Time]] ▸ **Time Intervals** **Time intervals** are irregular! For example, there are 60 seconds in a minute, but 24 hours in a day. Even more confusing, some days have 23 or 25 hours due to [daylight saving time](http://en.wikipedia.org/wiki/Daylight_saving_time), and the standard [Gregorian calendar](http://en.wikipedia.org/wiki/Gregorian_calendar) uses months of differing lengths. And then there are leap years! To simplify manipulation of and iteration over time intervals, D3 provides a handful of time utilities in addition to the time [scale](Time-Scales) and [format](Time-Formatting). The utilities support both local time and UTC time. Local time is determined by the browser's JavaScript runtime; arbitrary time zone support would be nice, but requires access to the Olson zoneinfo files. ## Interval <a name="interval" href="#interval">#</a> d3.time.interval Returns the specified *interval*. The following intervals are supported: * d3.time.[second](#second) * d3.time.[minute](#minute) * d3.time.[hour](#hour) * d3.time.[day](#day) * d3.time.[week](#week) (alias for d3.time.[sunday](#sunday)) * d3.time.[sunday](#sunday) * d3.time.[monday](#monday) * d3.time.[tuesday](#tuesday) * d3.time.[wednesday](#wednesday) * d3.time.[thursday](#thursday) * d3.time.[friday](#friday) * d3.time.[saturday](#saturday) * d3.time.[month](#month) * d3.time.[year](#year) <a name="_interval" href="#_interval">#</a> interval(date) Alias for *interval*.floor(*date*). For example, `d3.time.day(new Date())` returns midnight (12:00 AM) on the current day, in local time. <a name="interval_floor" href="#interval_floor">#</a> interval.floor(date) Rounds down the specified *date*, returning the latest time interval before or equal to *date*. For example, `d3.time.day.floor(new Date())` returns midnight (12:00 AM) on the current day, in local time. <a name="interval_round" href="#interval_round">#</a> interval.round(date) Rounds up or down the specified *date*, returning the closest time interval to *date*. For example, `d3.time.day.round(new Date())` returns midnight (12:00 AM) on the current day if it is on or before noon, and midnight of the following day if it is after noon. <a name="interval_ceil" href="#interval_ceil">#</a> interval.ceil(date) Rounds up the specified *date*, returning the earliest time interval after or equal to *date*. For example, `d3.time.day.ceil(new Date())` returns midnight (12:00 AM) on the following day, in local time (unless you happen to run this code at exactly midnight, in which case it returns the current time). <a name="interval_range" href="#interval_range">#</a> interval.range(start, stop[, step]) Returns every time interval after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th interval will be returned, based on the interval number (such as day of month for d3.time.day). For example, a *step* of 2 will return the 1st, 3rd, 5th *etc.* of the month with d3.time.day. <a name="interval_offset" href="#interval_offset">#</a> interval.offset(date, step) Returns a new date equal to *date* plus *step* intervals. If *step* is negative, then the returned date will be before the specified *date*; if *step* is zero, then a copy of the specified *date* is returned. This method does not round the specified *date* to the interval. For example, if it is currently 5:34 PM, then `d3.time.day.offset(new Date(), 1)` returns 5:34 PM tomorrow (even if Daylight Savings Time changes!). <a name="interval_utc" href="#interval_utc">#</a> interval.utc Returns a corresponding time interval in UTC rather than local time. For example, `d3.time.day.range(start, stop)` returns local time days between *start* and *stop*, while `d3.time.day.utc.range(start, stop)` returns UTC days between *start* and *stop*. ## Intervals <a name="second" href="#second">#</a> d3.time.second Seconds (e.g., 01:23:45.0000 AM). Always 1,000 milliseconds long. <a name="minute" href="#minute">#</a> d3.time.minute Minutes (e.g., 01:02:00 AM). ECMAScript [explicitly ignores leap seconds](http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.1), so minutes are always 60 seconds (6e4 milliseconds) long. <a name="hour" href="#hour">#</a> d3.time.hour Hours (e.g., 01:00 AM). 60 minutes long (36e5 milliseconds). Note that advancing time by one hour can return the same hour number, or skip an hour number, due to Daylight Savings Time. <a name="day" href="#day">#</a> d3.time.day Days (e.g., February 7, 2012 at 12:00 AM). Most days are 24 hours long (864e5 milliseconds); however, with Daylight Savings Time, a day may be 23 or 25 hours long. <a name="week" href="#week">#</a> d3.time.week Alias for d3.time.[sunday](#sunday). A week is always 7 days, but ranges between 167 and 169 hours depending on Daylight Savings Time. <a name="sunday" href="#sunday">#</a> d3.time.sunday Sunday-based weeks (e.g., February 5, 2012 at 12:00 AM). <a name="monday" href="#monday">#</a> d3.time.monday Monday-based weeks (e.g., February 6, 2012 at 12:00 AM). <a name="tuesday" href="#tuesday">#</a> d3.time.tuesday Tuesday-based weeks (e.g., February 7, 2012 at 12:00 AM). <a name="wednesday" href="#wednesday">#</a> d3.time.wednesday Wednesday-based weeks (e.g., February 8, 2012 at 12:00 AM). <a name="thursday" href="#thursday">#</a> d3.time.thursday Thursday-based weeks (e.g., February 9, 2012 at 12:00 AM). <a name="friday" href="#friday">#</a> d3.time.friday Friday-based weeks (e.g., February 10, 2012 at 12:00 AM). <a name="saturday" href="#saturday">#</a> d3.time.saturday Saturday-based weeks (e.g., February 11, 2012 at 12:00 AM). <a name="month" href="#month">#</a> d3.time.month Months (e.g., February 1, 2012 at 12:00 AM). Ranges between 28 and 31 days. <a name="year" href="#year">#</a> d3.time.year Years (e.g., January 1, 2012 at 12:00 AM). Normal years are 365 days long; leap years are 366. ## Aliases <a name="seconds" href="#seconds">#</a> d3.time.seconds(start, stop[, step]) Alias for d3.time.[second](#second).[range](#interval_range). Returns the second boundaries (e.g., 01:23:45 AM) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th second will be returned, based on the second of the minute. For example, a *step* of 15 will return 9:01:45 PM, 9:02:00 PM, 9:02:15 PM, *etc.* <a name="minutes" href="#minutes">#</a> d3.time.minutes(start, stop[, step]) Alias for d3.time.[minute](#minute).[range](#interval_range). Returns the minute boundaries (e.g., 01:23 AM) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th minute will be returned, based on the minute of the hour. For example, a *step* of 15 will return 9:45 PM, 10:00 PM, 10:15 PM, *etc.* <a name="hours" href="#hours">#</a> d3.time.hours(start, stop[, step]) Alias for d3.time.[hour](#hour).[range](#interval_range). Returns the hour boundaries (e.g., 01 AM) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th hour will be returned, based on the hour of the day. For example, a *step* of 3 will return 9 PM, 12 AM, 3 AM, *etc.* <a name="days" href="#days">#</a> d3.time.days(start, stop[, step]) Alias for d3.time.[day](#day).[range](#interval_range). Returns the day boundaries (midnight) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th date will be returned, based on the day of the month. For example, a *step* of 2 will return the 1st, 3rd, 5th *etc.* of the month. <a name="weeks" href="#weeks">#</a> d3.time.weeks(start, stop[, step]) <a name="sundays" href="#sundays">#</a> d3.time.sundays(start, stop[, step]) <a name="mondays" href="#mondays">#</a> d3.time.mondays(start, stop[, step]) <a name="tuesdays" href="#tuesdays">#</a> d3.time.tuesdays(start, stop[, step]) <a name="wednesdays" href="#wednesdays">#</a> d3.time.wednesdays(start, stop[, step]) <a name="thursdays" href="#thursdays">#</a> d3.time.thursdays(start, stop[, step]) <a name="fridays" href="#fridays">#</a> d3.time.fridays(start, stop[, step]) <a name="saturdays" href="#saturdays">#</a> d3.time.saturdays(start, stop[, step]) Aliases for d3.time.interval.[range](#interval_range) etc. Returns the week boundaries (midnight Sunday) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th week will be returned, based on the week of the year. For example, a *step* of 4 will return January 2, January 30, February 27, *etc.* <a name="months" href="#months">#</a> d3.time.months(start, stop[, step]) Alias for d3.time.[month](#month).[range](#interval_range). Returns the month boundaries (e.g., January 01) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th month will be returned, based on the month of the year. For example, a *step* of 3 will return January, April, July, *etc.* <a name="years" href="#years">#</a> d3.time.years(start, stop[, step]) Alias for d3.time.[year](#year).[range](#interval_range). Returns the year boundaries (midnight January 1st) after or equal to *start* and before *stop*. If *step* is specified, then every *step*'th year will be returned. For example, a *step* of 5 will return 2010, 2015, 2020, *etc.* ## Counting <a name="dayOfYear" href="#dayOfYear">#</a> d3.time.dayOfYear(date) Returns the day number for the given date. The first day of the year (January 1) is always the 0th day. Unlike the [d3.time.format](Time-Formatting)'s %j directive, dayOfYear is 0-based rather than 1-based. <a name="weekOfYear" href="#weekOfYear">#</a> d3.time.weekOfYear(date) <a name="sundayOfYear" href="#sundayOfYear">#</a> d3.time.sundayOfYear(date) <a name="mondayOfYear" href="#mondayOfYear">#</a> d3.time.mondayOfYear(date) <a name="tuesdayOfYear" href="#tuesdayOfYear">#</a> d3.time.tuesdayOfYear(date) <a name="wednesdayOfYear" href="#wednesdayOfYear">#</a> d3.time.wednesdayOfYear(date) <a name="thursdayOfYear" href="#thursdayOfYear">#</a> d3.time.thursdayOfYear(date) <a name="fridayOfYear" href="#fridayOfYear">#</a> d3.time.fridayOfYear(date) <a name="saturdayOfYear" href="#saturdayOfYear">#</a> d3.time.saturdayOfYear(date) Returns the week number for the given date, where weeks start with the given day. The first day of the year (January 1) is always the 0th week. weekOfYear is an alias for sundayOfYear, which is equivalent to [d3.time.format](Time-Formatting)'s %U directive. mondayOfYear is equivalent to [d3.time.format](Time-Formatting)'s %W directive.