简体中文、英文、多语言框架、时区、夏令时、公制/英制和区域配置

This commit is contained in:
mmc
2026-10-09 13:30:55 +08:00
parent 0bc900cb5b
commit 5afaf1de75
14 changed files with 595 additions and 23 deletions

View File

@@ -0,0 +1,171 @@
# 完善多语言与区域配置功能
## Context(背景)
本项目(机器人智慧服务系统)已具备基础 i18n 框架(i18next + react-i18next),支持简体中文(zh)和英文(en)切换,并有 `LanguageSwitcher` 组件和 antd ConfigProvider 的 locale 切换。但以下功能存在缺口:
- **时区**:`BasicSettings.tsx` 的时区选择器只有固定的 `UTC+08:00` 一个选项,无法选择其他时区;`Layout.tsx` 用 `new Date().toLocaleString()` 显示时间,依赖浏览器本地时区;`WayLinePage`/`RealTimeMonitor` 用 `Intl.DateTimeFormat().resolvedOptions().timeZone` 获取浏览器时区写入接口字段,用户无法手动配置。
- **夏令时(DST)**:固定偏移无法处理 DST,项目无任何 DST 逻辑。
- **公制/英制单位**:温度在 `DeviceOverviewPage.tsx`(L787,L989) 和 `DeviceStatusPage.tsx`(L1191-1195,L1310-1314) 硬编码为 `℃`,无英制(°F)转换;无距离/速度单位切换。
- **区域配置**:`userSlice` 只管理 token/userInfo/auth,无集中化的区域偏好(语言、时区、单位制)状态。
本次目标:搭建集中化的区域配置框架(preferencesSlice + dayjs 时区插件 + 单位换算工具 + 设置 UI),并接入关键展示点(顶部时钟、设备温度),让时区/DST/单位制可由用户配置并全局生效。**不包含**补全约 1070 个缺失翻译 key 和清理 69 个文件硬编码中文的工作。
## 实现方案
### 1. 新建 preferencesSlice — 区域偏好状态管理
**新文件**:`src/store/preferencesSlice.ts`
State 结构:
```ts
interface PreferencesState {
locale: 'zh' | 'en'; // 界面语言
timezone: string; // IANA 时区名,如 'Asia/Shanghai'
unitSystem: 'metric' | 'imperial'; // 单位制
dateFormat: 'YYYY-MM-DD HH:mm:ss' | 'YYYY-MM-DD HH:mm' | 'MM/DD/YYYY HH:mm:ss'; // 日期格式
}
```
- 初始化:从 `localStorage.preferences` 读取;无则用浏览器默认:locale 取 `i18nextLng`、timezone 取 `Intl.DateTimeFormat().resolvedOptions().timeZone`、unitSystem 按 locale 默认(zh→metric,en→metric,用户可手动切 imperial)
- Actions:`setLocale`、`setTimezone`、`setUnitSystem`、`setDateFormat`、`setPreferences`(批量)、`resetPreferences`
- 每次更新同步写回 `localStorage.preferences`
- 导出 selector hooks:`usePreferences()`、`useTimezone()`、`useUnitSystem()`
**修改文件**:`src/store/index.ts` — 注册 `preferences: preferencesReducer`,更新 `RootState` 类型。
### 2. dayjs 时区插件配置 — DST 自动处理
**新文件**:`src/lib/dayjs.ts`
- 导入并扩展 `dayjs/plugin/utc` 和 `dayjs/plugin/timezone`
- 导出配置好的 `dayjs` 实例
- 导出辅助函数:
- `formatInTz(date: Date|string, tz: string, format: string): string` — 在指定时区格式化时间,自动处理 DST
- `nowInTz(tz: string, format: string): string` — 当前时间在指定时区的格式化结果
- `getTimezoneOffsetLabel(tz: string): string` — 获取时区偏移标签如 `UTC+08:00`(用于显示)
- `isDST(tz: string): boolean` — 判断指定时区当前是否处于夏令时
- 导出常用 IANA 时区列表 `TIMEZONES`(覆盖主要地区:Asia/Shanghai、Asia/Tokyo、America/New_York、America/Los_Angeles、Europe/London、Europe/Paris、Australia/Sydney 等,约 30-40 个)
### 3. 单位换算工具 — 公制/英制转换
**新文件**:`src/lib/units.ts`
- `celsiusToFahrenheit(c: number): number` — ℃→°F
- `fahrenheitToCelsius(f: number): number` — °F→℃
- `kmToMile(km: number): number` — km→mile
- `mileToKm(mi: number): number`
- `kmhToMph(kmh: number): number`
- `formatTemperature(celsius: number, unitSystem: 'metric'|'imperial', digits=1): { value: number; unit: '℃'|'°F'; label: string }` — 根据单位制格式化温度,返回数值+单位
- `formatDistance(km: number, unitSystem): { value: number; unit: 'km'|'mi' }`
- `formatSpeed(kmh: number, unitSystem): { value: number; unit: 'km/h'|'mph' }`
- React hook `useUnitFormatter()` — 从 preferencesSlice 读取 unitSystem,返回绑定好的格式化函数
### 4. i18n 集成 — 翻译 key 补充 + 语言联动
**修改文件**:`src/locales/zh/index.ts` 和 `src/locales/en/index.ts`
在 `systemSetting` 命名空间下新增翻译 key(zh/en 各一份):
```
unitSystem: '单位制' / 'Unit System'
metric: '公制' / 'Metric'
imperial: '英制' / 'Imperial'
timezoneSelect: '时区选择' / 'Timezone'
daylightSavingTime: '夏令时' / 'Daylight Saving Time'
dstActive: '当前处于夏令时' / 'DST Active'
dstInactive: '当前非夏令时' / 'DST Inactive'
dateFormat: '日期格式' / 'Date Format'
regionalSettings: '区域配置' / 'Regional Settings'
unitCelsius: '摄氏度' / 'Celsius'
unitFahrenheit: '华氏度' / 'Fahrenheit'
```
**修改文件**:`src/i18n/index.ts` — 不改动核心配置,但在 App 层监听 preferencesSlice.locale 变化时调用 `i18n.changeLanguage`。
### 5. 设置 UI — 扩展 BasicSettings 区域配置面板
**修改文件**:`src/components/SystemSetting/BasicSettings.tsx`
在现有"默认语言""时区""默认首页"区域(L234-245)进行改造:
- **时区选择器**:从单一 `UTC+08:00` 替换为完整 IANA 时区下拉列表(使用 `TIMEZONES`),选项显示 `时区名 (UTC偏移)`,选中后写入 `preferencesSlice.timezone`
- **单位制切换**:新增 `Radio.Group`(公制/英制),写入 `preferencesSlice.unitSystem`
- **DST 指示器**:在时区选择旁显示当前时区是否处于夏令时(用 `isDST()` 判断,显示绿/灰标签)
- **日期格式选择**:新增日期格式下拉
- 所有变更通过 `dispatch(setXxx(...))` 写入 store,立即生效并持久化
### 6. 接入展示点 — 让区域配置全局生效
#### 6.1 顶部时钟(Layout.tsx)
**修改文件**:`src/components/Layout.tsx`
- `useState(new Date().toLocaleString())` → 改为读取 `preferencesSlice.timezone` + `dateFormat`,用 `nowInTz(tz, fmt)` 格式化
- `setInterval` 回调改为调用 `nowInTz`
- 时区变化时自动重格式化(useEffect 依赖 timezone)
#### 6.2 设备温度展示(DeviceOverviewPage.tsx + DeviceStatusPage.tsx)
**修改文件**:
- `src/components/devices/DeviceOverviewPage.tsx`(L787, L989)
- `src/components/devices/DeviceStatusPage.tsx`(L1191-1195, L1310-1314)
将硬编码 `℃` 替换为 `useUnitFormatter().formatTemperature(celsius)` 返回的 `{value}{unit}`,根据 unitSystem 自动切换 ℃/°F。
#### 6.3 接口时区字段(WayLinePage.tsx + RealTimeMonitor.tsx)
**修改文件**:
- `src/components/devices/WayLinePage.tsx`(L328, L392, L690)
- `src/pages/RealTimeMonitor.tsx`(L692)
将 `Intl.DateTimeFormat().resolvedOptions().timeZone` 替换为读取 `preferencesSlice.timezone`,优先用用户配置的时区。
#### 6.4 语言联动
**修改文件**:`src/components/LanguageSwitcher.tsx`(或新建 hook)
- 切换语言时同步 `dispatch(setLocale(key))`,确保 preferencesSlice 与 i18n 一致
- App 启动时从 preferencesSlice 初始化 i18n 语言
### 7. 类型定义
**修改文件**:`src/store/types.ts`(如存在)或 `preferencesSlice.ts` 内联
- 导出 `PreferencesState`、`UnitSystem`、`Locale` 类型
## 关键文件清单
| 文件 | 操作 | 说明 |
|------|------|------|
| `src/store/preferencesSlice.ts` | 新建 | 区域偏好状态管理 |
| `src/store/index.ts` | 修改 | 注册 preferencesReducer |
| `src/lib/dayjs.ts` | 新建 | dayjs 时区插件 + 辅助函数 |
| `src/lib/units.ts` | 新建 | 公制/英制单位换算 |
| `src/locales/zh/index.ts` | 修改 | 新增区域配置翻译 key |
| `src/locales/en/index.ts` | 修改 | 新增区域配置翻译 key |
| `src/components/SystemSetting/BasicSettings.tsx` | 修改 | 时区/单位/DST 设置 UI |
| `src/components/Layout.tsx` | 修改 | 顶部时钟时区感知 |
| `src/components/devices/DeviceOverviewPage.tsx` | 修改 | 温度单位制适配 |
| `src/components/devices/DeviceStatusPage.tsx` | 修改 | 温度单位制适配 |
| `src/components/devices/WayLinePage.tsx` | 修改 | 接口时区字段用配置值 |
| `src/pages/RealTimeMonitor.tsx` | 修改 | 接口时区字段用配置值 |
| `src/components/LanguageSwitcher.tsx` | 修改 | 语言切换同步 preferencesSlice |
## 复用现有代码
- 复用 `src/i18n/index.ts` 的 i18next 实例,不重建
- 复用 `src/store/index.ts` 的 `configureStore` 模式(参考 userSlice/stationSlice 的 localStorage 持久化模式)
- 复用 `src/lib/utils.ts` 中已有的 `fix2` 数字格式化函数(温度展示中已使用)
- 复用 antd 的 `Select`、`Radio`、`Tag` 组件(BasicSettings 已大量使用)
- dayjs 已作为 antd 的传递依赖可用,仅需在项目中显式 `import dayjs from 'dayjs'` 并扩展插件(UTC/Timezone 插件随 dayjs 包内置,无需额外安装)
## 验证方案
1. **启动开发服务器**:`npm run dev`(vite --port=3001)
2. **语言切换**:点击右上角 LanguageSwitcher 切换中/英文,验证所有新 UI 文案正确切换
3. **时区配置**:进入系统设置 → 区域配置,选择不同时区(如 America/New_York),验证:
- 顶部时钟立即切换为纽约时间
- 切换到 Europe/Paris 并验证夏令时标签正确显示(10 月欧洲仍在 DST 内)
4. **单位制切换**:在设置中切换英制,进入设备概览/设备状态页,验证温度从 `℃` 变为 `°F` 且数值正确(如 25℃ → 77.0°F)
5. **持久化**:刷新页面,验证语言/时区/单位制设置从 localStorage 恢复
6. **类型检查**:`npm run lint`(tsc --noEmit)无类型错误
7. **DST 验证**:选择 America/New_York(EST/EDT),验证当前(10 月仍在 EDT)显示 DST Active;选择 Asia/Shanghai 验证显示 DST Inactive
## 注意事项
- dayjs 的 UTC/Timezone 插件随 dayjs npm 包内置(`dayjs/plugin/utc`、`dayjs/plugin/timezone`),无需额外安装依赖
- dayjs 目前是 antd 的传递依赖,项目中已有多处直接 `import dayjs from 'dayjs'`,可安全使用
- 不改动 i18n 核心配置文件 `src/i18n/index.ts` 的 resources 结构,仅新增翻译 key
- 温度数据来源是设备上报的摄氏度原始值,转换在前端完成,不涉及后端改动