# @jotter/dateformat

> Lightweight and easy-to-use date/time formatting function that returns the formatted date/time based on the passed in placeholders.

Latest version **1.0.2** (published 2023-06-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install @jotter/dateformat
pnpm add @jotter/dateformat
yarn add @jotter/dateformat
bun add @jotter/dateformat
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2023-06-15 |
| First published | 2023-05-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 26.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | lmq |
| Maintainers | mengqing723 |
| Keywords | dateFormat, date formatting, date, time, datetime, formatting, from now, to now, time ago |

## Links

- npm: https://www.npmjs.com/package/@jotter/dateformat
- Repository: https://github.com/Meqn/jotter
- Homepage: https://github.com/Meqn/jotter/tree/main/libs/dateFormat
- Issues: https://github.com/Meqn/jotter/issues
- npm.io page: https://npm.io/package/@jotter/dateformat

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 1.0.2 (latest) — 2023-06-15
- 1.0.1 — 2023-06-05
- 1.0.0 — 2023-05-25

## README

# dateFormat

轻巧易用的日期/时间格式化函数。根据传入的占位符返回格式化后的日期/时间。

Lightweight and easy date/time formatting function that returns the formatted date/time based on the passed in placeholders.

## Install

**npm**

```
npm install @jotter/dateformat
```
**browser**

```
https://cdn.jsdelivr.net/npm/@jotter/dateformat/dist/index.global.js
```


## Usage

```js
import dateFormat from '@jotter/dateformat'

dateFormat(new Date(), 'ddd YYYY/MM/DD HH:mm:ss SSS ZZ')
// Thu 2023/05/25 14:04:25 405 +0800

dateFormat(new Date())
// 2023-05-25 14:05:46

dateFormat(new Date(), 'date')
// '2023-05-25'

dateFormat(new Date(), 'time')
// '13:58:30'

dateFormat('2023/05/25 14:04:25', 'dddd YYYY/MM/DD hh:mm a')
// Thursday 2023/05/25 02:04 pm

dateFormat('2023/05/25 14:04:25', 'YYYY/MM/DD AAh:mm dddd', 'zh')
// 2023/05/25 下午2:04 星期四

dateFormat('2023-5-21', '[Today is] dddd', 'en')
// Today is Sunday

dateFormat('2023-5-25', (date) => {
  return `今天是${date.M}月${date.D}日 星期${date.dd}`
}, 'zh')
// 今天是5月25日 星期四
```

## API
```js
dateFormat(date, formatter, locale)
```

### date
需要格式化的日期/时间。
- `type` : `Date | string | number`
### formatter
格式化方式。
- `type` : `string | Function | 'datetime' | 'date' | 'time'`
- `default`: `datetime`

### locale
格式化的语言环境，默认为英文。
- `type` : `'zh' | 'en'`
- `default`: `en`



## 对照表
1. 对照表与 `moment.js` 一致
2. 将字符放在方括号中，即可原样返回而不被格式化替换 (例如， `[MM]`)

| 占位符 | 输出                      | 详情                    |
| ------ | ------------------------- | ----------------------- |
| `YY`   | 23                        | 两位数的年份            |
| `YYYY` | 2023                      | 四位数的年份            |
| `M`    | 1-12                      | 月份，从 1 开始         |
| `MM`   | 01-12                     | 月份，两位数            |
| `MMM`  | Jan-Dec 或 [一, 十二]      | 简写月份                |
| `MMMM` | October 或 十月           | 完整月份                |
| `D`    | 1-31                      | 月份里的一天            |
| `DD`   | 01-31                     | 月份里的一天，两位数    |
| `Q`    | 1-4                       | 季度（数字）            |
| `QQ`   | [一, 四]                  | 季度 (中文)             |
| `d`    | 0-6                       | 周, 星期天是0 (数字)    |
| `dd`   | Su-Sa 或 [日, 六]         | 最简写的星期几          |
| `ddd`  | Sun-Sat 或 [周日, 周六]   | 简写的星期几            |
| `dddd` | Sunday-Saturday 或 星期几 | 完整的星期几                  |
| `H`    | 0-23                      | 小时                    |
| `HH`   | 00-23                     | 小时，两位数            |
| `h`    | 1-12                      | 小时, 12 小时制         |
| `hh`   | 01-12                     | 小时, 12 小时制, 两位数 |
| `m`    | 0-59                      | 分钟                    |
| `mm`   | 00-59                     | 分钟，两位数            |
| `s`    | 0-59                      | 秒                      |
| `ss`   | 00-59                     | 秒, 两位数              |
| `S`    | 0-9                       | 毫秒 (后1位)            |
| `SS`   | 00-99                     | 毫秒 (后2位)            |
| `SSS`  | 000-999                   | 毫秒 (3位)              |
| `Z`    | +05:00                    | UTC 的偏移量，±HH:mm    |
| `ZZ`   | +0500                     | UTC 的偏移量，±HHmm     |
| `a`    | am/pm                     |                         |
| `A`    | AM/PM                     |                         |
| `AA`   | 上午/下午                 |                         |

---
_Source: https://npm.io/package/@jotter/dateformat · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._