@ 国家状态/ 时区

具备转换设施和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 释放 文档删除地理标识并提供了 removed_ids_v3.2_to_v4.0.csv 用于迁移存储的城市/州编号.

* 特性

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

* 安装

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

QQ 快速启动

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 当您需要时, 值得同时加入:

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

每月有3 000个请求免费开始. 比较计划 或者说 获取 API 密钥。 。 。 .

npm install @countrystatecity/sdk

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

const tzs = await getTimezonesByCountry('US');

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

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

见 完整移徙指南 用于错误处理、重试等等.

API 参考

核心职能

getTimezones()

获取所有可用的时区 .

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

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

getTimezonesByCountry(countryCode: string)

获取特定国家的时区 .

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

参数:

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

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

getTimezoneInfo(timezoneName: string)

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

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

回返情况:

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

getTimezoneAbbreviations()

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

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

套装效果: ~5KB 键

getTimezonesByAbbreviation(abbreviation: string)

以缩写查找时区.

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

工具函数

convertTime(time, fromTimezone, toTimezone)

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

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)

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

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

isDaylightSaving(timezoneName: string, date?: Date)

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

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

参数:

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

getGMTOffset(timezoneName: string)

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

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

formatGMTOffset(offsetSeconds: number)

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

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

isValidTimezone(timezoneName: string)

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

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

searchTimezones(searchTerm: string)

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

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

getUniqueAbbreviations()

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

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

getTimezonesByOffset(offsetSeconds: number)

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

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

现实世界实例

会议排程器

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']);

世界时钟

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 提醒

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 类型脚本

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 套装大小

数据覆盖

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

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

说明: 时区数据自动来自 国家城市数据库 每周更新一次.

测试

# 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. 导弹 © 驱动器5hn

此软件包及其数据由开放数据库许可证(ODbL)v1.0许可. 数据来源于 国家城市数据库 也根据ODbL-1.0获得许可证.

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

捐款

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

数据相关问题 (不正确的时区数据、缺失时区、错误的抵消等) 国家城市数据库 寄存器,是此软件包的权威数据源.

成套生态系统

此软件包是 @ 国家状态包生态系统数字 :

• @ 国家/ 国家 ——服务器侧国家,州和城市数据库. 环境:Node.js, Next.js API路线,快通. Bundle: <10KB初始负载.

• @ 国家状态/ 国家浏览器 – 有jsDelivr CDN和懒惰加载的浏览器-本地版本. 环境:React,Vue,Svelte,Vite,任意浏览器. 与服务器包相同的API——零配置,只是导入和使用.

• @ 国家状态/ 时区 (本套件)-配有转换公用设施的综合时区数据. 环境:只有服务器侧. Bundle: <20KB初始负载.

链接

• GitHub 仓库
• 问题
• 国家防范机制一揽子计划
• 国家预防机制组织