# @countrystatecity/timezones 中文文档

规范地址：https://npmcn.com/package/%40countrystatecity/timezones/

版本：2\.0\.2
npm 元数据更新时间：2026-11-03T14:16:27.669Z
中文译文更新时间：2026-11-10T22:11:04.031Z
软件包许可：ODbL-1\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40countrystatecity/timezones
原文对照：https://npmcn.com/package/%40countrystatecity/timezones/?lang=original
项目主页：https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/timezones#readme
源码仓库：https://github.com/dr5hn/countrystatecity-npm

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

- 包体积（解压后）：439 kB，267 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-10-18T13:13:10.314Z
- 最新版本发布：2026-11-03T14:16:27.166Z
- 近 30 天下载量：2655（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 8 个）

## 中文简介

配有转换设施和iOS/Safari支助的综合时区数据

## 安装

```sh
npm install @countrystatecity/timezones
```

也可以使用：`pnpm add @countrystatecity/timezones`、`yarn add @countrystatecity/timezones`、`bun add @countrystatecity/timezones`

## README

# @ 国家状态/ 时区

[![npm](https://img.shields.io/npm/v/@countrystatecity/timezones)](https://www.npmjs.com/package/@countrystatecity/timezones) [![CI](https://github.com/dr5hn/countrystatecity-npm/workflows/Pipeline/badge.svg)](https://github.com/dr5hn/countrystatecity-npm/actions/workflows/ci.yml) [![npm downloads](https://img.shields.io/npm/dm/@countrystatecity/timezones?label=timezones)](https://www.npmjs.com/package/@countrystatecity/timezones) [![npm downloads](https://img.shields.io/npm/dw/@countrystatecity/timezones?label=timezones)](https://www.npmjs.com/package/@countrystatecity/timezones)

具备转换设施和iOS/Safari支持的综合时区数据.

**环境:** 🖥️ **仅服务器侧** (Node.js, Next.js API线路,快递等)

## 升级到 2. 0

V4.0-export.50快照纠正了时区偏移和缩写. 所有432 IANA区记录都保留下来,但缩写搜索 `ACDT`, (中文(简体) ), `AEDT`, (中文(简体) ), `ALMT`, (中文(简体) ), `EASST`, (中文(简体) ), `EGT`, (中文(简体) ), `MIST`, (中文(简体) ), `MSD+1`, (中文(简体) ), `NZDT`, (中文(简体) ), `QYZST`, (中文(简体) ), `QYZT`,以及 `WEST` 现在不返回匹配。 简称 `CLT`, (中文(简体) ), `EAST`, (中文(简体) ), `KZT`,以及 `NZST` 添加了该词。 持久IANA区名和更新缩略语/抵销元数据后再升级.

此套件不包含城市/州编号 。 如果你把它与地理包结合起来 [上游 v 4.0 释放](https://github.com/dr5hn/countries-states-cities-database/releases/tag/v4.0) 文档删除地理标识并提供了 [`removed_ids_v3.2_to_v4.0.csv`](https://github.com/dr5hn/countries-states-cities-database/releases/download/v4.0/removed_ids_v3.2_to_v4.0.csv) 用于迁移存储的城市/州编号.

## \* 特性

-   🌐 **426个独立的IANA名称**: 本快照中432个国家和地区记录
-   🗺️ **250个国家**: 按国家排列的时区
-   🔄 **时间转换**: 很容易在时区间转换
-   ⏰ **当前时间**: 将当前时间输入任意时区
-   📅 **DST 支持**: 探测日出节省时间
-   📱 **iOS 兼容**: Safari/iOS 上没有堆栈溢出错误
-   🚀 **最小套装**: < 20KB 初始负载并带有懒惰负载
-   📝 **类型脚本**: 包括完整类型定义
-   🔧 **可树动**: 只捆绑您使用的

## \* 安装

```bash
npm install @countrystatecity/timezones
# or
yarn add @countrystatecity/timezones
# or
pnpm add @countrystatecity/timezones
```

## QQ 快速启动

```typescript
import {
  getTimezones,
  getTimezonesByCountry,
  convertTime,
  getCurrentTime
} from '@countrystatecity/timezones';

// Get all timezones (~74KB - lazy loaded)
const timezones = await getTimezones();
console.log(timezones.length); // 432 country/zone records

// Get timezones for a specific country (~0.3KB per country)
const usTimezones = await getTimezonesByCountry('US');
console.log(usTimezones);
// [
//   { zoneName: 'America/New_York', abbreviation: 'EST', ... },
//   { zoneName: 'America/Chicago', abbreviation: 'CST', ... },
//   ...
// ]

// Get current time in a timezone
const currentTime = await getCurrentTime('America/New_York');
console.log(currentTime); // "2025-10-18T08:30:00.000Z"

// Convert time between timezones
const converted = await convertTime(
  '2025-10-18 14:00',
  'America/New_York',
  'Asia/Tokyo'
);
console.log(converted);
// {
//   originalTime: "2025-10-18T14:00:00.000Z",
//   fromTimezone: "America/New_York",
//   convertedTime: "2025-10-19T04:00:00.000Z",
//   toTimezone: "Asia/Tokyo",
//   timeDifference: 14
// }
```

## 本地包还是活的API?

这个软件包传输了一个免费的,离线能力的数据快照——当应用程序必须离线工作时,这仍然是正确的选择,一个周期快照就足够了,或者你只需要简单的外观.

这个 [国家 API](https://countrystatecity.in/) 当您需要时, 值得同时加入:

-   **新鲜度** ——不发布新包版本而更新的数据.
-   **搜索** 模糊、耐打字、服务器侧搜索(`csc.search.fuzzy(...)`),而不只是精确匹配的本地外观.
-   **缩放支持( S)** ——可配置的速率限制和超过捆绑快照的支持.

**每月有3 000个请求免费开始.** [比较计划](https://countrystatecity.in/pricing?source=npm&campaign=sdk_api_migration&package=timezones) 或者说 [获取 API 密钥](https://app.countrystatecity.in/?source=npm&campaign=sdk_api_migration&package=timezones)。 。 。 .

```bash
npm install @countrystatecity/sdk
```

```typescript
// Before
import { getTimezonesByCountry } from '@countrystatecity/timezones';

const tzs = await getTimezonesByCountry('US');
```

```typescript
// After
import { createCSCClient } from '@countrystatecity/sdk';

const csc = createCSCClient({ apiKey: process.env.CSC_API_KEY! });
const { data: tzs } = await csc.timezones.byCountry('US');
```

见 [完整移徙指南](https://github.com/dr5hn/countrystatecity-npm/blob/main/packages/sdk/MIGRATION.md) 用于错误处理、重试等等.

## API 参考

### 核心职能

#### `getTimezones()`

获取所有可用的时区 .

```typescript
const timezones = await getTimezones();
// Returns: ITimezone[]
```

**套装效果**:~74KB (韩语)

#### `getTimezonesByCountry(countryCode: string)`

获取特定国家的时区 .

```typescript
const timezones = await getTimezonesByCountry('US');
// Returns: ITimezone[]
```

**参数:**

-   `countryCode` - ISO 3166-1 α-2国家代码(例如“美国”,“IN”)

**套装效果**: ~0.3KB 每个国家

#### `getTimezoneInfo(timezoneName: string)`

获取包括当前时间在内的一个时区的详细信息 .

```typescript
const info = await getTimezoneInfo('America/New_York');
// Returns: ITimezoneInfo | null
```

**回返情况:**

```typescript
{
  timezone: "America/New_York",
  currentTime: "2025-10-18T08:30:00.000Z",
  utcOffset: "UTC-05:00",
  isDST: false,
  gmtOffset: -18000
}
```

#### `getTimezoneAbbreviations()`

获取所有时区缩写( PST, EST等).

```typescript
const abbreviations = await getTimezoneAbbreviations();
// Returns: ITimezoneAbbreviation[]
```

**套装效果**: ~5KB 键

#### `getTimezonesByAbbreviation(abbreviation: string)`

以缩写查找时区.

```typescript
const timezones = await getTimezonesByAbbreviation('EST');
// Returns: ITimezone[]
```

### 工具函数

#### `convertTime(time, fromTimezone, toTimezone)`

从一个时区转换时间到另一个时区.

```typescript
const result = await convertTime(
  '2025-10-18 14:00',
  'America/New_York',
  'Europe/London'
);
// Returns: IConvertedTime
```

**参数:**

-   `time` - 转换时间(ISO字符串或日期对象)
-   `fromTimezone` - 源时区(IANA名称)
-   `toTimezone` - 目标时区(IANA名称)

#### `getCurrentTime(timezoneName: string)`

在一个特定的时区获得当前时间 .

```typescript
const time = await getCurrentTime('Asia/Tokyo');
// Returns: string (ISO format)
```

#### `isDaylightSaving(timezoneName: string, date?: Date)`

检查日出保存时间是否激活 .

```typescript
const isDST = await isDaylightSaving('America/New_York');
// Returns: boolean
```

**参数:**

-   `timezoneName` - IANA 时区名称
-   `date` - 检查的可选日期( 默认日期)

#### `getGMTOffset(timezoneName: string)`

得到格林尼治平分/UTC相抵秒数.

```typescript
const offset = await getGMTOffset('America/New_York');
// Returns: number (e.g., -18000 for UTC-05:00)
```

#### `formatGMTOffset(offsetSeconds: number)`

格式 GMT 从秒到字符串相抵消 .

```typescript
const formatted = formatGMTOffset(-18000);
// Returns: "UTC-05:00"
```

#### `isValidTimezone(timezoneName: string)`

验证一个时区名称是否有效 .

```typescript
const isValid = await isValidTimezone('America/New_York');
// Returns: boolean
```

#### `searchTimezones(searchTerm: string)`

按名称搜索时区(部分匹配).

```typescript
const results = await searchTimezones('america');
// Returns: ITimezone[]
```

#### `getUniqueAbbreviations()`

获得所有独特的时区缩写.

```typescript
const abbreviations = await getUniqueAbbreviations();
// Returns: string[] (e.g., ['EST', 'PST', 'CST', ...])
```

#### `getTimezonesByOffset(offsetSeconds: number)`

获得格林尼治平时的时区.

```typescript
const timezones = await getTimezonesByOffset(-18000); // UTC-05:00
// Returns: ITimezone[]
```

## 现实世界实例

### 会议排程器

```typescript
import { convertTime, getTimezonesByCountry } from '@countrystatecity/timezones';

async function scheduleMeeting(localTime: string, attendeeCountries: string[]) {
  const meetingTimes = [];

  for (const countryCode of attendeeCountries) {
    const timezones = await getTimezonesByCountry(countryCode);
    const primaryTz = timezones[0];

    const converted = await convertTime(
      localTime,
      'America/New_York',
      primaryTz.zoneName
    );

    meetingTimes.push({
      country: countryCode,
      timezone: primaryTz.zoneName,
      time: converted.convertedTime
    });
  }

  return meetingTimes;
}

// Schedule 2 PM EST meeting for US, UK, and Japan
const times = await scheduleMeeting('2025-10-18 14:00', ['US', 'GB', 'JP']);
```

### 世界时钟

```typescript
import { getTimezonesByCountry, getCurrentTime } from '@countrystatecity/timezones';

async function createWorldClock(countryCodes: string[]) {
  const clocks = [];

  for (const code of countryCodes) {
    const timezones = await getTimezonesByCountry(code);
    for (const tz of timezones) {
      const currentTime = await getCurrentTime(tz.zoneName);
      clocks.push({
        location: tz.tzName,
        timezone: tz.zoneName,
        currentTime,
        offset: tz.gmtOffsetName
      });
    }
  }

  return clocks;
}

const worldClock = await createWorldClock(['US', 'GB', 'IN', 'AU', 'JP']);
```

### DST 提醒

```typescript
import { isDaylightSaving, getTimezonesByCountry } from '@countrystatecity/timezones';

async function checkDSTStatus(countryCode: string) {
  const timezones = await getTimezonesByCountry(countryCode);

  const dstStatus = [];
  for (const tz of timezones) {
    const isDST = await isDaylightSaving(tz.zoneName);
    dstStatus.push({
      timezone: tz.tzName,
      isDST,
      message: isDST
        ? 'Daylight Saving Time is active'
        : 'Standard Time'
    });
  }

  return dstStatus;
}
```

## QQ 类型脚本

```typescript
interface ITimezone {
  zoneName: string;        // "America/New_York"
  countryCode: string;     // "US"
  abbreviation: string;    // "EST"
  gmtOffset: number;       // -18000 (seconds)
  gmtOffsetName: string;   // "UTC-05:00"
  tzName: string;          // "Eastern Standard Time"
}

interface ITimezoneInfo {
  timezone: string;
  currentTime: string;     // ISO string
  utcOffset: string;       // "UTC-05:00"
  isDST: boolean;
  gmtOffset: number;
}

interface ITimezoneAbbreviation {
  abbreviation: string;    // "EST"
  name: string;            // "Eastern Standard Time"
  timezones: string[];     // ["America/New_York", ...]
}

interface IConvertedTime {
  originalTime: string;
  fromTimezone: string;
  convertedTime: string;
  toTimezone: string;
  timeDifference: number;  // hours
}
```

## QQ 套装大小

| 行动 | 套装大小 |
| --- | --- |
| 安装软件包+导入功能 | ~ 5KB 键 |
| 装入全部时区 | ~74KB (英语) |
| 一个国家装入时区 | ~0.3千贝 |
| 装入缩略语 | ~ 5KB 键 |
| **典型用途** | **~ 10KB 键** |

### 数据覆盖

-   **426个独立的IANA名称** 记录
-   **250个国家代码**,包括南极洲的11个区记录`AQ`(中文(简体) )
-   **142个缩略语绘图** 从上游元数据

该快照包含区域名称,偏移,缩写和显示名称. 它不运送历史过渡数据库;特定日期的转换使用运行时间的 `Intl` 时区数据.

**说明**: 时区数据自动来自 [国家城市数据库](https://github.com/dr5hn/countries-states-cities-database) 每周更新一次.

## 测试

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch
```

所有软件包包括全面测试:

-   单位测试
-   综合测试
-   iOS/Safari兼容性测试

## ++CI/CD和自动化

### 持续整合

每一次推和公关自动:

-   使用 TypeScript 进行类型检查
-   \* 执行综合测试套件
-   QQ 构建软件包
-   校验捆绑大小
-   iOS/Safari 兼容性测试

### 自动数据更新

每周自动更新( 星期日 UTC 00: 00):

-   QQ 从权威来源下载最新时区数据
-   \* 转换成优化结构
-   QQ 运行全测试套件
-   如果检测到变化, 则创建 PR 以供审查

这保证了您的应用程序总是可以获取最新的时区信息而无需人工干预.

### 自动出版

自动向国家预防机制发布版本变化:

-   QQ 检测软件包中的版本出错. json
-   发布前的构建和测试
-   国家防范机制登记册出版物
-   QQ 创建带有更改日志的 GitHub 发布

## 许可证

[ODbL-1.0. 导弹](https://github.com/dr5hn/countrystatecity/blob/main/LICENSE) © [驱动器5hn](https://github.com/dr5hn)

此软件包及其数据由开放数据库许可证(ODbL)v1.0许可. 数据来源于 [国家城市数据库](https://github.com/dr5hn/countries-states-cities-database) 也根据ODbL-1.0获得许可证.

您可以自由分享,创建,并修改这个数据库,只要您将原始源属性化,在同一许可证下发布修改,并且不要使用技术限制来锁定数据.

## 捐款

欢迎捐款! 请打开一个问题或公关.

**数据相关问题** (不正确的时区数据、缺失时区、错误的抵消等) [国家城市数据库](https://github.com/dr5hn/countries-states-cities-database/issues) 寄存器,是此软件包的权威数据源.

## 成套生态系统

此软件包是 [@ 国家状态包生态系统](https://github.com/dr5hn/countrystatecity-npm)数字 :

-   **[@ 国家/ 国家](https://www.npmjs.com/package/@countrystatecity/countries)** ——服务器侧国家,州和城市数据库. 环境:Node.js, Next.js API路线,快通. Bundle: <10KB初始负载.
    
-   **[@ 国家状态/ 国家浏览器](https://www.npmjs.com/package/@countrystatecity/countries-browser)** – 有jsDelivr CDN和懒惰加载的浏览器-本地版本. 环境:React,Vue,Svelte,Vite,任意浏览器. 与服务器包相同的API——零配置,只是导入和使用.
    
-   **[@ 国家状态/ 时区](https://www.npmjs.com/package/@countrystatecity/timezones)** (本套件)-配有转换公用设施的综合时区数据. 环境:只有服务器侧. Bundle: <20KB初始负载.
    

## 链接

-   [GitHub 仓库](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/timezones)
-   [问题](https://github.com/dr5hn/countrystatecity-npm/issues)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@countrystatecity/timezones)
-   [国家预防机制组织](https://www.npmjs.com/org/countrystatecity)

## 常见问题

### @countrystatecity/timezones 是什么？

配有转换设施和iOS/Safari支助的综合时区数据

### 如何安装 @countrystatecity/timezones？

在项目目录运行 npm install @countrystatecity/timezones，或使用 pnpm add / yarn add / bun add。

### @countrystatecity/timezones 支持 TypeScript 吗？

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

### @countrystatecity/timezones 支持 ESM 还是 CommonJS？

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

### @countrystatecity/timezones 可以商用吗？

@countrystatecity/timezones 使用 ODbL-1\.0 许可。声明的许可为 ODbL-1\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @countrystatecity/timezones 的下载量有多少？

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

### @countrystatecity/timezones 还在维护吗？

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