首页 > 代码库 > [Javascript] 轻量级的JavaScript日期处理类库xDate使用指南
[Javascript] 轻量级的JavaScript日期处理类库xDate使用指南
XDate是一个请谅解的JavaScript的原生Date对象的封装库,提供增强的功能解析,格式化和日期处理。使用起来就和JavaScript自己的对象和方法一样,非常简单。
XDate是一个请谅解的JavaScript的原生Date对象的封装库,提供增强的功能解析,格式化和日期处理。使用起来就和JavaScript自己的对象和方法一样,非常简单。
使用说明:
首先在页面中添加 XDate 的 JS 文件
<script src="http://www.mamicode.com/xdate.js"></script>
之后就可以了 new 一个日期出来,如
var d = new XDate("2012-9-9");
var c = new XDate(2012, 7, 8);
d.addDays(10);
var a = d.toString("yyyy/MM/dd");
Constructors
- new XDate()
- 使用当前的日期和时间创建一个新的XDate
- new XDate(xdate)
- 创建一个新的XDate从一个xdate对象
- new XDate(nativeDate)
- 创建一个新的XDate从一个指定的日期
- new XDate(milliseconds)
- 通过UTC毫秒数创建一个新的XDate。
- new XDate(year, month, date, hours, minutes, seconds, milliseconds)
- new XDate(dateString)
Read more about date-string parsing
下面是xDate的常用方法:
Getters
- .getFullYear()
- Returns the 4-digit year (ex: 2012)
- .getMonth()
- Returns the month of the year. (0-11)
Value is zero-index, meaning Jan=0, Feb=1, Mar=2, etc. - .getWeek()
- Returns the ISO week number of the year. (1-53)
- .getDate()
- Returns the date of the month. (1-31)
- .getDay()
- Returns the day-of-week as a number. (0-6)
Sun=0, Mon=1, Tue=2, etc. - .getHours()
- Returns the hour of the day. (0-23)
- .getMinutes()
- Returns the minute of the hour. (0-59)
- .getSeconds()
- Returns the second of the minute. (0-59)
- .getMilliseconds()
- Returns the millisecond of the second. (0-999)
- .getTime()
- Returns the number of milliseconds since the epoch.
- .valueOf()
- Returns the number of milliseconds since the epoch. Identical to
getTime
.
Setters
- .setFullYear(year, preventOverflow)
year
is a 4-digit year- .setMonth(month, preventOverflow)
month
is zero-indexed, meaning Jan=0, Feb=1, Mar=2, etc.- .setWeek(week, year)
Moves the xdate to the Monday of the given week with time 00:00:00. The week is represented by a given ISO week number and an optional
year
. Ifyear
is omitted, the xdate‘s year with be used.- .setDate(date)
- Sets the date of the month. (1-31)
- .setHours(hours)
- Sets the hour of the day. (0-23)
- .setMinutes(minutes)
- Sets the minute of the hour. (0-59)
- .setSeconds(seconds)
- Sets the second of the minute. (0-59)
- .setMilliseconds(milliseconds)
- Sets the millisecond of the second. (0-999)
- .setTime(milliseconds)
- Sets the number of milliseconds since the epoch.
Setting preventOverflow
to true
prevents a date from "overflowing" into the next month. Example:
d=newXDate(2011,7,31);// August 31d.setMonth(8);// Septemberd.toString();// October 1st!!! because there are only 30 says in September// let‘s try this with preventOverflow...d=newXDate(2011,7,31);// August 31d.setMonth(8,true);// Septemberd.toString();// September 30!
Setting preventOverflow
to true
guarantees the date will be in desired month. It is optional and defaults to false
.
Adding
The following methods add or subtract time from the XDate:
- .addYears(years, preventOverflow)
- .addMonths(months, preventOverflow)
- .addWeeks(weeks)
- .addDays(days)
- .addHours(hours)
- .addMinutes(minutes)
- .addSeconds(seconds)
- .addMilliseconds(milliseconds)
If a value is negative, subtraction will occur. Values may be floating-point numbers.
Please note, these methods directly modify the object. Use clone if you need a copy.
Diffing
The following methods return the amount of time that must be added to the XDate in order to arrive at otherDate
.
- .diffYears(otherDate)
- .diffMonths(otherDate)
- .diffWeeks(otherDate)
- .diffDays(otherDate)
- .diffHours(otherDate)
- .diffMinutes(otherDate)
- .diffSeconds(otherDate)
- .diffMilliseconds(otherDate)
otherDate can be an XDate, a native Date, a milliseconds time, or a date-string.
The results will be positive or negative depending on the ordering of the dates:
varthanksgiving=newXDate(2011,10,24);varchristmas=newXDate(2011,11,25);thanksgiving.diffDays(christmas);// 31christmas.diffDays(thanksgiving);// -31
Also, the result can potentially be a floating-point number:
varjan2011=newXDate(2011,0,1);varjul2012=newXDate(2012,6,1);jan2011.diffYears(jul2012);// 1.5
You‘ll have to do the rounding or flooring yourself.
Parsing
Date-strings must either be in ISO8601 format or IETF format (like "Mon Sep 05 2011 12:30:00 GMT-0700 (PDT)")
ISO8601 is the preferred format. Examples:
"2011-09-05"
"2011-09-05T12:30:00"
"2011-09-05T12:30:00-07:00"
"2011-09-05T12:30:00Z"
Advanced: extending the parser
Formatting
- .toString(formatString, settings)
- If
formatString
is not specified, a browser-produced IETF string will be returned.settings
can be a name of an available locale or an object that overrides the default locale‘s settings. - .toUTCString(formatString, settings)
- Same as
toString
but gets its values from the UTC version of the date. As a result, "Z" will be displayed as the timezone. - .toISOString()
- Returns an ISO8601 string that has been normalized to UTC. Will have a "Z" timezone indicator. See the native Date‘s specs for toISOString.
- .toDateString()
- Same as native Date‘s toDateString
- .toTimeString()
- Same as native Date‘s toTimeString
- .toLocaleString()
- Same as native Date‘s toLocaleString
- .toLocaleDateString()
- Same as native Date‘s toLocaleDateString
- .toLocaleTimeString()
- Same as native Date‘s toLocaleTimeString
A formatString
can contain any of the following tokens:
fff | milliseconds, 3-digits |
---|---|
s | seconds |
ss | seconds, 2-digits |
m | minutes |
mm | minutes, 2-digits |
h | hours, 12-hour clock |
hh | hours, 12-hour clock, 2-digits |
H | hours, 24-hour clock |
HH | hours, 24-hour clock, 2-digits |
d | date number |
dd | date number, 2-digits |
ddd | day name, 3-characters (like "Sun") |
dddd | day name, full (like "Sunday") |
M | month number (Jan=1, Feb=2, etc) |
MM | month number, 2-digits |
MMM | month name, 3-characters (like "Jan") |
MMMM | month name, full (like "January") |
yy | year, 2-digits |
yyyy | year, 4-digits |
t | a/p |
tt | am/pm |
T | A/P |
TT | AM/PM |
z | timezone offset hour (like "-7") or "Z" |
zz | timezone offset hour, 2-digits (like "-07") or "Z" |
zzz | timezone offset hour, 2-digits, and minutes (like "-07:00") or "Z" |
w | ISO week number |
ww | ISO week number, 2 digits |
S | day-of-week ordinal (like "st", "nd", "rd") |
i | ISO8601 format, without a timezone indicator |
u | ISO8601 format, with a timezone indicator |
Example:
vard=newXDate(2012,5,8);d.toString("MMM d, yyyy");// "Jun 8, 2012"d.toString("i");// "2012-06-08T00:00:00"d.toString("u");// "2012-06-08T00:00:00-07:00"
If you want to have literal text in your formatString, enclose it in single quotes:
vard=newXDate(2012,5,8);d.toString("‘the month is‘ MMMM");// "the month is June"
A literal single quote is represented by two consecutive single quotes.
If you want to output text only if certain values are non-zero, enclose your tokens in parenthesis:
newXDate(2011,0,1,6,0).toString(‘M/d/yy h(:mm)TT‘);// "1/1/11 6AM"newXDate(2011,0,1,6,30).toString(‘M/d/yy h(:mm)TT‘);// "1/1/11 6:30AM"
Advanced:
changing locale
extending the formatter
UTC Methods
The following methods are similar to previously mentioned methods but operate on the UTC values of the date:
- .getUTCFullYear()
- .getUTCMonth()
- .getUTCWeek()
- .getUTCDate()
- .getUTCDay()
- .getUTCHours()
- .getUTCMinutes()
- .getUTCSeconds()
- .getUTCMilliseconds()
- .setUTCFullYear(year)
- .setUTCMonth(month)
- .setUTCWeek(week, year)
- .setUTCDate(date)
- .setUTCHours(hours)
- .setUTCMinutes(minutes)
- .setUTCSeconds(seconds)
- .setUTCMilliseconds(milliseconds)
UTC Mode
Just like a native Date, an XDate is represented by its number of milliseconds since the epoch. Also like a native Date, methods like getDate
and getHours
are dependant upon the client computer‘s timezone.
However, you can remove this reliance on the client computer‘s timezone and make a UTC date, a date without a timezone. A date in UTC-mode will have all of its "get" methods identical to its "getUTC" methods and won‘t experience any daylight-savings time.
A true
argument can be appended to any of the constructors to make an XDate in UTC-mode:
d=newXDate(true);// the current date, in UTC-moded.toString();// "Mon, 24 Oct 2011 08:42:08 GMT"d=newXDate(2012,5,8,true);// values will be interpreted as UTCd.toString();// "Fri, 08 Jun 2012 00:00:00 GMT"d=newXDate(‘2012-06-08‘,true);// ambiguous timezone, so will be parsed as UTCd.toString();// "Fri, 08 Jun 2012 00:00:00 GMT"
Here are methods that relate to UTC-mode:
- .getUTCMode()
- Returns
true
if the date is in UTC-mode andfalse
otherwise - .setUTCMode(utcMode, doCoercion)
utcMode
must be eithertrue
orfalse
. If the optionaldoCoercion
parameters is set totrue
, the underlying millisecond time of the date will be coerced in such a way that methods likegetDate
andgetHours
will have the same values before and after the conversion.- .getTimezoneOffset()
- Returns the number of minutes from UTC, just like the native Date‘s getTimezoneOffset. However, if the XDate is in UTC-mode,
0
will be returned.
Please note, these methods directly modify the object. Use clone if you need a copy.
Utilities
- .clone()
- returns a copy of the XDate
- .clearTime()
- sets the hours, minutes, seconds, and milliseconds to zero
- .valid()
- return
true
if the XDate is a valid date,false
otherwise - .toDate()
- Returns a conversion to a native Date
The following utilities are members of the XDate class and are not associated with a specific XDate instance:
- XDate.getDaysInMonth(year, month)
- Returns the number of days in the given month
- XDate.parse(dateString)
- Parses a date-string and returns milliseconds since the epoch. You‘ll probably want to use
new XDate(dateString)
instead. - XDate.now()
- Returns the current date, as milliseconds since the epoch. You‘ll probably want to use
new XDate()
instead. - XDate.today()
- Returns the current date with time cleared, as an XDate object
- XDate.UTC(year, month, date, hours, minutes, seconds, milliseconds)
- Returns a milliseconds time since the epoch for the given UTC date
Chaining
Many of XDate‘s methods return a reference to the same XDate object. This allows you to "chain" operations together and makes for more concise code:
d1=newXDate();d2=d1.clone().setUTCMode(true).setDate(1).addMonths(1).addYears(2);
Inconsistencies with Native Date
XDate attempts to be "backwards-compatible" with the native Date object. However, there are two small departures that were made:
If you‘ve never noticed, a native Date object returns it‘s millisecond value every time there is a "set" method. This is not very helpful. In the same situations, an XDate will return a reference to itself to allow for chaining. This is much more useful, but does not match the way the native Date works.
Also, when a native Date is concatenated with a string (with&n
[Javascript] 轻量级的JavaScript日期处理类库xDate使用指南