Skip to content

Latest commit

 

History

History
520 lines (355 loc) · 10.6 KB

README.md

File metadata and controls

520 lines (355 loc) · 10.6 KB
Raw

English | 简体中文

Day.js

Fast 2kB alternative to Moment.js with the same modern API


Gzip Size NPM Version Build Status Codecov License

Day.js is a minimalist JavaScript library for modern browsers with a largely Moment.js-compatible API. If you use Moment.js, you already know how to use Day.js.

dayjs().startOf('month').add(1, 'day').set('year', 2018).format('YYYY-MM-DD HH:mm:ss');
  • 🕒 Familiar Moment.js API & patterns
  • 💪 Immutable
  • 🔥 Chainable
  • 📦 2kb mini library
  • 👫 All browsers supported

Installation

You have multiple ways of getting Day.js:

  • Via NPM:
npm install dayjs --save
var dayjs = require('dayjs');
dayjs().format();
  • Via CDN:
<!-- Latest compiled and minified JavaScript -->
<script src="https://unpkg.com/dayjs"></script>
<script>
  dayjs().format();
</script>
  • Via download and self-hosting:

Just download the latest version of Day.js at https://unpkg.com/dayjs/dist/

Getting Started

Instead of modifying the native Date.prototype, Day.js creates a wrapper for the Date object, called Dayjs object. Dayjs object is immutable, that is to say, all API operation will return a new Dayjs object.

API

API will always return a new Dayjs object if not specified.

Parse

Simply call dayjs() with one of the supported input types.

Now

To get the current date and time, just call dayjs() with no parameters.

dayjs();

String

Creating from a string matches ISO 8601 format.

dayjs(String);
dayjs('1995-12-25');

Unix Timestamp (milliseconds)

Passing an integer value representing the number of milliseconds since the Unix Epoch (Jan 1 1970 12AM UTC).

dayjs(Number);
dayjs(1318781876406);

Date

Passing a pre-existing native Javascript Date object.

dayjs(Date);
dayjs(new Date(2018, 8, 18));

Clone

All Dayjs are immutable. If you want a copy of the object, just call .clone(). Calling dayjs() on a Dayjs object will also clone it.

dayjs(Dayjs);
dayjs().clone();

Validation

  • returns a Boolean

Check whether the Dayjs object considers the date invalid.

dayjs().isValid();

Get + Set

Get and set date.

Year

  • returns a Number

Get year.

dayjs().year();

Month

  • returns a Number

Get month.

dayjs().month();

Date of Month

  • returns a Number

Get day of the month.

dayjs().date();

Day of Week

  • returns a Number

Get day of the week.

dayjs().day();

Hour

  • returns a Number

Get hour.

dayjs().hour();

Minute

  • returns a Number

Get minute.

dayjs().minute();

Second

  • returns a Number

Get second.

dayjs().second();

Millisecond

  • returns a Number

Get millisecond.

dayjs().millisecond();

Set

Date setter. Units are case insensitive

dayjs().set((unit: String), (value: Int));
dayjs().set('month', 3); // April
dayjs().set('second', 30);

Manipulate

Once you have a Dayjs object, you may want to manipulate it in some way like this:

dayjs()
  .startOf('month')
  .add(1, 'day')
  .subtract(1, 'year');

Add

Returns a new Dayjs object by adding time.

dayjs().add((value: Number), (unit: String));
dayjs().add(7, 'day');

Subtract

Returns a new Dayjs object by subtracting time. exactly the same as dayjs#add.

dayjs().subtract((value: Number), (unit: String));
dayjs().subtract(7, 'year');

Start of Time

Returns a new Dayjs object by by setting it to the start of a unit of time.

dayjs().startOf((unit: String));
dayjs().startOf('year');

End of Time

Returns a new Dayjs object by by setting it to the end of a unit of time.

dayjs().endOf((unit: String));
dayjs().endOf('month');

Display

Once parsing and manipulation are done, you need some way to display the Dayjs object.

Format

  • returns a String

Takes a string of tokens and replaces them with their corresponding date values.

dayjs().format(String);
dayjs().format(); // "2014-09-08T08:02:17-05:00" (ISO 8601, no fractional seconds)
dayjs().format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // "{2014} 09-08T08:02:17-05:00Z"
  • To escape characters in string, wrap the characters in square brackets (e.g. [Z]).

List of all available formats:

Format Output Description
YY 18 Two-digit year
YYYY 2018 Four-digit year
M 1-12 The month, beginning at 1
MM 01-12 The month, 2-digits
MMM Jan-Dec The abbreviated month name
MMMM January-December The full month name
D 1-31 The day of the month
DD 01-31 The day of the month, 2-digits
d 0-6 The day of the week, with Sunday as 0
dddd Sunday-Saturday The name of the day of the week
H 0-23 The hour
HH 00-23 The hour, 2-digits
h 1-12 The hour, 12-hour clock
hh 01-12 The hour, 12-hour clock, 2-digits
m 0-59 The minute
mm 00-59 The minute, 2-digits
s 0-59 The second
ss 00-59 The second, 2-digits
SSS 000-999 The millisecond, 3-digits
Z +5:00 The offset from UTC
ZZ +0500 The offset from UTC, 2-digits
A AM PM
a am pm

Difference

  • returns a Number

Get the difference of two Dayjs objects in milliseconds or another unit.

dayjs().diff(Dayjs, unit);
dayjs().diff(dayjs(), 'years'); // 0

Unix Timestamp (milliseconds)

  • returns a Number

Outputs the number of milliseconds since the Unix Epoch

dayjs().valueOf();

Unix Timestamp (seconds)

  • returns a Number

Outputs a Unix timestamp (the number of seconds since the Unix Epoch).

dayjs().unix();

Days in Month

  • returns a Number

Get the number of days in the current month.

dayjs().daysInMonth();

As Javascript Date

  • returns a Javascript Date object

Get copy of the native Date object from Dayjs object.

dayjs().toDate();

As Array

  • returns an Array

Returns an array that mirrors the parameters from new Date().

dayjs().toArray(); //[2018, 8, 18, 00, 00, 00, 000];

As JSON

  • returns a JSON String

Serializing a Dayjs object to JSON, will return an ISO8601 string.

dayjs().toJSON(); //"2018-08-08T00:00:00.000Z"

As ISO 8601 String

  • returns a String

Formats a string to the ISO8601 standard.

dayjs().toISOString();

As Object

  • returns an Object

Returns an object with year, month ... millisecond.

dayjs().toObject(); // { years:2018, months:8, date:18, hours:0, minutes:0, seconds:0, milliseconds:0}

As String

  • returns a String
dayjs().toString();

Query

Is Before

  • returns a Boolean

Check if a Dayjs object is before another Dayjs object.

dayjs().isBefore(Dayjs);
dayjs().isBefore(dayjs()); // false

Is Same

  • returns a Boolean

Check if a Dayjs object is same as another Dayjs object.

dayjs().isSame(Dayjs);
dayjs().isSame(dayjs()); // true

Is After

  • returns a Boolean

Check if a Dayjs object is after another Dayjs object.

dayjs().isAfter(Dayjs);
dayjs().isAfter(dayjs()); // false

Is Leap Year

  • returns a Boolean

Check if a year is a leap year.

dayjs().isLeapYear();
dayjs('2000-01-01').isLeapYear(); // true

License

MIT