# @art-suite/art-core-ts-time 中文文档

规范地址：https://npmcn.com/package/%40art-suite/art-core-ts-time/

版本：0\.4\.1
npm 元数据更新时间：2026-06-19T10:23:30.138Z
中文译文更新时间：2026-11-06T20:39:54.717Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40art-suite/art-core-ts-time
原文对照：https://npmcn.com/package/%40art-suite/art-core-ts-time/?lang=original
项目主页：https://github.com/art-suite/art-suite-ts#readme
源码仓库：https://github.com/art-suite/art-suite-ts

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

- 包体积（解压后）：68.8 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-05-12T08:59:04.419Z
- 最新版本发布：2026-06-19T10:23:30.016Z
- 近 30 天下载量：3224（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 6 个）

## 中文简介

TypeScript 字符串工具库

## 安装

```sh
npm install @art-suite/art-core-ts-time
```

也可以使用：`pnpm add @art-suite/art-core-ts-time`、`yarn add @art-suite/art-core-ts-time`、`bun add @art-suite/art-core-ts-time`

## README

# @art-site/art-core-ts-time (英语)

在JavaScript和TypeScript中与日期,时间,和持续时间一起工作的无缝,简单公用设备.

## 为什么是这个模块?

**为什么:** 在JavaScript中与日期,时间,和持续时间一起工作是出名的容易出错和不一致的. 开发者往往需要在数字、字符串和 `Date` 对象,或以人类友好的方式表示当前时间,但标准API是杂乱无章和零散的.

**如何解释:** 该图书馆提供一套统一的公用设施,用于标准日期/时间表述之间的无功转换(`number`, (中文(简体) ), `string`, (中文(简体) ), `Date`以及容易的格式和列报方式(例如, `formatDate`, (中文(简体) ), `timeAgo`, (中文(简体) ), `humanDurationString`) (中文(简体) ). 也使得不同时间单位(秒,时,日等)之间的转换和进行"从天起"或"从正月起"等常见计算变得微不足道.

**何谓:** 一套综合的转换、格式化和提交日期和时间的职能,加上与时间单位和期限合作的助手.

## 毫秒和秒数

JavaScript date-time-as-number使用毫秒为单位. 然而,秒往往是更自然(和高效)的选择单位. 这个库通过一个强大的假设来解决了这个问题,这个假设允许您同时使用毫秒和秒:

-   **日期/时间( 秒) :** 任意 `number < 100000000000` 被视为秒
-   **以毫秒计的日期/时间 :** 任意 `number >= 100000000000` 被认为是毫秒

这意味着支持的秒和毫秒日期时间范围为:

-   **以秒计的日期/时间 :** 1970年到公元5138年在位.
-   **以毫秒计的日期/时间范围 :** 1973-03-03T09:46:40.000Z 到基本永恒 (ChatGPT说公元275,760

换句话说,通过作出小的牺牲 -- -- 在1970至1973年期间不能代表大于5138年或毫秒的日期/时间秒 -- -- 我们获得了无缝工作的能力,既不能代表日期/时间的共同数字,也不能考虑使用哪个数字.

## 安装和使用示例( 需要)

用 npm 安装 :

```sh
npm install @art-suite/art-core-ts-time
```

基本用途:

```ts
import {
  formatDate,
  toMilliseconds,
  toSeconds,
  toDate,
  timeAgo,
  humanDurationString,
  firstOfDay,
  firstOfMonth,
  secondsPer,
} from "@art-suite/art-core-ts-time";

// Convert between types
toMilliseconds("2024-01-01"); // e.g., 1704067200000
toSeconds(new Date()); // e.g., 1704067200
toDate(1704067200000); // Date object

// Format and present
formatDate(new Date(), "yyyy-MM-dd"); // "2024-06-01"
timeAgo(new Date(Date.now() - 60000)); // "1m ago"
humanDurationString(3661); // "1h 1m 1s"

// Time calculations
firstOfDay(new Date()); // Seconds since epoch at start of today (UTC)
firstOfMonth(new Date()); // Seconds since epoch at start of this month (UTC)

// Time unit constants
secondsPer.hour; // 3600
secondsPer.day; // 86400
```

## 职能概览

### 转换水电费

-   `toMilliseconds(value)` - 转换 a `Date`,字符串,或数字到毫秒.
-   `toSeconds(value)` - 转换 a `Date`,字符串,或数字至秒.
-   `toDate(value)` - 转换字符串、数字或 `Date` 改为 `Date` 对象.

### 格式和列报

-   `formatDate(value, format?, utc?)` ——将日期格式化为字符串,可选格式和UTC支持.
-   `timeAgo(date, options?)` ——人性友好"相去相去"弦(如"相去相去","相去相去"等).
-   `humanDurationString(seconds, options?)` ——将一个持续时间以秒为单位格式为人可读字符串(如"1h 2m 3s").
-   `niceDateString(date, now?)` ——友好日期字符串(如"今天","同","六月一"等).
-   `niceFullDateString(date)` ——完整可读的日期字符串(如"3:45pm June 1, 2024").

### 时间计算

-   `firstOfHour(time)` ——时间刚开始的时代以来的秒数.
-   `firstOfDay(time)` ——自正月初一(UTC)起的秒数.
-   `firstOfWeek(time)` ——自一周开始(UTC,星期一)以来的秒数.
-   `firstOfMonth(time)` ——自正月初一起秒(UTC).
-   `firstOfYear(time)` ——自开元(UTC)以来的秒数.
-   地语变体: `firstOfDayLocale`, (中文(简体) ), `firstOfWeekLocale`, (中文(简体) ), `firstOfMonthLocale`, (中文(简体) ), `firstOfYearLocale`。 。 。 .

### 时间单位常数

-   `secondsPer` ——对象映射时间单位(如:, `hour`, (中文(简体) ), `day`, (中文(简体) ), `month`以秒计.

## API 文档参考

关于所有被输出功能及其参数的详细信息,请参见源代码内的TypeScript打字和JSDoc评论.

## 常见问题

### @art-suite/art-core-ts-time 是什么？

TypeScript 字符串工具库

### 如何安装 @art-suite/art-core-ts-time？

在项目目录运行 npm install @art-suite/art-core-ts-time，或使用 pnpm add / yarn add / bun add。

### @art-suite/art-core-ts-time 支持 TypeScript 吗？

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

### @art-suite/art-core-ts-time 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @art-suite/art-core-ts-time 可以商用吗？

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

### @art-suite/art-core-ts-time 的下载量有多少？

根据 npm 官方下载统计，@art-suite/art-core-ts-time 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,224 次，日均约 107 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @art-suite/art-core-ts-time 还在维护吗？

最新版本 0\.4\.1 发布于 2026/06/19（4 个月前）；至今共发布 22 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/05/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。