浅念
87 lines
2.8 KiB
Dart
87 lines
2.8 KiB
Dart
/// 相册时区感知的时间展示（P3 计划 Task 4）。
|
||
///
|
||
/// 契约：startAt/endAt 按 UTC 存储，「展示按 timezone」。Dart 核心库无
|
||
/// IANA 时区数据库，引入 `timezone` 包（内嵌 tzdata）做墙钟换算，字符串
|
||
/// 格式化仍走 intl [DateFormat]（App 语言）。tzdata 初始化为幂等懒加载
|
||
/// （[ensureTzInitialized]），生产与测试共用同一路径。
|
||
library;
|
||
|
||
import 'package:intl/intl.dart';
|
||
import 'package:timezone/data/latest.dart' as tzdata;
|
||
import 'package:timezone/timezone.dart' as tz;
|
||
|
||
bool _tzInitialized = false;
|
||
|
||
/// 初始化内嵌 tzdata（幂等；首次调用后为空操作）。
|
||
void ensureTzInitialized() {
|
||
if (!_tzInitialized) {
|
||
tzdata.initializeTimeZones();
|
||
_tzInitialized = true;
|
||
}
|
||
}
|
||
|
||
/// 解析 IANA 时区名；无效返回 null。
|
||
///
|
||
/// 内嵌 tzdata（10 年窗口）不含 `UTC` 顶名（仅 `Etc/UTC`），此处将
|
||
/// `UTC` 归一化到 `Etc/UTC`，避免最常用的时区名被误判非法。
|
||
tz.Location? _resolveLocation(String timeZone) {
|
||
ensureTzInitialized();
|
||
final name = timeZone.trim();
|
||
try {
|
||
return tz.getLocation(name == 'UTC' ? 'Etc/UTC' : name);
|
||
} on Object {
|
||
return null;
|
||
}
|
||
}
|
||
|
||
/// UTC 瞬间 → 相册时区墙钟；IANA 名无效返回 null。
|
||
tz.TZDateTime? tryToAlbumZone(DateTime instant, String timeZone) {
|
||
final location = _resolveLocation(timeZone);
|
||
if (location == null) return null;
|
||
return tz.TZDateTime.from(instant.toUtc(), location);
|
||
}
|
||
|
||
/// 时区名是否为合法 IANA 标识（表单校验用）。
|
||
bool isValidTimezone(String timeZone) =>
|
||
timeZone.trim().isNotEmpty &&
|
||
tryToAlbumZone(DateTime.utc(2026, 1, 1), timeZone) != null;
|
||
|
||
/// 按相册时区格式化时间（`y/M/d HH:mm` 模式，App locale）。
|
||
///
|
||
/// 时区无效时回退 UTC 展示（表单校验另行拦截无效时区，此处仅兜底）。
|
||
String formatAlbumDateTime(
|
||
DateTime utcInstant,
|
||
String timeZone,
|
||
String locale,
|
||
) {
|
||
final zoned = tryToAlbumZone(utcInstant, timeZone) ?? utcInstant.toUtc();
|
||
return DateFormat('y/M/d HH:mm', locale).format(zoned);
|
||
}
|
||
|
||
/// 相册墙钟（表单里选择的日期时间，设备本地时区标记的 naive 值）→
|
||
/// UTC 瞬间（提交与回显往返一致）。
|
||
///
|
||
/// 时区无效时按字面值视为 UTC（校验先行拦截，避免设备时区偏移污染）。
|
||
DateTime albumWallClockToUtc(DateTime wallClock, String timeZone) {
|
||
final location = _resolveLocation(timeZone);
|
||
if (location == null) {
|
||
return DateTime.utc(
|
||
wallClock.year,
|
||
wallClock.month,
|
||
wallClock.day,
|
||
wallClock.hour,
|
||
wallClock.minute,
|
||
);
|
||
}
|
||
return tz
|
||
.TZDateTime(
|
||
location,
|
||
wallClock.year,
|
||
wallClock.month,
|
||
wallClock.day,
|
||
wallClock.hour,
|
||
wallClock.minute,
|
||
)
|
||
.toUtc();
|
||
}
|