On this page
@std/datetime
Unstable
This @std package is experimental and its API may change without a major version bump.
Overview Jump to heading
Utilities for dealing with Date objects.
import { dayOfYear, isLeap, difference, HOUR, MINUTE, SECOND } from "@std/datetime";
import { assertEquals } from "@std/assert";
assertEquals(dayOfYear(new Date("2019-03-11T03:24:00")), 70);
assertEquals(isLeap(1970), false);
const date0 = new Date("2018-05-14");
const date1 = new Date("2020-05-13");
assertEquals(difference(date0, date1).years, 1);
assertEquals(HOUR / MINUTE, 60);
assertEquals(MINUTE / SECOND, 60);
Add to your project Jump to heading
deno add jsr:@std/datetime
See all symbols in @std/datetime on
什么是 datetime？ Jump to heading
在 JavaScript 中，日期和时间围绕内置的 Date 对象：
Date存储自 Unix 纪元时间点（1970‑01‑01T00:00:00Z）起的毫秒数。其内部值始终为 UTC。- 渲染和许多 getter 方法可采用本地时间（例如
getHours）或 UTC 时间（例如getUTCHours）。请明确指定所需的时间类型。 - 对非 ISO 字符串使用
Date构造函数进行解析时，结果依赖于本地环境和实现细节，建议使用 ISO-8601 格式（YYYY‑MM‑DDTHH:mm:ssZ）或其他库/解析器。
@std/datetime 包基于此提供简单的解析、格式化和日期运算，并支持显式的模式和选项。
它旨在涵盖常见需求，无需引入大型依赖，并兼容 Deno、Node.js、Bun、浏览器和 Workers。
何时使用 @std/datetime Jump to heading
如果你需要格式化和解析日期/时间，以及进行小规模计算，同时不想引入大型库，典型用例包括：
- 为日志、文件名或界面显示生成可读的时间戳。
- 使用显式格式安全地解析用户输入，替代 Date 的猜测式解析。
- 显示相对持续时间（例如“剩余 X 天”）。
- 获取日历字段，比如年中的周数或天数。
- 生成符合标准的字符串（例如 ISO-8601）以供接口使用。
示例 Jump to heading
import {
dayOfYear,
dayOfYearUtc,
difference,
format,
isLeap,
isUtcLeap,
parse,
weekOfYear,
} from "@std/datetime";
// 带时区的格式化
const nowTokyo = format(
new Date("2025-01-02T12:34:56Z"),
"yyyy-MM-dd HH:mm XXX",
{ timeZone: "Asia/Tokyo" },
);
// 按明确模式解析（本地时间，除非模式或偏移另有指定）
const parsed = parse("2025-01-02 09:30", "yyyy-MM-dd HH:mm");
parsed instanceof Date; // true
// 在特定单位上的差异
const a = new Date("2024-01-01T00:00:00Z");
const b = new Date("2025-06-01T00:00:00Z");
difference(a, b, { units: ["years", "months", "days"] });
// -> { years: 1, months: 5, days: 0 }
// 年周和年内天数
weekOfYear(new Date("2025-01-05")); // ISO 年周号 (1-53)
dayOfYear(new Date("2025-03-01")); // 本地时区
dayOfYearUtc(new Date(Date.UTC(2025, 2, 1))); // UTC
// 闰年检查
isLeap(2024); // 根据本地规则为 true
isUtcLeap(2024); // 时区无关，为 true
// UTC vs 指定时区格式化
import { format } from "@std/datetime";
const d = new Date("2025-01-02T00:00:00Z");
format(d, "yyyy-MM-dd HH:mm XXX", { timeZone: "UTC" }); // 2025-01-02 00:00 +00:00
format(d, "yyyy-MM-dd HH:mm XXX", { timeZone: "Asia/Tokyo" }); // 2025-01-02 09:00 +09:00
// 解析带数字偏移的 ISO 字符串
import { parse } from "@std/datetime";
const withOffset = parse(
"2025-01-02T09:30:00+09:00",
"yyyy-MM-dd'T'HH:mm:ssXXX",
);
withOffset.toISOString(); // 2025-01-02T00:30:00.000Z
// 使用提供的常量添加时间长度
import { HOUR, MINUTE, SECOND } from "@std/datetime";
const start = new Date("2025-01-01T00:00:00Z");
const plus90m = new Date(start.getTime() + 90 * MINUTE);
const plus1h5s = new Date(start.getTime() + HOUR + 5 * SECOND);
// 到期限的剩余天数（倒计时）
import { difference } from "@std/datetime";
const now = new Date("2025-01-01T00:00:00Z");
const launch = new Date("2025-02-15T00:00:00Z");
difference(now, launch, { units: ["days"] }); // { days: 45 }
// 年界限附近的 ISO 年周
import { weekOfYear } from "@std/datetime";
weekOfYear(new Date("2020-12-31")); // 53
weekOfYear(new Date("2021-01-01")); // 53 （仍是 2020 年最后一周）
weekOfYear(new Date("2021-01-04")); // 1
// 使用 Date 输入的闰年检测
import { isLeap } from "@std/datetime";
isLeap(new Date("2000-01-01")); // true（能被400整除）
isLeap(new Date("1900-01-01")); // false（世纪年不能被400整除）
提示 Jump to heading
- 在格式化时明确时区（例如包含
XXX偏移符号）。 - 交换和存储时优先使用 ISO 8601 格式。