dateUtils

getTimeFormatToZone

获取特定地区的时间（系统里默认用America/Los_Angeles：UTC-7时区）

timeStamp 时间戳
zoneAlias 时区别名：见下方时区映射表
format 格式，默认 'YYYY-MM-DD HH:mm:ss'
returns 格式化后的时区时间

使用

tsx

import { getTimeFormatToZone } from '@aplus-frontend/utils';

// getTimeFormatToZone(时间戳,时区别名,格式化)
getTimeFormatToZone(1718502724000,"LA","YYYY-MM-DD") => "2024-06-16"

getUTCTimeFormatWithZone

带UTC偏移量后缀的时区时间（系统里默认用UTC-7时区）

timeStamp 时间戳
utc UTC偏移量，默认 -7
format 格式，默认 'YYYY-MM-DD HH:mm:ss'
returns 格式化后的时区时间

使用

tsx

import { getUTCTimeFormatWithZone } from '@aplus-frontend/utils';

// getUTCTimeFormatWithZone(时间戳,UTC偏移量,格式化)
getUTCTimeFormatWithZone(1718502724000,-7,"YYYY-MM-DD") => "2024-06-16 (UTC-7)"

getUtcTimestamp 🔥

根据指定时区的时间拿到目标时区的时间戳或dayjs对象

日期时间模式就是日期时间转时间戳，即根据指定的绝对日期时间，获取不同地区的时间戳（日期时间是固定的）
时间戳模式就是时间戳转日期时间，即根据一个固定的时间戳，获取不同地区的日期时间（时间戳是固定的）
time {string | Date | number} 时间
targetZoneAlias 目标时区，默认'LA', 别名枚举值：LA = 'America/Los_Angeles' | NY ='America/New_York' | SH = 'Asia/Shanghai'...
currentZoneAlias 当前时区，默认本地时区, 别名枚举值：LA = 'America/Los_Angeles' | NY ='America/New_York' | SH = 'Asia/Shanghai'...
returnDayjs 是否返回dayjs对象，默认为false
mode 模式，默认'timeString'，可选'timeString（日期时间模式）' | 'timeStamp（时间戳模式）'
返回值 {number | Dayjs | null} 目标时区时间戳 | 目标时区dayjs对象

使用

tsx

import { getUtcTimestamp } from '@aplus-frontend/utils';
 getUtcTimestamp({
    time: dayjs(1726685784000),
    currentZoneAlias: 'LA',
    returnDayjs: true
})

getDateIntervalUnit

获取历史到现在或现在到未来的某天的开始和结束时间戳(以天为单位,时区为相对转换)

timezone 转换的时区，默认LA
step 时间间隔，默认-3
unit 时间间隔单位,仅支持'day' | 'week' | 'month' | 'year'，默认month（月）
returns 开始和结束时间戳

使用

tsx

import { getDateIntervalUnit } from '@aplus-frontend/utils';

// getDateIntervalUnit(时间,UTC偏移量,格式化)
getDateIntervalUnit() => [1729407600000, 1737446399999]

API

参数	说明	类型	默认值
timeStamp	时间戳	`Number`	无
utc	UTC偏移量	`Number`	-7
format	设置日期格式	`String`	YYYY-MM-DD HH:mm:ss
time	时间	`String`/`Number`/`Date`	无
targetZoneAlias	时区别名	`ZoneAlias`	LA

ZoneMap

/**
 * @description: 时区映射表
 * @example: ZoneMap.LA = 'America/Los_Angeles'
 * @example: ZoneMap.SH = 'Asia/Shanghai'
 */
export enum ZoneMap {
  /**
   * 冰岛 UTC+0 （不存在夏令时）
   */
  RJ = 'Atlantic/Reykjavik',
  /**
   * 伦敦 UTC+0 （存在夏令时：UTC+0 | UTC+1）
   */
  LD = 'Europe/London',
  /**
   * 巴黎 UTC+1
   */
  PR = 'Europe/Paris',
  /**
   * 佛得角 UTC-1
   */
  VD = 'Atlantic/Cape_Verde',
  /**
   * 哥本哈根 UTC+2
   */
  CP = 'Europe/Copenhagen',
  /**
   * 巴西 UTC-2
   */
  BS = 'America/Sao_Paulo',
  /**
   * 莫斯科 UTC+3
   */
  MS = 'Europe/Moscow',
  /**
   * 圣保罗 UTC-3
   */
  // eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
  SP = 'America/Sao_Paulo',
  /**
   * 迪拜 UTC+4
   */
  DB = 'Asia/Dubai',
  /**
   * 纽约 UTC-4
   */
  NY = 'America/New_York',
  /**
   * 卡拉奇 UTC+5
   */
  KR = 'Asia/Karachi',
  /**
   * 芝加哥 UTC-5
   */
  CG = 'America/Chicago',
  /**
   * 不丹 UTC+6
   */
  TM = 'Asia/Thimphu',
  /**
   * 丹佛 UTC-6
   */
  DV = 'America/Denver',
  /**
   * 首尔 UTC+7
   */
  SU = 'Asia/Seoul',
  /**
  /**
   * 洛杉矶 UTC-7
   */
  LA = 'America/Los_Angeles',
  /**
   * 上海 UTC+8
   */
  SH = 'Asia/Shanghai',
  /**
   * 阿拉斯加 UTC-8
   */
  ALS = 'America/Juneau'
  // 根据需要添加更多...
}

ZoneAlias

/**
 * params 时区别名
 */
export type ZoneAlias = keyof typeof ZoneMap;

时区映射表(详见上方ZoneMap)

时区别名	IANA时区	时区名
LA	America/Los_Angeles	洛杉矶
NY	America/New_York	纽约
SH	Asia/Shanghai	上海
后续可根据业务需要添加...

概念补充

前置说明

日期时间格式 2025-05-20 01:02:03
时间戳格式 1716153723000
固定日期时间下，不同时区的时间戳是不同的
固定时间戳下，不同时区的日期时间是不同的
日期时间模式就是日期时间转时间戳，即根据指定的绝对日期时间，获取不同地区的时间戳（日期时间是固定的）
时间戳模式就是时间戳转日期时间，即根据一个固定的时间戳，获取不同地区的日期时间（时间戳是固定的）

误区

`dayjs.tz(time,zone)` 等价于 `dayjs(time).tz(zone)` `❌`

dayjs.tz(time,zone) 👉🏻 直接将 time 视作属于指定时区 zone 的时间来解析
dayjs(time).tz(zone) 👉🏻 先根据当前环境（浏览器或服务器）所在的本地时区解析这个时间，得到一个具体的时刻，再把这个时刻“重新定位”到目标时区 zone，也就是改变展示的时区，但不改变它对应的时刻
直接获取洛杉矶2024-09-19 00:00:00的时间戳 👇🏻
dayjs.tz('2024-09-19 00:00:00', 'America/Los_Angeles').valueOf()
获取本地2024-09-19 00:00:00这一时刻在洛杉矶时区的日期时间展示 👇🏻
dayjs('2024-09-19 00:00:00').tz('America/Los_Angeles').format('YYYY-MM-DD HH:mm:ss')

时刻与时间

“时刻”指的是物理世界中的某一个时间点，而“时间”则是我们平常说的“几点几分”。“时刻”是一个绝对的时间点，而“时间”是时钟上显示的值，是相对的，不同地区会有时差。
例如 A 在美国，C 在中国，假如他们时差 12 小时，则某一刻如果 A 时间是 8 am，则 C 时间是 8 pm。
实际项目中，时间戳（一串数字）是一个时刻，而我们呈现给用户的（YYYY年MM月DD日 HH时mm分ss秒）则是一个时间。这里一定要明确，不能搞混淆了。
“时刻”和“时间”要互相转换的话，还需要知道——“时区”

什么是时区？

大家都知道北京是东八区，可以记作 UTC+8；而美国阿拉斯加是西九区，记作 UTC-9。
UTC 是指“协调世界时”，是一个基准时间。后面跟着的“+n”可以理解为“快了 n 个小时“。“-n”同理。所以北京时间比阿拉斯加快了 17 个小时。
一天有 24 小时，所以分为 24 个时区，东区是加相应的时区差，西区是减时区差，所以时区范围就是UTC-11 到 UTC+12。

时区是如何定义的？

从格林威治本初子午线起，经度每向东或者向西间隔 15°，就划分一个时区，在这个区域内，大家使用同样的标准时间。
但实际上，为了照顾到行政上的方便，常将 1 个国家或 1 个省份划在一起。所以时区并不严格按南北直线来划分，而是按自然条件来划分。另外：由于目前，国际上并没有一个批准各国更改时区的机构。一些国家会由于特定原因改变自己的时区。
全球共分为 24 个标准时区，相邻时区的时间相差一个小时。

GMT-格林尼治标准时间

GMT 的全名是格林威治标准时间或格林威治平时（Greenwich Mean Time），这个时间系统的概念在 1884 年确立，由英国伦敦的格林威治皇家天文台计算并维护，并在往后的几十年往欧陆其他国家扩散。在 1924 年开始，格林威治天文台每小时就会向全世界播报时间。
在刚开始的几十年，GMT 的测量方法非常简单：观测者随时监控太阳在天空的位置，并且把每天太阳爬升到仰角最高的时候记录下来，这个时间点称呼为“过中天”。一般人对于一天 24 小时的理解，大致上就相等于两次太阳过中天的时间间隔。不过由于地球是以椭圆轨道绕着太阳，在轨道上的行进速率不一，导致一年之中会有“比较长的一天”与“比较短的一天”，所以格林威治的观测者必须要至少连续观测一年，然后求取 365 个长度不一的“天”，再把他们全部平均后，得到固定的一天长度，之后再细分成时、分、秒等单位。这个就是 GMT。
GMT 12:00 就是指的是英国伦敦郊区的皇家格林尼治天文台当地的中午 12:00，而 GMT+8 12:00，则是指的东八区的北京当地时间的 12:00。

UTC-世界标准时间(协调世界时)

自从 1967 年国际度量衡大会把秒的定义改成铯原子进行固定震荡次数的时间后，时间的测量就可以与星球的自转脱节了。只利用原子钟计算时间与日期的系统，称作国际原子时（International Atomic Time），这是一种只有“天”的系统，时分秒都以“天”的小数点零头来表示。以国际原子时为计算基准，把时间格式与 UT1 对齐，让一般人都方便使用的时间系统，就叫做协调世界时（Universal Time Coordinated），也就是 UTC。这也就是 UTC 为什么与 GMT 几乎一样的关係。由于 UTC 直接与国际度量衡标准相联繫，所以目前所有的国际通讯系统，像是卫星、航空、GPS 等等，全部都协议採用 UTC 时间。
协调世界时，又称世界统一时间、世界标准时间、国际协调时间。协调世界时，即以我为基准，向我看齐的意思。（英语：Coordinated Universal Time，法语：Temps Universel Coordonné，简称 UTC）是最主要的世界时间标准，由于英文（CUT）和法文（TUC）的缩写不同，作为妥协，简称 UTC。

我们一般认为 GMT 与 UTC 是一样的，都与英国伦敦的本地时间相同。

本地时间（Local Time）

所在时区的时间。UTC 或 GMT 与 LT 如下的换算关系：LT=UTC+时区差；东区是加相应的时区差，西区是减时区差。如北京是东八区，则北京时间=UTC+8。

什么是时间戳？

时间戳是指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒（北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒）起至现在的总秒数。

什么是夏令时，冬令时？

夏令时（Daylight Saving Time：DST），又称“夏时制”或“夏令时间”，是一种为节约能源而人为规定地方时间的制度，在这一制度实行期间所采用的统一时间称为“夏令时间”。一般在天亮早的夏季人为将时间提前一小时，可以使人早起早睡，减少照明量，以充分利用光照资源，从而节约照明用电。
冬令时的实行则相对有限，主要在加拿大、欧洲北部以及一些靠近北极的国家，如挪威。这些国家通常在秋季的 10 月和 11 月实行冬令时，以应对冬季白天短暂、夜晚漫长的情况。

dateUtils ​

getTimeFormatToZone ​

getUTCTimeFormatWithZone ​

getUtcTimestamp 🔥 ​

根据指定时区的时间拿到目标时区的时间戳或dayjs对象 ​

getDateIntervalUnit ​

API ​

ZoneMap ​

ZoneAlias ​

时区映射表(详见上方ZoneMap) ​

概念补充 ​

前置说明 ​

误区 ​

dayjs.tz(time,zone) 等价于 dayjs(time).tz(zone) ❌ ​

时刻与时间 ​

什么是时区？ ​

时区是如何定义的？ ​

GMT-格林尼治标准时间 ​

UTC-世界标准时间(协调世界时) ​

本地时间（Local Time） ​

什么是时间戳？ ​

什么是夏令时，冬令时？ ​

dateUtils

getTimeFormatToZone

getUTCTimeFormatWithZone

getUtcTimestamp 🔥

根据指定时区的时间拿到目标时区的时间戳或dayjs对象

getDateIntervalUnit

API

ZoneMap

ZoneAlias

时区映射表(详见上方ZoneMap)

概念补充

前置说明

误区

`dayjs.tz(time,zone)` 等价于 `dayjs(time).tz(zone)` `❌`

时刻与时间

什么是时区？

时区是如何定义的？

GMT-格林尼治标准时间

UTC-世界标准时间(协调世界时)

本地时间（Local Time）

什么是时间戳？

什么是夏令时，冬令时？