道

气象是地球系统中最基础、最连续的自然观测要素之一。大气中的温度、湿度、降水、风场等要素，以小时为粒度、以经纬网格为尺度，持续记录着地球表层环境的演变轨迹。这些看似枯燥的数值序列，实际上是人类理解气候变迁、评估极端事件、规划生产生活的最原始证据。

历史气象数据的存在，使得"过去某地某时的天气如何"这一问题可以从主观记忆转化为可量化的事实。将空间坐标与时间轴交会，在网格化数据中回溯任意位置的气象历史，本质上是打破了人类感知的时空局限——让任何人在任何时刻，都能以统一的尺度审视地球任意角落曾经发生过的自然过程。这种能力对于农业决策、灾害回溯、工程设计和学术研究而言，是不可或缺的基础信息支撑。

法

历史气象数据的获取与分析，遵循"定位—定段—定项—检索—解析—呈现"的六步方法论。

步骤一：确定查询位置

气象数据天然与地理位置绑定。查询的起点是明确目标地点的经纬度坐标。经度的有效范围为 -180 到 180，纬度的有效范围为 -90 到 90。坐标精度直接影响数据匹配的准确性——系统会将输入坐标匹配到最近的气象网格点上，因此输入坐标与实际目标越接近，返回的数据越能反映目标位置的真实状况。

步骤二：设定时间范围

确定一个起止日期，界定所需数据的时间跨度。起始日期不得晚于结束日期，且时间跨度通常需要控制在一定范围内。合理的时间范围既保证数据量可处理，也避免因数据量过大导致响应缓慢或超出服务限制。选择起止日期时应注意：起始日期的 00:00 到结束日期的 23:00 之间的所有逐小时数据均会被包含。

步骤三：选择气象变量

气象变量种类繁多，各有其物理含义和度量单位。常见的变量包括：近地面气温（摄氏度）、相对湿度（百分比）、降水量（毫米）、降雨量（毫米）、降雪量（厘米）、风速（千米/小时）、风向（角度）、云量（百分比）、海平面气压（百帕）和太阳短波辐射（瓦/平方米）。用户应根据分析目的筛选相关变量，避免请求无关数据造成冗余。可同时选择多个变量进行综合对比分析。

步骤四：构造查询请求

将位置坐标、时间范围、变量列表组合为标准化的请求参数。这些参数以键值对形式拼接，通过通用网络协议发送至数据服务端点。请求方式为单向获取（读取操作），服务器无需验证身份即可返回公开数据。时区参数可指定，以便返回的时间序列符合目标时区的日期划分。

步骤五：解析响应数据

服务端返回的结构化数据包含：实际匹配的网格点坐标、海拔高度、时区偏移信息，以及按时间轴排列的变量数值数组。逐小时数据以等间距时间序列呈现，每个变量对应一个等长数组，索引位置与时间数组一一对应。解析时应校验返回数据的完整性，确认时间数组长度与各变量数组长度一致。

步骤六：可视化与导出

将数值序列转化为统计图表，通过折线图展示时间趋势，通过柱状图展示周期累计量。图表应支持缩放、悬停提示等交互。同时支持将完整响应数据导出为结构化文件，供下游分析工具二次处理。

设计原则

• 输入校验优先：在发起请求之前，对所有输入参数进行合法性检查，包括坐标范围、日期逻辑、变量非空等，尽早拦截无效请求。
• 用户反馈闭环：每次操作（查询中、成功、失败）均应有明确的状态反馈，错误信息应语义清晰，帮助用户定位问题。
• 数据可复现：查询结果应包含完整的请求上下文（位置、时间、参数），确保历史查询可追溯、可复现。

术

本项目在数据处理和可视化环节使用了三个构建工具提供的软件包。

echarts

• 用途：数据可视化图表渲染。将时间序列气象数据绘制为折线图、柱状图等形式，支持交互式缩放、悬停提示、动态主题切换。
• 官网：https://echarts.apache.org/
• npm：https://www.npmjs.com/package/echarts

图表实例的初始化与生命周期管理通过封装后的组合函数实现，核心逻辑如下：

// 初始化图表实例（来自 useECharts.ts）
chartInstance = echarts.init(chartContainer.value)

// 设置图表配置
chartInstance.setOption(option, true)

// 窗口大小变化时自适应
chartInstance.resize()

// 销毁实例释放资源
chartInstance.dispose()

图表配置采用工厂函数模式，每种图表类型对应一个生成函数，根据传入的天气数据和主题色彩动态生成配置对象。以气温趋势图为例：

// 气温折线图配置生成（来自 weatherHistoryChart.ts）
export function generateTemperatureChart(
  data: WeatherApiResponse,
  theme: ChartThemeColors
): EChartsOption {
  const hourly = data.hourly
  if (!hourly?.time || !hourly.temperature_2m) {
    return {}
  }
  return {
    xAxis: {
      type: 'category',
      boundaryGap: false,
      data: hourly.time.map((t) => t.substring(0, 16).replace('T', ' ')),
    },
    yAxis: { type: 'value', name: '温度 (°C)' },
    series: [{
      name: '气温',
      type: 'line',
      data: hourly.temperature_2m,
      smooth: true,
      areaStyle: {
        color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
          { offset: 0, color: oklchToHex(theme.primary) + '40' },
          { offset: 1, color: oklchToHex(theme.primary) + '05' },
        ]),
      },
    }],
  }
}

设计中采用了渐变色域填充（areaStyle + LinearGradient），使折线下方呈现由浓到淡的颜色过渡，增强视觉层次感。主题色彩通过 oklch 色彩空间传入后转换为十六进制格式，确保图表配色与界面主题协调一致。

@vuepic/vue-datepicker

• 用途：日期选择交互组件。提供日历面板供用户直观选择起止日期，支持日期范围约束、国际化本地化显示。
• npm：https://www.npmjs.com/package/@vuepic/vue-datepicker

核心配置：

// 日期选择器配置（来自 WeatherHistoryPage.vue script 部分）
:time-config="{ enableTimePicker: false }"
:min-date="minDate"
:max-date="endDateModel || today"
model-type="yyyy-MM-dd"
:formats="{ input: 'yyyy-MM-dd', preview: 'yyyy/MM/dd' }"
:year-first="true"
:clearable="false"
:locale="zhCN"
placeholder="选择开始日期"

关键设计要点：

• 仅启用日期选择（enableTimePicker: false），不涉及时分秒，符合历史天气按天查询的场景。
• 起始日期和结束日期相互联动约束：开始日期不超过结束日期，结束日期不早于开始日期，且均不超过当天。
• 使用 yyyy-MM-dd 格式输出日期字符串，与 API 的日期参数格式保持一致。
• 通过 zhCN 本地化对象实现中文界面，该对象由 date-fns 提供。

date-fns

• 用途：日期处理工具库，提供本地化语言包。用于将日期选择器的界面文本（月份、星期、按钮标签等）转换为中文显示。
• npm：https://www.npmjs.com/package/date-fns
• 官网：https://date-fns.org/

// 导入中文本地化对象（来自 WeatherHistoryPage.vue）
import { zhCN } from 'date-fns/locale'

技术架构与数据流

数据在系统中的流转路径如下：

1. 用户通过日期选择器组件选定起止日期，输入经纬度坐标。
2. 日期字符串经由内联函数 toDateString 格式化，确保输出格式与 API 要求一致（yyyy-MM-dd）。
3. 表单验证层检查坐标范围（-180 到 180、-90 到 90）、日期逻辑（起始 <= 结束）、日期跨度（1 到 365 天）、变量非空。
4. 验证通过后，构建 URLSearchParams 对象，将经纬度、起止日期、选中的变量列表（逗号拼接）、固定每日变量、时区信息组装为查询字符串。
5. 通过浏览器原生网络请求接口将参数发送至历史天气数据 API 端点。
6. 响应数据经类型校验后传入图表工厂，根据用户选择的图表类型调用对应的配置生成函数。
7. echarts 实例接收配置对象，渲染图表到页面容器。
8. 响应数据同时支持导出为 JSON 文件，通过 Blob 和 Object URL 实现浏览器端文件下载。