微信小程序世界时间：moment-timezone时区转换实战

简介微信小程序世界时间设置示例源码是一套面向初中级小程序开发者的实践项目旨在演示如何构建全球多城市时间查询与设置功能从而掌握小程序从页面搭建到逻辑处理的基本流程。压缩包共9个文件含5个js、2个json、1个wxml、1个wxss大小仅39KB其中js负责业务逻辑与工具函数json配置全局与页面参数wxml和wxss分别完成界面结构与样式。项目基于moment及moment-timezone实现时区换算并演示了数据绑定、生命周期函数、点击事件等核心知识也适合作为学习模块化与工具库用法的参考。目前已有202人学习代码体量小、结构清晰可帮助开发者快速理解并改造出自己的世界时钟小程序。1. 世界时间小程序为什么我放弃了系统 API 而选择 moment-timezone做微信小程序时遇到一个真实需求界面要同时显示纽约、东京、伦敦的实时时间并且不同设备看到的结果必须一致。设备本地时间拿到的是“这一刻”但用户手机可能是北京时间、美东时间或 UTC直接用new Date()再算时区偏移代码立刻变成一团浆糊。尝试用微信自带的wx.getSystemInfo和Intl.DateTimeFormat发现小程序的 JavaScript 内核在不同平台上对Intl支持不一致有的直接报错有的返回结果不正确。后来拆这个“世界时间设置 demo”的源码发现它采用了moment.js和moment-timezone.js这两个库把所有时区转换问题全部变成了数据查询逻辑清晰很多。这篇文章不是泛泛介绍小程序目录结构而是围绕时区数据如何在小程序里加载、计算和刷新把 demo 的核心代码逐一拆开适合想在小程序里做多时区、排期、日历功能的开发者。2. 先拆项目骨架app.json、pages 和依赖库的组织方式2.1 小程序全局配置与页面注册打开 demo 源码先看根目录的app.json这是小程序的入口配置。所有页面必须在pages字段中注册否则无法访问。同时window字段定义了导航栏样式和背景色。在这个 demo 里核心页面是pages/index其余页面未必很多但app.json中的配置决定了后续代码的加载方式。{ pages: [ pages/index/index ], window: { navigationBarTitleText: 世界时间, navigationBarBackgroundColor: #1f1f1f, navigationBarTextStyle: white } }pages数组中的第一项就是小程序启动后展示的第一页。这里只有一个index页面说明 demo 的业务逻辑全部集中在pages/index下。navigationBarTitleText是顶部导航栏的标题navigationBarBackgroundColor和navigationBarTextStyle控制标题栏颜色把背景设为深色、文字设为白色是为了配合世界时间这种跨时区场景的视觉效果。如果后续要增加“城市管理”页面需要手动在pages里追加路径否则跳转时会提示页面不存在。2.2 moment-timezone 在小程序里的引入方式微信小程序不像普通 Node.js 项目直接把moment-timezone安装到node_modules还不够。常见做法有两种一种是通过开发者工具的“构建 npm”功能然后使用import或require另一种是直接把moment.js和moment-timezone.js文件复制到utils目录再用相对路径引入。demo 采用的是后一种方式因为在小程序包上传时必须显式看到文件而且依赖版本可控不需要每次在开发者工具里点“构建 npm”。引入方式优点缺点适用场景开发者工具构建 npm版本管理清晰更新方便每次改依赖要重新构建代码压缩后调试栈不友好团队项目、依赖较多直接复制 js 文件到 utils代码一目了然打包体积可控手动更新库文件小型 demo、单个页面从插件市场引入封装库开箱即用黑盒出现问题难定位原型验证、非核心逻辑我一般建议先把moment.min.js和moment-timezone-with-data.min.js放进utils因为moment-timezone的完整数据文件体积不小直接引用完整文件会让小程序主包接近 2MB但只要不涉及分包demo 场景还能接受。引入方式如下const moment require(../../utils/moment.min.js); const momentTZ require(../../utils/moment-timezone-with-data.min.js);require的路径要从当前文件出发pages/index/index.js到utils目录要回退两级所以是../../utils。第一个require加载moment核心库第二个require加载时区数据并且它也会在内部绑定到同一个moment对象上所以后面直接用moment.tz()即可。这里有个容易被忽略的细节必须先引入moment.min.js再引入moment-timezone-with-data.min.js顺序反了会抛出moment.tz is not a function。2.3 封装时区查询工具为了让页面代码不直接依赖moment-timezonedemo 一般会在utils下单独放一个timezone.js把“根据时区名称获取格式化时间”的逻辑集中管理。这样页面里只需要调用一个函数后续改时间格式也只需改一处。const momentTZ require(./moment-timezone-with-data.min.js); function formatTimeByZone(timeZone, pattern) { if (!momentTZ.tz.zone(timeZone)) { throw new Error(Unsupported time zone: timeZone); } return momentTZ().tz(timeZone).format(pattern || YYYY-MM-DD HH:mm:ss); } module.exports { formatTimeByZone: formatTimeByZone };formatTimeByZone接收两个参数timeZone是 IANA 时区名称比如America/New_Yorkpattern是moment的格式化模板默认输出“年-月-日 时:分:秒”。momentTZ.tz.zone(timeZone)用来检查时区名是否真实存在避免拼写错误导致运行时异常。注意这里调用的是momentTZ()也就是当前时刻没有传时间戳因为显示世界时间必须永远基于“现在的瞬间”而不是某个写死的日期。如果需要按下某个城市后固定某一时刻的时间可以传入时间戳或日期字符串但 demo 里的核心场景是实时刷新所以默认取当前时刻。2.4 时区数据裁剪的取舍moment-timezone-with-data.min.js包含了全球上千个时区但真实业务用到的可能只有十几个城市。如果执着于包体大小可以只保留一部分时区数据用moment.tz.add手动添加城市定义。但这个 demo 没有这么做原因是“世界时间”天然需要覆盖全世界的主要城市一旦裁剪掉某个冷门城市用户切换时就会直接报错。折中方案是把城市列表限制在 20 个以内并只加载这些城市对应的时区数据体积能从几百 KB 降到几十 KB。如果后续要发布正式版建议单独抽一个timezone-data.js在构建时按城市列表动态生成。这里我常用 Node 脚本读取一个 JSON 城市表再调用moment.tz.zone采集数据最后拼接成一个精简版时区数据文件但 demo 中的完整数据文件更适合作为学习时的对照基准。3. 核心逻辑时区数据加载、时间格式与数据绑定3.1 城市列表与时区映射打开pages/index/index.js数据源不再是硬编码的UTC8这种偏移量而是一个城市对象数组。每个对象包含三个字段显示名称、IANA 时区名、以及初始化时用到的默认城市标记。城市名称用于界面展示时区名交给moment.tz计算。const timezoneUtil require(../../utils/timezone.js); Page({ data: { cityList: [ { name: 北京, zone: Asia/Shanghai }, { name: 东京, zone: Asia/Tokyo }, { name: 纽约, zone: America/New_York }, { name: 伦敦, zone: Europe/London } ], timeList: [], currentZone: Asia/Shanghai, currentTime: }, onLoad() { this.updateTimes(); this.timer setInterval(() { this.updateTimes(); }, 1000); }, updateTimes() { const now Date.now(); const timeList this.data.cityList.map(item { return { name: item.name, zone: item.zone, time: timezoneUtil.formatTimeByZone(item.zone, YYYY-MM-DD HH:mm:ss) }; }); this.setData({ timeList: timeList, currentTime: timezoneUtil.formatTimeByZone(this.data.currentZone, HH:mm:ss) }); } });now变量虽然在这个代码片段中没有直接传给formatTimeByZone但它代表了一个关键设计同一颗时间戳必须在一次刷新中共享避免不同城市之间因为调用时间差出现秒级偏差。实际项目中我会把formatTimeByZone改成接收第二个参数timestamp然后统一用这一毫秒值去格式化所有城市。setInterval设定为 1 秒一次是因为界面要展示“秒针”如果只显示到分钟把间隔改成 30000 毫秒即可省电且减少setData开销。currentTime是单独给页面顶部大号数字用的它和列表用的格式化模板不同列表需要完整日期顶部只需要时分秒。3.2 wxml 渲染与 wxs 格式化边界index.wxml负责把timeList渲染成一组卡片。微信小程序的插值表达式做不了复杂函数调用所以不能在{{}}里写moment()只能把格式化结果预先放在timeList的time字段中。这是 iOS 和 Android 端统一表现的关键因为不同端的 JavaScript 引擎对Date.prototype.toLocaleString生成结果不一致但字符串拼接永远不会出错。view classcontainer view classcurrent-time{{currentTime}}/view view classcity-grid block wx:for{{timeList}} wx:keyzone view classcity-card bindtaponSelectCity>onHide() { if (this.timer) { clearInterval(this.timer); this.timer null; } }, onUnload() { if (this.timer) { clearInterval(this.timer); this.timer null; } }清理定时器后如果小程序只是切到后台再回到前台onShow阶段要重新启动定时器并立刻更新一次时间否则界面时间会停留在后台时刻。这一块很多新手会漏掉我一般会抽成一个公共mixin给所有需要实时时间的页面复用。微信小程序支持Behavior把定时器管理逻辑放进去就够了。4. 实战动态切换城市、自动刷新与夏令时处理4.1 点击卡片切换当前城市demo 的交互不复杂点击任意城市卡片后顶部大号时间切换成该城市的当前时间。实现方法是在 3.1 节预留的onSelectCity事件处理函数中处理。onSelectCity(e) { const zone e.currentTarget.dataset.zone; if (!zone) return; this.setData({ currentZone: zone, currentTime: timezoneUtil.formatTimeByZone(zone, HH:mm:ss) }); }e.currentTarget.dataset.zone能取到 wxml 里>const momentTZ require(../../utils/moment-timezone-with-data.min.js); const winterDate 2024-01-15 12:00:00; const summerDate 2024-07-15 12:00:00; const offsetWinter momentTZ.tz(winterDate, America/New_York).utcOffset(); const offsetSummer momentTZ.tz(summerDate, America/New_York).utcOffset(); console.log(offsetWinter); // 300 分钟即 UTC-5 console.log(offsetSummer); // 240 分钟即 UTC-4utcOffset()返回的是分钟数不是小时数这点极容易把人绕晕。300 分钟等于 5 小时也就是说 1 月时纽约比 UTC 慢 5 小时7 月慢 4 小时。不要自己去写8或-5这种便宜逻辑否则一份维护两年的代码总有一天会遇到“欧洲在夏令时切换当天少了一小时”的线上问题。moment.tz还支持zone.abbr(timestamp)来获取缩写名比如EST、EDT在 UI 上展示会比单纯偏移量更友好。需要注意zone.abbr在不同环境下可能返回不同格式紧凑型数据甚至可能返回空字符串所以我对abbr的惯例是优先展示城市名把缩写作为次要信息。4.3 最小化 setData 与请求频控一秒一次的setData会不断触发视图层 diff如果页面存在地图组件频繁更新会造成明显卡顿。更合理的做法是把秒级刷新只应用到顶部currentTime城市列表的时间改为每 30 秒到 60 秒刷新一次。updateListTimes() { const timeList this.data.cityList.map(item ({ name: item.name, zone: item.zone, time: timezoneUtil.formatTimeByZone(item.zone, HH:mm:ss) })); this.setData({ timeList }); }, updateCurrentTime() { this.setData({ currentTime: timezoneUtil.formatTimeByZone(this.data.currentZone, HH:mm:ss) }); }这里拆成两个函数后定时器里可以分别设置一个每秒调用updateCurrentTime另一个每隔 30 秒调用updateListTimes。如果城市列表只有三四个城市每秒全量更新其实也不明显但往往 demo 会预留几十个城市这时候每秒钟做几十次时间格式化再通过setData传几十个对象CPU 占用会直线上升。另一个优化是硬件时钟校准小程序的Date.now()来自设备系统用户手动改系统时间会直接影响结果。如果需要可信时间可以在onShow时调用一款时间校准接口把本地时间与服务器时间的偏移量缓存起来后续计算都用“本地时间 偏移量”合成伪时间戳。这种方案我不建议在 demo 中使用因为引入网络请求会掩盖时区库本身的学习重点但正式项目里几乎必做。5. 进阶验证用时间戳快照校验 demo 的时区计算结果5.1 用 Node.js 对拍关键时区demo 在小程序里运行逻辑没问题但每次都要打开开发者工具肉眼观察效率太低。我习惯在命令行用 Node.js 跑一份同样的moment-timezone把固定时间戳下的格式化结果和小程序端打印的日志做对拍。先在项目根目录创建verify.jsconst momentTZ require(./utils/moment-timezone-with-data.min.js); const timestamps [ { label: DST开始前, time: 2024-03-10 06:59:00 }, { label: DST开始后, time: 2024-03-10 07:00:00 } ]; timestamps.forEach(({ label, time }) { const ny momentTZ.tz(time, America/New_York).format(YYYY-MM-DD HH:mm:ss); const bj momentTZ.tz(time, Asia/Shanghai).format(YYYY-MM-DD HH:mm:ss); console.log(${label}: 纽约${ny}, 北京${bj}); });运行命令node verify.js观察两个边界时刻的换算结果。2024 年 3 月 10 日是美国转入夏令时的时刻纽约本地时间从 2 点直接跳到 3 点所以 07:00 UTC 时纽约已经是 3 点用 Node 跑出的结果应该是 03:00而非 02:00。小程序端如果也用同一份数据文件结果必然一致因此一旦有误差问题就出在小程序环境对Date的解析上。5.2 在开发者工具中验证设备时区无关性这个 demo 的核心目标是“无论手机设置成哪个时区显示的城市时间都不变”所以验证时必须切换设备时区。在微信开发者工具的“普通编译”下拉菜单里可以自定义设备参数把系统时区改为“美国东部”再编译预览观察顶部北京时间的卡片是否依然按Asia/Shanghai计算。如果时间显示变成了设备当地时间说明代码里混入了new Date()而没有走moment.tz去显式指定时区。另一种更快的验证是直接修改电脑系统时间再重进小程序看currentTime是否等于城市时区的时间。这个方法只建议在 demo 阶段使用因为小程序在真机上读取的是手机系统时间开发者工具模拟器与实际手机在时区数据上完全一致但Intl的行为有差异所以重点验证moment.tz路径即可。最后补充一个可复用的小技巧在utils/timezone.js中增加一个getTimeStamp函数统一提供当前可信时间戳所有计算都改用它。getTimeStamp内部定义一个本地模块级变量在onShow时同步一次系统时间之后每秒增加 1000而不是每次调用Date.now()。这样做的好处是即使某些安卓机型在低功耗模式下Date.now()出现跳变显示的世界时间依然保持平滑递增不会出现明显回拨或跳秒。一个小改动能让 demo 从“能跑”变成“真机体验良好”。本文还有配套的精品资源点击获取