tds-map-methods 0.1.0 → 0.1.2

package/README.md

@@ -1,21 +1,400 @@
 # tds-map-methods
 
-可复用的 TDS 地图方法库，支持 ESM 和 CommonJS。
+面向浏览器应用的 TDS / OpenLayers 地图渲染工具包，提供气象栅格、等值线、风场、WMS、台风路径和 TDS 数据请求能力。
+
+## 功能特性
+
+- 初始化 OpenLayers 地图并统一管理业务图层
+- 支持色斑图、网格值、等值线、风场、风羽、WMS、MICAPS 和台风路径
+- 支持图层加载、更新、显隐、移除和经纬度取值
+- 内置 TDS 目录、NCSS、XML、图片及台风数据请求方法
+- 提供 ESM、CommonJS 和完整 TypeScript 类型声明
 
 ## 安装
 
-```sh
+~~~bash
 npm install tds-map-methods ol @turf/turf dayjs d3-contour lodash-es
-```
+~~~
+
+也可以使用 pnpm：
+
+~~~bash
+pnpm add tds-map-methods ol @turf/turf dayjs d3-contour lodash-es
+~~~
+
+## 必要引入
+
+在宿主项目的入口文件中引入 OpenLayers 样式。npm 包不会自动注入全局 CSS：
+
+~~~ts
+import "ol/ol.css";
+~~~
+
+然后根据实际功能从包中引入方法。初始化地图至少需要引入 `initMap`；如需设置服务地址，同时引入 `configureMapMethods`：
+
+~~~ts
+import { configureMapMethods, initMap } from "tds-map-methods";
+~~~
+
+加载和管理业务图层时，通常需要以下方法：
+
+~~~ts
+import {
+  clearAllLayers,
+  getValueByLonLat,
+  initMap,
+  loadLayer,
+  removeLayerById,
+  toggleVisibleById,
+  updateLayer,
+} from "tds-map-methods";
+~~~
+
+如果使用 TypeScript，可以按需引入 OpenLayers 的地图类型：
+
+~~~ts
+import type { Map } from "ol";
+~~~
+
+注意：`ol`、`@turf/turf`、`dayjs`、`d3-contour` 和 `lodash-es` 是 peer dependencies，必须安装在宿主项目中，但通常不需要在业务文件中手动逐个 `import`。
+
+## 快速开始
+
+页面中需要准备一个具有明确宽高的地图容器：
+
+~~~html
+<div id="map" style="width: 100%; height: 600px"></div>
+~~~
+
+初始化配置并创建地图：
+
+~~~ts
+import { configureMapMethods, initMap, loadLayer } from "tds-map-methods";
+
+configureMapMethods({
+  serviceBaseUrl: "/server",
+  serviceAuthorization: "Basic ...",
+  ncssBaseUrl: "/ncss/grid",
+  requestTimeout: 60_000,
+  imageSize: 2048,
+  typhoonServiceBaseUrl: "/typhoon-server",
+});
+
+const map = await initMap("map", {
+  center: [118.8, 32.1],
+  zoom: 5,
+});
+
+loadLayer(map, {
+  id: "temperature",
+  title: "温度",
+  label: "Temperature",
+  type: "gradual",
+  filePath: "/data/temperature.nc",
+  show: true,
+  config: {
+    extent: [70, 15, 140, 55],
+    mode: "gradient",
+    legendType: "gradual",
+    legend: [
+      { name: "低温", scope: [-40, 0], color: "#3b82f6" },
+      { name: "适中", scope: [0, 25], color: "#22c55e" },
+      { name: "高温", scope: [25, 50], color: "#ef4444" },
+    ],
+    opacity: 0.85,
+    zIndex: 10,
+  },
+});
+~~~
+
+也可以在初始化地图时传入运行配置：
+
+~~~ts
+const map = await initMap("map", {
+  center: [118.8, 32.1],
+  zoom: 5,
+  mapMethodsConfig: {
+    serviceBaseUrl: "/server",
+    ncssBaseUrl: "/ncss/grid",
+  },
+});
+~~~
+
+## 全局配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `serviceBaseUrl` | `string` | `""` | WMS 和 TDS 请求的服务前缀 |
+| `serviceAuthorization` | `string` | `""` | TDS 请求默认 Authorization 请求头 |
+| `ncssBaseUrl` | `string` | `"/ncss/grid"` | NCSS `dataset.xml` 请求前缀 |
+| `requestTimeout` | `number` | `60000` | 请求超时时间，单位毫秒 |
+| `imageSize` | `number` | `2048` | 源图片请求的最大宽高 |
+| `typhoonServiceBaseUrl` | `string` | `serviceBaseUrl` | 台风 JSON 服务前缀 |
+| `typhoonDataPath` | `string` | `data/script/mdp_typhoon/output` | 台风数据目录 |
+| `typhoonAuthorization` | `string` | `""` | 台风请求 Authorization 请求头 |
+
+配置相关方法：
+
+~~~ts
+import {
+  configureMapMethods,
+  getMapMethodsConfig,
+  resetMapMethodsConfig,
+} from "tds-map-methods";
+~~~
+
+## 支持的图层类型
+
+`loadLayer` 的 `type` 可传单个字符串或字符串数组。
+
+| 类型 | 用途 |
+| --- | --- |
+| `gradual` | 栅格色斑图 |
+| `grid` | 网格数值 |
+| `isoline` / `contour` | 等值线或等值面 |
+| `uv` | U/V 风场 |
+| `windShaft` | 风羽图 |
+| `arrow` | 箭头图层 |
+| `micaps` | MICAPS 数据图层 |
+| `wms` | WMS 图层 |
+| `typhoon` | 台风路径图层 |
+
+组合类型示例：
+
+~~~ts
+loadLayer(map, {
+  ...layerOptions,
+  type: ["uv", "grid", "windShaft"],
+});
+~~~
+
+## 图层管理
+
+~~~ts
+import {
+  clearAllLayers,
+  getLoadedLayerOptions,
+  getValueByLonLat,
+  removeLayerById,
+  toggleVisibleById,
+  updateLayer,
+  updateWmsLayerColor,
+} from "tds-map-methods";
+
+toggleVisibleById("temperature", false);
+
+const currentLayer = getLoadedLayerOptions().find(
+  (item) => item.id === "temperature",
+);
+if (currentLayer) {
+  updateLayer({ ...currentLayer, time: "2026-10-27T00:00:00Z" });
+}
+
+const value = await getValueByLonLat(map, "temperature", 118.8, 32.1);
+console.log(value);
+
+removeLayerById("temperature");
+clearAllLayers();
+~~~
+
+常用图层方法：
+
+| 方法 | 说明 |
+| --- | --- |
+| `loadLayer(map, options)` | 加载业务图层 |
+| `updateLayer(options)` | 使用相同 `id` 更新图层参数 |
+| `toggleVisibleById(id, visible)` | 控制业务图层显隐 |
+| `removeLayerById(id)` | 删除指定业务图层 |
+| `clearAllLayers()` | 清空全部业务图层 |
+| `getLoadedLayerOptions()` | 获取已加载图层的配置 |
+| `getValueByLonLat(map, id, lon, lat, smooth?)` | 查询指定经纬度的栅格值 |
+| `updateWmsLayerColor(id, options)` | 更新 WMS 色带参数 |
+
+## 绘制方法说明
+
+### 推荐方式：通过 `loadLayer` 绘制
+
+业务项目优先使用 `loadLayer(map, options)`。它会根据 `options.type` 自动选择对应绘制实现，并将图层加入统一管理列表，使 `updateLayer`、`removeLayerById` 和 `toggleVisibleById` 可以正常工作。
+
+~~~ts
+loadLayer(map, {
+  id: "temperature",
+  title: "温度",
+  label: "Temperature",
+  type: "isoline",
+  filePath: "/data/temperature.nc",
+  config: {
+    extent: [70, 15, 140, 55],
+    mode: "discrete",
+    legendType: "legend",
+    legend: [
+      { name: "0℃", scope: [0], color: "#3b82f6" },
+      { name: "10℃", scope: [10], color: "#22c55e" },
+      { name: "20℃", scope: [20], color: "#ef4444" },
+    ],
+    showIsolineValue: true,
+    isolineSmoothness: 1,
+  },
+});
+~~~
+
+### 底层绘制方法
+
+底层方法适合需要自行控制数据地址、缓存、预加载或中断请求的场景。直接调用底层方法创建的图层不会完整进入 `loadLayer` 的统一管理流程，应使用对应的删除方法进行清理。
+
+| 方法 | 用途 | 必要参数与注意事项 |
+| --- | --- | --- |
+| `createIsoline(map, options)` | 从栅格数据生成等值线或等值面 | 必须提供 `id`、`url`、`config.legend`；支持 `authorization` 和 `AbortSignal` |
+| `preloadIsoline(options, timeList)` | 提前生成多个时次的等值线缓存 | `timeList` 应与实际数据时次一致，适合播放动画前预加载 |
+| `addIsolineLayer(options)` | 将已经生成的等值线 GeoJSON 加到地图 | 适用于调用方已经持有几何数据的高级场景 |
+| `toggleIsolineLayer(map, id, visible)` | 控制底层等值线图层显隐 | `id` 必须与创建时保持一致 |
+| `removeIsolineLayer(map, id)` | 删除底层等值线图层并使未完成请求失效 | 直接调用 `createIsoline` 时应使用此方法删除 |
+| `createMicContour(map, options)` | 请求并解析 MICAPS 文件，绘制等值线、填色和符号 | 必须提供 `className`、`filePath`；支持授权和请求取消 |
+| `removeMicContour(map, className)` | 删除同一 MICAPS 数据集创建的全部图层 | `className` 必须与创建时一致 |
+| `renderFcstCanvasByWebGPU(options)` | 将二维栅格数组渲染为 `HTMLCanvasElement` | 需要宽高、原始/平滑数组、阈值和 RGBA 色表；自动按 WebGL2、WebGPU、Canvas2D 顺序降级 |
+
+直接生成等值线示例：
+
+~~~ts
+import { createIsoline, removeIsolineLayer } from "tds-map-methods";
+
+const controller = new AbortController();
+
+await createIsoline(map, {
+  id: "temperature-isoline",
+  url: "/server/path/to/grid-image",
+  authorization: "Basic ...",
+  signal: controller.signal,
+  config: {
+    legend: [
+      { name: "0℃", scope: [0], color: "#3b82f6" },
+      { name: "10℃", scope: [10], color: "#22c55e" },
+      { name: "20℃", scope: [20], color: "#ef4444" },
+    ],
+    isolineSmooth: true,
+    isolineSmoothness: 1,
+    showIsolineValue: true,
+  },
+});
+
+// 取消尚未完成的请求。
+controller.abort();
+
+// 删除直接创建的等值线图层。
+removeIsolineLayer(map, "temperature-isoline");
+~~~
+
+MICAPS 绘制示例：
+
+~~~ts
+import { createMicContour, removeMicContour } from "tds-map-methods";
+
+await createMicContour(map, {
+  className: "micaps-weather",
+  filePath: "/server/path/to/micaps.txt",
+  showText: true,
+  showFillcolor: true,
+  showIsoline: true,
+  showPointMarkers: true,
+});
+
+removeMicContour(map, "micaps-weather");
+~~~
+
+## TDS 数据请求
+
+包内请求方法基于浏览器 `fetch`，支持 Authorization、超时和 `AbortSignal`。
+
+~~~ts
+import {
+  fetchTdsGet,
+  fetchXMLFromUrl,
+  getMenuList,
+  getVariableMinMax,
+  getXmlData,
+  resolveLayerLoadOptions,
+} from "tds-map-methods";
+
+const menu = await getMenuList("/catalog.xml");
+
+const dataset = await getXmlData({
+  filePath: "/data/temperature.nc",
+});
+
+const range = await getVariableMinMax(
+  "/data/temperature.nc",
+  "Temperature",
+  { north: 55, south: 15, east: 140, west: 70 },
+);
+~~~
+
+其他请求方法包括 `fetchTdsResponse`、`fetchXmlData`、`fetchTxtOrJson`、`fetchExcel`、`fetchImageBase64` 和 `fetchTdsImageBase64`。
+
+### 接口方法说明
+
+| 方法 | 返回值 | 主要用途 |
+| --- | --- | --- |
+| `fetchTdsResponse(url, options)` | `Promise<Response>` | 校验 HTTP 状态后返回原始响应，适合调用方自行读取响应内容 |
+| `fetchTdsGet<T>(url, params, authorization, options)` | `Promise<T>` | 发起带查询参数的 GET 请求，可通过 `responseType` 指定返回类型 |
+| `fetchXMLFromUrl(url, authorization, options)` | `Promise<string>` | 获取 XML 文本 |
+| `fetchTxtOrJson(url, params, authorization, options)` | `Promise<string>` | 获取文本或 JSON 字符串 |
+| `fetchExcel(url, authorization, options)` | `Promise<ArrayBuffer>` | 下载 Excel 等二进制文件 |
+| `fetchImageBase64(...)` | `Promise<string>` | 获取图片并转换为 Base64/Data URL |
+| `getMenuList(url, authorization, options)` | 菜单类型及目录项数组 | 读取 TDS catalog 目录 |
+| `getXmlData(options)` | 数据范围、时次及文件列表 | 读取 NCSS `dataset.xml` 元数据 |
+| `getVariableMinMax(...)` | `{ min, max }` | 查询指定变量、范围和时次的最小值与最大值 |
+| `resolveLayerLoadOptions(menu, options)` | `Layer.Config \| null` | 将菜单配置补全为可传给 `loadLayer` 的图层配置 |
+| `getTyphoonList(options)` | 台风列表 | 获取可用台风编号和基础信息 |
+| `getTyphoonDetail(number, options)` | 台风详情 | 获取实况与预报路径点 |
+
+接口配置优先级通常为：本次方法参数或图层参数 → `configureMapMethods` 全局配置 → 包内默认值。需要取消页面卸载或条件变化时的请求，可以传入 `AbortSignal`：
+
+~~~ts
+const controller = new AbortController();
+
+const request = getXmlData({
+  filePath: "/data/temperature.nc",
+  signal: controller.signal,
+});
+
+// 页面卸载或条件发生变化时取消。
+controller.abort();
+
+try {
+  await request;
+} catch (error) {
+  if (error instanceof DOMException && error.name === "AbortError") {
+    // 请求被主动取消。
+  } else {
+    throw error;
+  }
+}
+~~~
+
+请求失败、超时或响应状态异常时，Promise 会被拒绝。业务代码应根据需要使用 `try/catch`，并在组件卸载时取消不再使用的请求。
+
+## 台风数据
+
+~~~ts
+import { getTyphoonDetail, getTyphoonList } from "tds-map-methods";
+
+const list = await getTyphoonList();
+const detail = await getTyphoonDetail(list[0].num_nati);
+~~~
+
+台风请求可单独覆盖 `serviceBaseUrl`、`dataPath`、`authorization` 和 `signal`。
 
-## 使用
+## CommonJS
 
-```ts
-import { initMap, loadLayer, removeLayerById } from "tds-map-methods";
+~~~js
+const { initMap, loadLayer } = require("tds-map-methods");
+~~~
 
-const map = await initMap("map", { center: [118.8, 32.1], zoom: 5 });
-loadLayer(map, layerOptions);
-removeLayerById(layerOptions.id);
-```
+## 使用注意
 
-依赖 OpenLayers 浏览器运行环境。方法中的数据地址、鉴权和图像尺寸通过传入的图层配置或宿主应用环境提供。
+- 本包用于浏览器环境，依赖 DOM、Canvas、WebGL / WebGPU 和 OpenLayers。
+- 调用 `initMap` 前，地图容器必须已挂载并具有非零宽高。
+- 本包不会读取宿主项目的 Vite 环境变量，请通过 `configureMapMethods` 显式传入服务地址。
+- 跨域请求需要服务端正确配置 CORS；Authorization 请求头也必须被服务端允许。
+- `Layer.Config`、台风数据和请求方法均提供 TypeScript 类型提示。
+- `ol`、`@turf/turf`、`dayjs`、`d3-contour` 和 `lodash-es` 为 peer dependencies，需要由宿主项目安装。