XDate是一个请谅解的JavaScript的原生Date对象的封装库,提供增强的功能解析,格式化和日期处理。使用起来就和JavaScript自己的对象和方法一样,非常简单。
XDate是一个请谅解的JavaScript的原生Date对象的封装库,提供增强的功能解析,格式化和日期处理。使用起来就和JavaScript自己的对象和方法一样,非常简单。
使用说明:
<script src="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:
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