tds-map-methods 0.1.2 → 0.1.4

package/README.md

@@ -168,6 +168,281 @@ loadLayer(map, {
 });
 ~~~
 
+## 图层参数配置
+
+<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