# @gravity-ui/date-utils 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/date-utils/

版本：2\.7\.3
npm 元数据更新时间：2026-11-02T08:43:13.762Z
中文译文更新时间：2026-11-16T23:41:49.283Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/date-utils
原文对照：https://npmcn.com/package/%40gravity-ui/date-utils/?lang=original
项目主页：https://github.com/gravity-ui/date-utils#readme
源码仓库：https://github.com/gravity-ui/date-utils

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：173 kB，78 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2023-01-18T08:26:21.796Z
- 最新版本发布：2026-11-02T08:43:13.501Z
- 近 30 天下载量：78963（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 5 个）

## 中文简介

重力 UI 约会助手

## 安装

```sh
npm install @gravity-ui/date-utils
```

也可以使用：`pnpm add @gravity-ui/date-utils`、`yarn add @gravity-ui/date-utils`、`bun add @gravity-ui/date-utils`

## README

# @ gravity-ui/ date- utils (简体中文)

管理日期和时间的助手.

## 安装

```shell
npm i @gravity-ui/date-utils
```

## 使用量

```typescript
import {dateTimeParse, dateTime} from '@gravity-ui/date-utils';

// Current date: 2021-08-07T12:10:00
// User's time zone: Europe/Istanbul

const FORMAT = 'YYYY-MM-DDTHH:mm:ssZ';

// parse absolute date
dateTimeParse({year: 2021, month: 7, day: 7})?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse([2021, 7, 7])?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse('2021-08-07')?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse(1621708204063)?.format(FORMAT); // "2021-05-22T21:30:04+03:00"
dateTimeParse('')?.format(FORMAT); // undefined
dateTimeParse('incorrect-date')?.format(FORMAT); // undefined

// parse relative date
dateTimeParse('now')?.format(FORMAT); // "2021-08-07T12:10:00+03:00"
dateTimeParse('now-1d')?.format(FORMAT); // "2021-08-06T12:10:00+03:00"
dateTimeParse('now-1d+1M')?.format(FORMAT); // "2021-09-06T12:10:00+03:00"
dateTimeParse('now/d')?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse('now+1d/d')?.format(FORMAT); // "2021-08-08T00:00:00+03:00"
dateTimeParse('now-1f')?.format(FORMAT); // undefined

// create dateTime
dateTime().format(FORMAT); // "2021-08-07T12:10:00+03:00"
dateTime({input: '2021-08-07'}).format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTime({input: '2021-08-07', format: 'YYYY-MM-DD'}).format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTime({timeZone: 'Asia/Tokyo'}).format(FORMAT); // "2021-08-07T18:10:00+09:00
dateTime({input: ''}).format(FORMAT); // "Invalid Date"
dateTime({input: '2021-08', format: 'YYYY-MM-DD'}).format(FORMAT); // "Invalid Date"
```

## 设置

```typescript
import {settings} from '@gravity-ui/date-utils';

// Locales management
settings.getLocale(); // default locale "en"
settings.loadLocale('de').then(() => {
  settings.setLocale('de');
  settings.getLocale(); // "de"
});

// Customization
settings.updateLocale({weekStart: 0}); // change first day of week
```

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/date-utils/LICENSE) 详细情况.

## 对于人工智能特工

时区认识日期/时间帮助者——解析(包括相对表达式如: `now-1d/d`),格式化,和地产管理——没有任何UI,当你需要计算和格式化的日期可靠地跨时区时,而不是拉入一个完整的UI日历时,就会到达.

### 何时使用

-   解析绝对或相对日期表达式( E)`'now-1d'`, (中文(简体) ), `'now/d'`)进入时区意识 `dateTime` 对象.
-   格式化在用户的时区中显示的日期, 并有 locale 支持 .
-   在服务器(节点)和客户端(反应)代码之间共享日期逻辑——该软件包没有反应依赖性.

### 不使用时

-   制作日历、取出日期或任何日期 **用户**,使用时 [`@gravity-ui/date-components`](https://gravity-ui.com/components/date-components) ——它在这个包上建起它的视觉.
-   对于轻量级不可变的日期数学和没有时区/相对表达需要, `date-fns` 或当地人 `Intl`编号 :`Date` API可能就够了.

### 常见陷阱

-   **通话 `dateTimeParse('')` 需要一个日期** ——返回 `undefined`,而不是一个 `dateTime`; 以可选的链条或无效检查来守护.
-   **忘记装入一个地方** —— 说 `settings.setLocale('de')` 仅格式化本地化名称(周日、月) `settings.loadLocale('de')` 已经解决了.
-   **迷幻函数 `formatDate` 编号 : `parseDate`** - 切入点是 `dateTimeParse` (页)和 `dateTime(...).format(...)` (格式).
-   **假设用户的时区自动应用** - 通过 `timeZone` 或使用系统时区.

## AI代理的文件

安装版本的可代理读取文档位于 `node_modules/@gravity-ui/date-utils/build/docs/INDEX.md`。 。 。 .

## 常见问题

### @gravity-ui/date-utils 是什么？

重力 UI 约会助手

### 如何安装 @gravity-ui/date-utils？

在项目目录运行 npm install @gravity-ui/date-utils，或使用 pnpm add / yarn add / bun add。

### @gravity-ui/date-utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gravity-ui/date-utils 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gravity-ui/date-utils 可以商用吗？

@gravity-ui/date-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ui/date-utils 的下载量有多少？

根据 npm 官方下载统计，@gravity-ui/date-utils 在 2026/10/17 – 2026/11/15 这 30 天内被下载 78,963 次，日均约 2,632 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gravity-ui/date-utils 还在维护吗？

最新版本 2\.7\.3 发布于 2026/11/02（14 天前）；至今共发布 33 个版本，其中过去 12 个月发布了 5 个；首次发布于 2023/01/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

