这份文档是基于您提供的 API 类源代码生成的完整中文开发指南。它涵盖了参数定义、接口逻辑说明及调用示例。

---

API 接口开发文档

1. 概述

API 类是一个用于获取民航核心数据的集成接口库。它主要负责与后端服务通信，提供航行通告（NOTAM）、气象数据（雷达、台风、火山灰）、跑道信息以及机场基础数据的查询功能。

核心特性：

• 请求取消：所有接口均支持传入 AbortSignal，允许调用者主动取消长时间未响应的请求。
• 智能解析：notam_data 接口支持自动从通告简码（如 A1234/23）中提取系列、编号和年份。
• 环境灵活：支持动态设置 BaseUrl 以切换测试与生产环境。

---

2. 基础配置

• 方法：setBaseUrl(baseUrl: string) 可用于修改请求域名。

---

3. 数据类型定义 (Parameter Types)

NotamListParams (通告列表参数)

用于可视化地图展示的通告筛选。

字段	类型	描述	默认值
pageNo	number	当前页码	1
pageSize	number	每页记录数	100
onlyGeojson	boolean	是否仅返回坐标数据	true
typeC	boolean	是否包含C类通告	true
isInternational	boolean	是否为国际通告	true
signal	AbortSignal	(可选) 取消请求的信号	-

NotamDetailParams (通告详情参数)

用于精确查询单条通告的文本内容。

字段	类型	描述
notamSeries	string	通告系列 (如 'A')
notamNoPart1	string	通告编号 (如 '0123')
notamNoPart2	string	通告年份 (如 '2024')
nof	string	发布机构代码 (NOF)

NotamDataParams (通告综合数据参数)

字段	类型	描述
notamCode	string	通告简码，支持格式如 "A1234/24"
itemA	string	地点指示信标 (四字码)
onlyValid	boolean	是否仅显示有效期内的数据
topic	string	主题分类，默认为 "official"

---

4. 接口方法说明

4.1 通告相关接口

notam_list(params)

• 描述：获取可视化通告列表，通常用于在地图上渲染通告要素。
• 返回值：Promise<Response>

notam_detail(params)

• 描述：通过系列号、编号、年份和NOF获取单条通告的详细信息。
• 返回值：Promise<Response>

notam_data(params)

• 描述：通告综合查询接口。
• 逻辑特性：该接口内置了正则解析。如果你传入了 notamCode（如 A0556/24），SDK 会自动将其拆解并赋值给 notamSeries、notamNoPart1 和 notamNoPart2，无需手动拆分。

4.2 气象与跑道接口

typhoon_volcano_ash(params)

• 描述：获取台风路径及火山灰云团的分析数据。

getRadarData(signal?)

• 描述：获取最新的雷达回波图列表（默认返回最近40条）。

getRunwayData(params)

• 描述：获取指定机场的跑道物理参数及可用性数据。

4.3 机场与地理数据

getAirportPoint(airport, signal?)

• 描述：这是一个复合接口。首先查询机场的地理中心点，随后自动调用索引接口获取该机场的详细空间数据。
• 返回参数描述：返回包含机场经纬度、标高、四字码等详细信息的 JSON 对象。

---

5. 调用案例

基础查询示例

import API from './api';

const api = new API();

// 1. 查询通告列表
api.notam_list({
  pageNo: 1,
  pageSize: 50,
  isInternational: true
}).then(res => res.json())
  .then(data => console.log("通告数据：", data));

// 2. 利用自动解析功能查询特定通告
api.notam_data({
  notamCode: "A0123/24", // SDK 会自动解析出系列A，编号0123，年份2024
  itemA: "ZSPD"
}).then(res => res.json());

超时与主动取消示例

如果用户切换了页面或请求时间过长，可以使用以下方式取消：

const controller = new AbortController();

api.getRadarData(controller.signal)
  .then(res => res.json())
  .catch(err => {
    if (err.name === 'AbortError') {
      console.log('请求已被用户主动取消');
    }
  });

// 5秒后如果还没响应，则取消请求
setTimeout(() => {
  controller.abort();
}, 5000);

---

6. 注意事项

1. 参数清理：SDK 内部会自动将空字符串 "" 转换为 null，以符合后端接口的过滤要求。
2. 错误处理：建议始终使用 .catch() 捕获网络错误。对于返回 Response 对象的接口，需调用 .json() 解析数据。
3. 跑道数据周期：getRunwayData 接口依赖于 GlobalConfigManager 中的周期设置，请确保在调用前全局配置已正确初始化。