1# 时区 2 3<!--Kit: Localization Kit--> 4<!--Subsystem: Global--> 5<!--Owner: @yliupy--> 6<!--Designer: @sunyaozu--> 7<!--Tester: @lpw_work--> 8<!--Adviser: @Brilliantry_Rui--> 9 10## 使用场景 11 12全球各国家和地区的经度不同，地方时间也有所不同，因此划分了不同的时区。例如，英国采用0时区，中国采用东8时区，中国时间要比英国快8小时，中国北京中午12:00，对应英国伦敦是凌晨4:00。时区模块可用于获取时区列表，应用可基于该列表实现业务逻辑，如双时钟应用。<br/>从API version 20开始，时区模块还可用于获取时区跳变时间点和偏移量等，时区的跳变逻辑参考[夏令时跳变](./i18n-dst-transition.md)。 13 14## 接口说明 15 16时区模块关键接口如下表所示，具体API说明详见[国际化-I18n](../reference/apis-localization-kit/js-apis-i18n.md)。 17 18| 接口名 | 描述 | 19| -------- | -------- | 20| getTimeZone(zoneID?: string): TimeZone | 获取时区ID对应的时区对象。 | 21| getID(): string | 获取时区对象的ID。 | 22| getDisplayName(locale?: string, isDST?: boolean): string | 获取时区对象名称在指定语言下的翻译。 | 23| getRawOffset(): number | 获取时区的固定偏移量。 | 24| getOffset(date?: number): number | 获取某一时刻时区对象所表示时区的偏移量。 | 25| getAvailableIDs(): Array<string> | 获取系统支持的时区ID列表。 | 26| getAvailableZoneCityIDs(): Array<string> | 获取系统支持的时区城市ID列表 | 27| getCityDisplayName(cityID: string, locale: string): string | 获取时区城市名称在指定语言下的翻译。 | 28| getTimezoneFromCity(cityID: string): TimeZone | 根据城市ID创建对应的时区对象。 | 29| getTimezonesByLocation(longitude: number, latitude: number): Array<TimeZone> | 根据地理坐标获取所在时区对象的数组。 | 30| getZoneRules(): ZoneRules | 获取时区跳变规则。 | 31| nextTransition(date?: number): ZoneOffsetTransition | 获取指定时间的下一个时区跳变对象。 | 32| getMilliseconds(): number | 获取时区跳变点的时间戳。 | 33| getOffsetAfter(): number | 获取时区跳变后的偏移量。 | 34| getOffsetBefore(): number | 获取时区跳变前的偏移量。 | 35 36## 开发步骤 37 38### 时区相关功能 39 401. 导入模块。 41 ```ts 42 import { i18n } from '@kit.LocalizationKit'; 43 ``` 44 452. 开发实例，包括获取特定时区、计算固定和实际时区偏移量、遍历时区列表。 46 ```ts 47 // 获取巴西时区 48 let timezone: i18n.TimeZone = i18n.getTimeZone('America/Sao_Paulo'); // 传入特定时区，创建时区对象 49 let timezoneId: string = timezone.getID(); // timezoneId = 'America/Sao_Paulo' 50 51 // 获取城市ID对应的时区对象 52 let aucklandTimezone: i18n.TimeZone = i18n.TimeZone.getTimezoneFromCity('Auckland'); 53 timezoneId = aucklandTimezone.getID(); // timezoneId = 'Pacific/Auckland' 54 55 // 获取时区的本地化名称 56 let timeZoneName: string = timezone.getDisplayName('zh-Hans', true); // timeZoneName = '巴西利亚标准时间' 57 58 // 本地化城市名称 59 let cityDisplayName: string = i18n.TimeZone.getCityDisplayName('Auckland', 'zh-Hans'); // cityDisplayName = '奥克兰 (新西兰)' 60 61 // 时区的固定偏移量 62 let rawOffset: number = timezone.getRawOffset(); // rawOffset = -10800000 63 64 // 时区的实际偏移量（固定偏移量+夏令时） 65 let offset: number = timezone.getOffset(1234567890); // offset = -10800000 66 67 // 系统支持的时区ID列表 68 let availableIDs: Array<string> = i18n.TimeZone.getAvailableIDs(); // availableIDs = ['America/Adak', 'Asia/Hovd', ...] 69 70 // 系统支持的时区城市ID列表 71 let cityIDs: Array<string> = i18n.TimeZone.getAvailableZoneCityIDs(); // cityIDs = ['Auckland', 'Magadan', ...] 72 73 // 遍历时区城市ID列表 74 let timezoneList: Array<object> = []; // 呈现给用户的时区列表 75 76 class Item { 77 cityDisplayName: string = ""; 78 timezoneId: string = ""; 79 offset: string = ""; 80 cityId: string = "" 81 } 82 83 for (let i = 0; i < cityIDs.length; i++) { 84 let cityId: string = cityIDs[i]; 85 let timezone: i18n.TimeZone = i18n.TimeZone.getTimezoneFromCity(cityId); // 城市ID对应的时区对象 86 let cityDisplayName: string = i18n.TimeZone.getCityDisplayName(cityId, 'zh-CN'); // 本地化城市名称 87 let timestamp: number = (new Date()).getTime(); 88 let item: Item = { 89 cityDisplayName: cityDisplayName, 90 timezoneId: timezone.getID(), 91 offset: 'GMT' + (timezone.getOffset(timestamp) / 3600 * 1000), 92 cityId: cityId 93 }; 94 timezoneList.push(item); 95 } 96 97 // 指定地理坐标所在的时区对象数组 98 let timezoneArray: Array<i18n.TimeZone> = i18n.TimeZone.getTimezonesByLocation(-43.1, -22.5); 99 100 // 获取指定时间的下一个时区跳变点 101 let tijuanaTzId: string = 'America/Tijuana'; 102 let tijuanaTimeZone: i18n.TimeZone = i18n.getTimeZone(tijuanaTzId); // 获取蒂华纳时区对象 103 let zoneRules: i18n.ZoneRules = tijuanaTimeZone.getZoneRules(); // 获取蒂华纳时区的时区跳变规则 104 let someTime = new Date(2025, 4, 13); 105 let zoneOffsetTrans: i18n.ZoneOffsetTransition = zoneRules.nextTransition(someTime.getTime()); 106 zoneOffsetTrans.getMilliseconds(); // 跳变点的时间戳: 1762074000000 107 zoneOffsetTrans.getOffsetAfter(); // 跳变后的偏移量: -28800000 108 zoneOffsetTrans.getOffsetBefore(); // 跳变前的偏移量: -25200000 109 // 将跳变点时间格式化 110 let dateTimeFormat: Intl.DateTimeFormat = new Intl.DateTimeFormat('en-US', { 111 timeZone: tijuanaTzId, 112 dateStyle: 'long', 113 timeStyle: 'long', 114 hour12: false 115 }); 116 let dateFormat: string = 117 dateTimeFormat.format(new Date(zoneOffsetTrans.getMilliseconds())); // November 2, 2025, 1:00:00 PST 118 ``` 119 120### 双时钟应用 121 1221. 导入模块。 123 ```ts 124 import { i18n } from '@kit.LocalizationKit'; 125 ``` 126 1272. 选择时区列表中的时区，添加到应用偏好时区列表。 128 ```ts 129 let pauloTimezone: i18n.TimeZone = i18n.getTimeZone('America/Sao_Paulo'); 130 let defaultTimezone: i18n.TimeZone = i18n.getTimeZone(); 131 let appPreferredTimeZoneList: Array<i18n.TimeZone> = []; // 应用偏好时区列表 132 appPreferredTimeZoneList.push(pauloTimezone); 133 appPreferredTimeZoneList.push(defaultTimezone); 134 ``` 135 1363. 遍历应用偏好时区列表，获取各时区的时间。 137 ```ts 138 let locale: Intl.Locale = i18n.System.getSystemLocaleInstance(); 139 for (let i = 0; i < appPreferredTimeZoneList.length; i++) { 140 let timezone: string = appPreferredTimeZoneList[i].getID(); 141 let calendar: i18n.Calendar = i18n.getCalendar(locale.toString()); 142 calendar.setTimeZone(timezone); // 设置日历对象的时区 143 // 获取年月日时分秒 144 let year: number = calendar.get('year'); 145 let month: number = calendar.get('month'); 146 let day: number = calendar.get('date'); 147 let hour: number = calendar.get('hour'); 148 let minute: number = calendar.get('minute'); 149 let second: number = calendar.get('second'); 150 } 151 ```