@acpaas-ui/js-date-utils 中文文档教程

Question

ACPaaS UI JS Date Utils

@acpaas-ui/js-date-utils 包提供一些基本支持用于处理 JS Date 对象。 除了 DateHelper 类之外，还包含一个 DateGenerator 类，用于从日期对象生成周、月和日期范围。

## Installation

NPM

npm install @acpaas-ui/js-date-utils --save

Yarn

yarn add @acpaas-ui/js-date-utils

## Import

// CommonJS
const DateHelper = require('@acpaas-ui/js-date-utils').DateHelper;
const DateGenerator = require('@acpaas-ui/js-date-utils').DateGenerator;

// ES2015
import { DateHelper, DateGenerator } from '@acpaas-ui/js-date-utils';

Datehelper 和 DateGenerator 中包含的所有方法也可以单独导入：

import { parseDate } from '@acpaas-ui/js-date-utils';

A note about JS and dates

JavaScript Date 对象可以变得非常笨重和令人困惑，尤其是跨时区。 为了保持这个包精简和快速，不依赖于像 moment.js 这样的帮助库，并且包含的​​功能仅限于支持生成器所必需的功能。

为确保遵守日期格式，建议以 YYYY-MM-DD 格式创建和使用日期：

const today = new Date('2017-10-03'); // this will always be the 3th October, 2017

DateHelper

Available methods and properties

• parseDate(...args, format?): parse the input to a date object, returns null for an invalid date. Format is an optional strict formatting parameter, using momentjs formats.
• getWeekday(date, startOfWeek): return the weekday for the provided date, offset by the (optionally) provided startOfWeek param, returns -1 for an invalid date
• getMonthLength(date): return the length of the month for the provided date, returns -1 for an invalid date
• getFirstWeekdayOfMonth(date, startOfWeek): return the weekday for the first day of the month for the provided date, offset by the (optionally) provided startOfWeek param, returns -1 for invalid dates
• getLastWeekdayOfMonth(date, startOfWeek): return the weekday for the last day of the month for the provided date, offset by the (optionally) provided startOfWeek param, returns -1 for invalid dates
• datesAreEqual(dates, specifier): compare the provided dates array with an optional specifier
  • dates (Date[]): an array of dates to compare
  • specifier (string | string[]): a specifier to compare against, can be one or a multitude of:
    • Y: year
    • M: month
    • D: date
    • h: hours
    • m: minutes
    • s: seconds
    • ms: milliseconds
    • value: integer value (valueOf)
• dateValuesAreEqual(dates, comparator): helper method for the datesAreEqual method, compares date values by the selected comparator
  • dates (Date[]): an array of dates to compare
  • comparator (string): a date getter method to determine the value to compare (e.g.: getMonths)
• updateDate(date, day): update the date value of a date, within the limits of the month (negative values will result in 1, values exceeding the month length will result in the month length), returns the provided value for an invalid date
• updateMonth(date, month): update the month value of a date, adjusting the year value if necessary, returns the provided value for an invalid date
• formatDate(date, format, options): format a date to a (limited set of) date format(s), returns null for an invalid date
  • date (Date): the date to format
  • format (string): the target format, can consist of:
    • YY: shorthand year notation, e.g.: 89 for 2017
    • YYYY: the full year notation, e.g.: 2017
    • MM: the numerical month notation, e.g.: 05 for may
    • MMMM: the written month notation, e.g.: may
    • DD: the numerical month notation, e.g.: 01
    • DDDD: the written day notation, e.g.: monday
    • hh: the hours notation, e.g.: 03
    • mm: the minutes notation, e.g.: 39
    • ss: the seconds notation, e.g.: 44
    • ms: the milliseconds notation, e.g.: 393
  • options ({}): the formatting options
    • leadingZero (Boolean): add leading zeros
    • startOfWeek (number): the first day of the week
    • weekdayLabels (string[]): a custom set of weekday labels
    • monthLabels (string[]): a custom set of month labels
• addLeadingZero(value, addLeadingZero) return the stringvalue of the provided value with a leading zero if addLeadingZero is true, returns the original string value if it is longer than 2
• dateOutOfRange(date, range): verify wether the provided date is outside of the provided range (an array of integers representing days in a month)
• closestDateForRange(date, range): return the closest date before or after the provided date that is not in the provided range (an array of integers representing days in a month)

Usage

Formatting examples

const date = new Date('2017-05-01 03:39:44.393');

DateHelper.format(date, 'hh:mm:ss (ms), DDDD DD MMMM YYYY', {
    addLeadingZero: true,
    startOfWeek: 1,
    weekdayLabels: [
        'Maandag',
        'Dinsdag',
        'Woensdag',
        'Donderdag',
        'Vrijdag',
        'Zaterdag',
        'Zondag'
    ],
    monthLabels: [
        'Januari',
        'Februari',
        'Maart',
        'April',
        'Mei',
        'Juni',
        'Juli',
        'Augustus',
        'September',
        'Oktober',
        'November',
        'December'
    ]
});

将导致

03:39:44 (393), Maandag 01 Mei 2017

Ranges

日期范围由日期或工作日数组组成：

const dateRange = [
    new Date('2017-05-03'),
    new Date('2017-05-20'),
    5, 6
];

转换为所有第 5 个和第 6 个工作日（默认为周五和周六）以及 5 月 3 日和 20 日。 dateOutOfRange 和 closestDateForRange 方法需要一个解析的日期范围，一个整数值数组，表示构成该范围的月份中的几天。 对于 5 月份的上述范围，这将是：

[ 3, 5, 6, 12, 13, 19, 20, 26, 27 ]

dateOutOfRange 方法将对以下日期返回 true：

[
    new Date('2017-05-02'), // a tuesday
    new Date('2017-18-03'), // a thursday
    new Date('2017-31-03'), // a wednesday
]

对这些日期返回 false ：

[
    new Date('2017-05-03'), // specific date in the range
    new Date('2017-05-05'), // a friday
    new Date('2017-05-27') // a saturday
]

closestDateForRange 方法将返回提供范围之外的最近日期，无论它是在提供日期之前还是之后：

const range = [ 3, 5, 6, 12, 13, 19, 20, 26, 27 ];

closestDateForRange(new Date('2017-05-13'), range);
=> 2017-05-14

closestDateForRange(new Date('2017-05-12'), range);
=> 2017-05-11

DateGenerator

Available methods

• generateMonth(date, options): generate an array of day values representing the month for the provided date, returns [] for an invalid date
  • date (Date): the target date
  • options (Object): the generator options
    • startOfWeek (number): the first day of the week
    • padding (boolean): add padding for the first & last week (empty values)
    • generatePadding (boolean): use actual day values for the padding
• generateWeek(start, options, padding): generate a week of day values
  • start (number): the day to start from
  • options (Object): the generator options
    • offset (number): offset the start
    • dayOffset (number): offset the day values
    • padding (boolean): add padding at the start/end
    • fromStart (boolean): add padding at the start
  • padding number[]: values to be used for padding
• generatePadding(date, count, fromStart): generate a value of integer values to be used as padding, returns [] for an invalid date
  • date (Date): the target date
  • count (number): the amount of padding to generate
  • fromStart (boolean): generate padding from the start of the month
• generateRange(date, ranges, options): parse a DateRange to a flat array of integers representing the day values, returns [] for an invalid date
  • date (Date): the target date
  • range (Array<number|Date>): a range of dates to parse, can be either a Date object or a number representing a weekday
  • options (Object): the range options
    • startOfWeek (number): the first day of the week