tds-map-methods 0.1.1 → 0.1.3

package/README.md

@@ -1,31 +1,675 @@
 # tds-map-methods
 
-Reusable TDS/OpenLayers rendering methods for browser applications.
+面向浏览器应用的 TDS / OpenLayers 地图渲染工具包，提供气象栅格、等值线、风场、WMS、台风路径和 TDS 数据请求能力。
 
-## Install
+## 功能特性
 
-```sh
+- 初始化 OpenLayers 地图并统一管理业务图层
+- 支持色斑图、网格值、等值线、风场、风羽、WMS、MICAPS 和台风路径
+- 支持图层加载、更新、显隐、移除和经纬度取值
+- 内置 TDS 目录、NCSS、XML、图片及台风数据请求方法
+- 提供 ESM、CommonJS 和完整 TypeScript 类型声明
+
+## 安装
+
+~~~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`。
+
+## 快速开始
 
-## Configure and use
+页面中需要准备一个具有明确宽高的地图容器：
 
-```ts
+~~~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 });
+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"],
+});
+~~~
+
+## 图层参数配置
+
+<code>loadLayer</code> 的第二个参数是 <code>Layer.Config</code>。建议先配置公共字段，再根据图层类型补充 <code>config</code> 下的专用字段。
+
+### 顶层参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| <code>id</code> | <code>string</code> | 是 | 图层唯一标识；更新、显隐和删除都依赖它 |
+| <code>title</code> | <code>string</code> | 是 | 图层标题，供业务菜单或图例使用 |
+| <code>label</code> | <code>string</code> | 是 | 图层显示标签 |
+| <code>type</code> | <code>LegendType</code> 或数组 | 是 | <code>gradual</code>、<code>grid</code>、<code>isoline</code>、<code>uv</code>、<code>wms</code> 等 |
+| <code>filePath</code> | <code>string</code> | 是 | TDS 数据目录或文件路径 |
+| <code>fallbackFilePath</code> | <code>string</code> | 否 | 主目录不可用时使用的备用目录 |
+| <code>url</code> | <code>string</code> | 否 | 直接数据地址或已经解析出的数据集 URL |
+| <code>serviceBaseUrl</code> | <code>string</code> | 否 | 仅覆盖当前图层的全局服务前缀 |
+| <code>show</code> | <code>boolean</code> | 否 | 初始是否显示，默认显示 |
+| <code>icon</code> | <code>string</code> | 否 | 业务菜单图标名称 |
+| <code>fileListType</code> | <code>file</code> 或 <code>menu</code> | 否 | 目录节点类型 |
+| <code>unit</code> | <code>string</code> | 否 | 数据单位 |
+| <code>authorization</code> | <code>string</code> | 否 | 当前图层请求使用的 Authorization |
+| <code>fallbackAuthorization</code> | <code>string</code> | 否 | 备用目录请求使用的 Authorization |
+| <code>time</code> | <code>string</code> 或 <code>Dayjs</code> | 否 | 请求的数据时次 |
+| <code>config</code> | <code>object</code> | 是 | 范围、图例、渲染模式和类型专用配置 |
+
+<code>serviceBaseUrl</code> 和 <code>authorization</code> 的优先级通常是：图层字段或本次请求参数 → 全局 <code>configureMapMethods</code> 配置 → 默认值。
+
+### config 通用参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>extent</code> | <code>[west, south, east, north]</code> | 数据经纬度范围，使用 EPSG:4326 顺序 |
+| <code>mode</code> | <code>discrete</code>、<code>gradient</code>、<code>grid</code> | 离散色带、渐变色带或网格模式 |
+| <code>legend</code> | <code>LegendItem[]</code> | 色带配置；每项包含 <code>name</code>、<code>scope</code> 和 <code>color</code> |
+| <code>legendType</code> | <code>visible</code>、<code>legend</code>、<code>grid</code>、<code>gradual</code> | 图例显示方式 |
+| <code>legendScope</code> | <code>[]</code> 或 <code>[start, end]</code> | 按图例下标选择范围，采用左闭右开区间；空数组表示不限制 |
+| <code>scope</code> | <code>[min, max]</code> | 数据值域；不设置时通常从 TDS 自动获取 |
+| <code>zIndex</code> | <code>number</code> | 图层层级，值越大越靠上 |
+| <code>opacity</code> | <code>number</code> | 透明度，范围 0 到 1 |
+| <code>lineWidth</code> | <code>number</code> | 等值线宽度 |
+| <code>isolineLineWidth</code> | <code>number</code> | 等值线宽度，优先于 <code>lineWidth</code> |
+| <code>isolineSmooth</code> | <code>boolean</code> | 是否平滑等值线，默认开启 |
+| <code>isolineSmoothness</code> | <code>number</code> | 平滑级别；0 关闭，1 到 3 逐级增强 |
+| <code>alignWithIsoline</code> | <code>boolean</code> | 色斑图是否复用等值线的平滑数值场和边界 |
+| <code>isolineColor</code> | <code>string</code> 或 <code>boolean</code> | 等值线颜色；<code>true</code> 表示跟随图例 |
+| <code>isolineBorderColor</code> | <code>string</code> | 等值面边界颜色 |
+| <code>isolineFill</code> | <code>boolean</code> | 是否绘制分级等值面 |
+| <code>showIsolineValue</code> | <code>boolean</code> | 是否沿等值线显示数值 |
+| <code>showText</code> | <code>boolean</code> | MICAPS 是否显示文本 |
+| <code>showFillcolor</code> | <code>boolean</code> | MICAPS 是否填色 |
+| <code>showIsoline</code> | <code>boolean</code> | MICAPS 是否显示等值线 |
+| <code>showPointMarkers</code> | <code>boolean</code> | MICAPS 是否显示符号点 |
+| <code>smooth</code> | <code>boolean</code> | 是否平滑掩膜边缘 |
+| <code>smoothIterations</code> | <code>number</code> | Chaikin 平滑迭代次数，建议 1 到 3 |
+| <code>valueTransform</code> | 函数或字符串 | 绘制和查询前转换栅格值；返回空值表示无效像素 |
+| <code>valueTransformAffectsScope</code> | <code>boolean</code> | 转换结果是否参与 <code>scope</code> 过滤，默认参与 |
+| <code>cache</code> | <code>boolean</code> | 旧版缓存开关，当前版本不建议依赖 |
+| <code>layerConfig</code> | <code>object</code> | TDS/WMS 原始请求参数 |
+| <code>gridConfig</code> | <code>object</code> | 网格数值绘制配置 |
+| <code>windConfig</code> | <code>object</code> | 风场预留扩展配置；当前版本主要使用通用字段和 <code>layerConfig</code> |
+| <code>windShaftConfig</code> | <code>object</code> | 风羽绘制配置 |
+| <code>typhoonConfig</code> | <code>object</code> | 台风路径配置 |
+
+图例项格式：
+
+~~~ts
+const legend = [
+  { name: "0-10", scope: [0, 10], color: "#3b82f6" },
+  { name: "10-20", scope: [10, 20], color: "#22c55e" },
+  { name: "20+", scope: [20, 9999], color: "#ef4444" },
+];
+~~~
+
+完整配置示例：
+
+~~~ts
+const layerOptions: Layer.Config = {
+  id: "temperature",
+  title: "温度",
+  label: "Temperature",
+  type: "gradual",
+  filePath: "/data/temperature",
+  time: "2026-10-28T00:00:00Z",
+  authorization: "Basic ...",
+  config: {
+    extent: [70, 15, 140, 55],
+    mode: "gradient",
+    legendType: "gradual",
+    legendScope: [],
+    scope: [-40, 50],
+    legend,
+    opacity: 0.85,
+    zIndex: 10,
+    isolineSmooth: true,
+    isolineSmoothness: 1,
+  },
+};
+
 loadLayer(map, layerOptions);
-```
+~~~
+
+### layerConfig：TDS/WMS 参数
+
+<code>layerConfig</code> 会被合并到 WMS 或 TDS 请求中。常用字段如下：
+
+| 参数 | 说明 |
+| --- | --- |
+| <code>LAYERS</code> | WMS 图层名；风场通常传 U、V 两个分量名称数组 |
+| <code>ELEVATION</code> | 高度层或气压层 |
+| <code>TIME</code> | 时间参数；由图层 <code>time</code> 生成时会覆盖此值 |
+| <code>BBOX</code> | 请求范围，由 <code>extent</code> 自动生成 |
+| <code>WIDTH</code>、<code>HEIGHT</code> | 图片尺寸，由 <code>imageSize</code> 和范围自动计算 |
+| <code>STYLES</code> | WMS 样式名 |
+| <code>COLORSCALERANGE</code> | 色带范围，通常由 <code>scope</code> 自动生成 |
+| <code>NUMCOLORBANDS</code> | 色带级数 |
+| <code>ABOVEMAXCOLOR</code>、<code>BELOWMINCOLOR</code>、<code>BGCOLOR</code> | 超出范围和背景颜色策略 |
+| <code>LOGSCALE</code> | 是否使用对数色阶 |
+| <code>SERVICE</code>、<code>VERSION</code>、<code>REQUEST</code>、<code>FORMAT</code>、<code>SRS</code> | 标准 WMS 参数 |
+| <code>TINTCOLOR</code> | 将 WMS 图片统一着色的特殊参数 |
+
+业务传入的 <code>BBOX</code>、<code>TIME</code>、<code>WIDTH</code>、<code>HEIGHT</code> 和 <code>COLORSCALERANGE</code> 可能被包重新计算。需要改变这些值时，应优先调整 <code>extent</code>、<code>time</code>、<code>scope</code> 和全局 <code>imageSize</code>。
+
+WMS 图层示例：
+
+~~~ts
+loadLayer(map, {
+  id: "temperature-wms",
+  title: "温度 WMS",
+  label: "Temperature",
+  type: "wms",
+  filePath: "/data/temperature.nc",
+  url: "/wms/data/temperature.nc",
+  serviceBaseUrl: "/server",
+  config: {
+    extent: [70, 15, 140, 55],
+    mode: "gradient",
+    legendType: "gradual",
+    legend,
+    opacity: 0.8,
+    layerConfig: {
+      LAYERS: "Temperature",
+      STYLES: "default-scalar/seq-Rainbow",
+      COLORSCALERANGE: "-40,50",
+      NUMCOLORBANDS: 250,
+      TRANSPARENT: true,
+      FORMAT: "image/png",
+      VERSION: "1.1.1",
+    },
+  },
+});
+~~~
+
+### gridConfig：网格数值
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| <code>pixelStep</code> | 40 | 网格文字像素间距，最小 8 |
+| <code>fontSize</code> | 14 | 文字大小，单位 px，最小 10 |
+| <code>decimals</code> | 1 | 小数位数 |
+| <code>fontColor</code> | #000 | 文字颜色 |
+| <code>strokeColor</code> | #fff | 文字描边颜色 |
+| <code>strokeWidth</code> | 2 | 描边宽度 |
+| <code>fontFamily</code> | Arial, sans-serif | 字体 |
+| <code>useDevicePixelRatio</code> | false | 是否按设备像素比绘制 |
+
+~~~ts
+loadLayer(map, {
+  ...layerOptions,
+  type: ["gradual", "grid"],
+  config: {
+    ...layerOptions.config,
+    gridConfig: {
+      pixelStep: 40,
+      fontSize: 14,
+      decimals: 1,
+      fontColor: "#111827",
+      strokeColor: "#ffffff",
+      strokeWidth: 2,
+      fontFamily: "Arial, sans-serif",
+      useDevicePixelRatio: true,
+    },
+  },
+});
+~~~
+
+### windShaftConfig：风羽
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| <code>pixelStep</code> | 40 | 风羽采样像素步长，最小 8 |
+| <code>fontSize</code> | 26 | 风羽尺寸，最小 10 |
+| <code>color</code> | rgb(255,255,255) | 风羽颜色 |
+| <code>minWindSpeed</code> | 0.01 | 过滤低于该值的风速 |
+| <code>speedLevelStep</code> | 2 | 风速分级步长 |
+| <code>maxLevel</code> | 30 | 风速级别上限 |
+| <code>spriteCellSize</code> | 32 | 风羽雪碧图单格尺寸 |
+| <code>baseFontSize</code> | 32 | 图标缩放基准字号 |
+| <code>iconYOffsetRatio</code> | 0.7 | 图标 Y 轴偏移比例 |
+| <code>firstRowMaxLevel</code> | 3 | 雪碧图第一行最大等级 |
+| <code>firstRowStartX</code> | 28 | 雪碧图第一行起始 X 坐标 |
+| <code>firstRowY</code> | 4 | 雪碧图第一行 Y 坐标 |
+| <code>secondRowOffsetX</code> | 4 | 雪碧图第二行 X 偏移 |
+| <code>secondRowY</code> | 5 | 雪碧图第二行 Y 坐标 |
+
+风场和风羽通常组合使用：
+
+~~~ts
+loadLayer(map, {
+  id: "wind",
+  title: "10 米风场",
+  label: "Wind",
+  type: ["uv", "grid", "windShaft"],
+  filePath: "/data/wind",
+  config: {
+    extent: [70, 15, 140, 55],
+    mode: "gradient",
+    legendType: "gradual",
+    legend: windLegend,
+    scope: [0, 60],
+    layerConfig: {
+      LAYERS: [
+        "u-component_of_wind_height_above_ground",
+        "v-component_of_wind_height_above_ground",
+      ],
+    },
+    windShaftConfig: {
+      pixelStep: 20,
+      fontSize: 18,
+      color: "rgb(255,255,255)",
+      minWindSpeed: 0.01,
+      speedLevelStep: 2,
+    },
+  },
+});
+~~~
+
+### typhoonConfig：台风路径
+
+| 参数 | 说明 |
+| --- | --- |
+| <code>serviceBaseUrl</code> | 台风 JSON 服务前缀，覆盖全局台风服务地址 |
+| <code>dataPath</code> | TDS fileServer 下的台风 JSON 目录 |
+| <code>typhoonNums</code> | 只加载指定台风编号；不传则使用列表中的默认台风 |
+| <code>sourcePriority</code> | 实况和预报来源优先级 |
+| <code>showForecast</code> | 是否显示预报路径 |
+| <code>fitToExtent</code> | 加载后是否自动缩放到路径范围，默认开启 |
+
+~~~ts
+loadLayer(map, {
+  id: "typhoon",
+  title: "台风路径",
+  label: "Typhoon",
+  type: "typhoon",
+  filePath: "data/script/mdp_typhoon/output",
+  authorization: "Basic ...",
+  config: {
+    extent: [100, 5, 180, 50],
+    mode: "gradient",
+    legendType: "legend",
+    legend: typhoonLegend,
+    typhoonConfig: {
+      dataPath: "data/script/mdp_typhoon/output",
+      typhoonNums: ["2415"],
+      sourcePriority: ["BABJ|WTPQ20", "RJTD|WTPQ51"],
+      showForecast: true,
+      fitToExtent: true,
+    },
+  },
+});
+~~~
+
+### 参数更新规则
+
+<code>updateLayer</code> 会按 <code>id</code> 更新通过 <code>loadLayer</code> 管理的相关图层；如果同时创建了关联的 <code>grid</code> 或 <code>windShaft</code> 图层，也会同步更新。直接使用 <code>createIsoline</code> 或 <code>createMicContour</code> 创建的底层图层，应使用对应的删除和显隐方法管理。
+
+## 图层管理
+
+~~~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
+
+~~~js
+const { initMap, loadLayer } = require("tds-map-methods");
+~~~
 
-The package also exports TDS request helpers, including fetchTdsGet, fetchXMLFromUrl,
-getMenuList, getXmlData, getVariableMinMax, resolveLayerLoadOptions, and typhoon requests.
+## 使用注意
 
-The package does not read host Vite environment variables. Supply service URLs explicitly.
+- 本包用于浏览器环境，依赖 DOM、Canvas、WebGL / WebGPU 和 OpenLayers。
+- 调用 `initMap` 前，地图容器必须已挂载并具有非零宽高。
+- 本包不会读取宿主项目的 Vite 环境变量，请通过 `configureMapMethods` 显式传入服务地址。
+- 跨域请求需要服务端正确配置 CORS；Authorization 请求头也必须被服务端允许。
+- `Layer.Config`、台风数据和请求方法均提供 TypeScript 类型提示。
+- `ol`、`@turf/turf`、`dayjs`、`d3-contour` 和 `lodash-es` 为 peer dependencies，需要由宿主项目安装。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tds-map-methods",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Map methods extracted from tds demo.",
   "publishConfig": {