/** * @license * Copyright Google Inc. All Rights Reserved. * * Use of this source code is governed by an MIT-style license that can be * found in the LICENSE file at https://angular.io/license */ import {Inject, LOCALE_ID, Pipe, PipeTransform} from '@angular/core'; import {formatDate} from '../i18n/format_date'; import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; // clang-format off /** * @ngModule CommonModule * @description * * Uses the function {@link formatDate} to format a date according to locale rules. * * The following tabled describes the formatting options. * * | Field Type | Format | Description | Example Value | * |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------| * | Era | G, GG & GGG | Abbreviated | AD | * | | GGGG | Wide | Anno Domini | * | | GGGGG | Narrow | A | * | Year | y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 | * | | yy | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 | * | | yyy | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 | * | | yyyy | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 | * | Month | M | Numeric: 1 digit | 9, 12 | * | | MM | Numeric: 2 digits + zero padded | 09, 12 | * | | MMM | Abbreviated | Sep | * | | MMMM | Wide | September | * | | MMMMM | Narrow | S | * | Month standalone | L | Numeric: 1 digit | 9, 12 | * | | LL | Numeric: 2 digits + zero padded | 09, 12 | * | | LLL | Abbreviated | Sep | * | | LLLL | Wide | September | * | | LLLLL | Narrow | S | * | Week of year | w | Numeric: minimum digits | 1... 53 | * | | ww | Numeric: 2 digits + zero padded | 01... 53 | * | Week of month | W | Numeric: 1 digit | 1... 5 | * | Day of month | d | Numeric: minimum digits | 1 | * | | dd | Numeric: 2 digits + zero padded | 01 | * | Week day | E, EE & EEE | Abbreviated | Tue | * | | EEEE | Wide | Tuesday | * | | EEEEE | Narrow | T | * | | EEEEEE | Short | Tu | * | Period | a, aa & aaa | Abbreviated | am/pm or AM/PM | * | | aaaa | Wide (fallback to `a` when missing) | ante meridiem/post meridiem | * | | aaaaa | Narrow | a/p | * | Period* | B, BB & BBB | Abbreviated | mid. | * | | BBBB | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | * | | BBBBB | Narrow | md | * | Period standalone* | b, bb & bbb | Abbreviated | mid. | * | | bbbb | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | * | | bbbbb | Narrow | md | * | Hour 1-12 | h | Numeric: minimum digits | 1, 12 | * | | hh | Numeric: 2 digits + zero padded | 01, 12 | * | Hour 0-23 | H | Numeric: minimum digits | 0, 23 | * | | HH | Numeric: 2 digits + zero padded | 00, 23 | * | Minute | m | Numeric: minimum digits | 8, 59 | * | | mm | Numeric: 2 digits + zero padded | 08, 59 | * | Second | s | Numeric: minimum digits | 0... 59 | * | | ss | Numeric: 2 digits + zero padded | 00... 59 | * | Fractional seconds | S | Numeric: 1 digit | 0... 9 | * | | SS | Numeric: 2 digits + zero padded | 00... 99 | * | | SSS | Numeric: 3 digits + zero padded (= milliseconds) | 000... 999 | * | Zone | z, zz & zzz | Short specific non location format (fallback to O) | GMT-8 | * | | zzzz | Long specific non location format (fallback to OOOO) | GMT-08:00 | * | | Z, ZZ & ZZZ | ISO8601 basic format | -0800 | * | | ZZZZ | Long localized GMT format | GMT-8:00 | * | | ZZZZZ | ISO8601 extended format + Z indicator for offset 0 (= XXXXX) | -08:00 | * | | O, OO & OOO | Short localized GMT format | GMT-8 | * | | OOOO | Long localized GMT format | GMT-08:00 | * * * When the expression is a ISO string without time (e.g. 2016-09-19) the time zone offset is not * applied and the formatted text will have the same day, month and year of the expression. * * WARNINGS: * - this pipe has only access to en-US locale data by default. If you want to localize the dates * in another language, you will have to import data for other locales. * See the {@linkDocs guide/i18n#i18n-pipes "I18n guide"} to know how to import additional locale * data. * - Fields suffixed with * are only available in the extra dataset. * See the {@linkDocs guide/i18n#i18n-pipes "I18n guide"} to know how to import extra locale * data. * - this pipe is marked as pure hence it will not be re-evaluated when the input is mutated. * Instead users should treat the date as an immutable object and change the reference when the * pipe needs to re-run (this is to avoid reformatting the date on every change detection run * which would be an expensive operation). * * ### Examples * * Assuming `dateObj` is (year: 2015, month: 6, day: 15, hour: 21, minute: 43, second: 11) * in the _local_ time and locale is 'en-US': * * {@example common/pipes/ts/date_pipe.ts region='DatePipe'} * * @stable */ // clang-format on @Pipe({name: 'date', pure: true}) export class DatePipe implements PipeTransform { constructor(@Inject(LOCALE_ID) private locale: string) {} /** * @param value a date object or a number (milliseconds since UTC epoch) or an ISO string * (https://www.w3.org/TR/NOTE-datetime). * @param format indicates which date/time components to include. The format can be predefined as * shown below (all examples are given for `en-US`) or custom as shown in the table. * - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`). * - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`). * - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM * GMT+1`). * - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at * 9:03:01 AM GMT+01:00`). * - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`). * - `'mediumDate'`: equivalent to `'MMM d, y'` (e.g. `Jun 15, 2015`). * - `'longDate'`: equivalent to `'MMMM d, y'` (e.g. `June 15, 2015`). * - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (e.g. `Monday, June 15, 2015`). * - `'shortTime'`: equivalent to `'h:mm a'` (e.g. `9:03 AM`). * - `'mediumTime'`: equivalent to `'h:mm:ss a'` (e.g. `9:03:01 AM`). * - `'longTime'`: equivalent to `'h:mm:ss a z'` (e.g. `9:03:01 AM GMT+1`). * - `'fullTime'`: equivalent to `'h:mm:ss a zzzz'` (e.g. `9:03:01 AM GMT+01:00`). * @param timezone to be used for formatting the time. It understands UTC/GMT and the continental * US time zone * abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`). * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by * default). */ transform(value: any, format = 'mediumDate', timezone?: string, locale?: string): string|null { if (value == null || value === '' || value !== value) return null; try { return formatDate(value, format, locale || this.locale, timezone); } catch (error) { throw invalidPipeArgumentError(DatePipe, error.message); } } }