fix: 完善 WebMapV3 Sprite 处理与资源引用

- 修正旧版线符号方向并统一 WebMap 图案方向
- 导出 Sprite 加载处理函数供外部 WebApp 使用
- 更新 Mapbox GL Enhance 文档链接并补充相关测试

AI-GEN: 90% gpt5.6-luna

Author: xiongjiaojiao

src/common/index.common.js

@@ -761,4 +761,5 @@ export { KeyServiceParameter, SecurityManager, ServerInfo, TokenServiceParameter
 export { CartoCSS, ThemeStyle };
 export { ElasticSearch };
 export { Lang };
-export { KnowledgeGraph } from './overlay/KnowledgeGraph';
+export { KnowledgeGraph } from './overlay/KnowledgeGraph';
+export { createSpriteLoadHandler } from './mapping/WebMapV3';

src/common/mapping/WebMapV3.js

@@ -2,7 +2,7 @@
  * This program are made available under the terms of the Apache License, Version 2.0
  * which accompanies this distribution and is available at http://www.apache.org/licenses/LICENSE-2.0.html.*/
 import { FetchRequest } from '../util/FetchRequest';
-import { getLayerCatalogRenderLayers, getLayerInfosFromCatalogs, getMainLayerFromCatalog, isSameRasterLayer, mergeFeatures, transformUrl } from './utils/util';
+import { getLayerCatalogRenderLayers, getLayerInfosFromCatalogs, getMainLayerFromCatalog, isSameRasterLayer, mergeFeatures, transformUrl, flipImageVertically } from './utils/util';
 import { SourceListModelV3 } from './utils/SourceListModelV3';
 import cloneDeep from 'lodash.clonedeep';
 
@@ -162,6 +162,28 @@ export const LEGEND_STYLE_TYPES = {
   IMAGE: 'image',
   STYLE: 'style'
 };
+
+/**
+ * 按地图版本创建 Sprite 加载处理函数，供 WebMap 和外部 WebApp 共用。
+ * @param {string} mapVersion 地图版本号。
+ * @returns {Function|undefined} 旧版地图返回线符号处理函数，新版地图不需要额外处理。
+ */
+export function createSpriteLoadHandler(mapVersion) {
+  const [major, minor, patch] = typeof mapVersion === 'string' ? mapVersion.split('.').map(Number) : [];
+  // 3.3.7 及以前的地图线符号需要垂直翻转；新版本由地图数据自身保证方向。
+  if (major > 3 || (major === 3 && minor > 3) || (major === 3 && minor === 3 && patch > 7)) {
+    return;
+  }
+  return (id, imageData, width, height) => {
+    // 翻转所有 line- 开头的图案
+    if (id && id.startsWith('line-')) {
+      return flipImageVertically(imageData, width, height);
+    }
+
+    return null;
+  };
+}
+
 export function createWebMapV3Extending(SuperClass, { MapManager, mapRepo, crsManager, l7LayerUtil, webMapService }) {
   return class WebMapV3 extends SuperClass {
     constructor(mapId, options, mapOptions = {}) {
@@ -291,6 +313,9 @@ export function createWebMapV3Extending(SuperClass, { MapManager, mapRepo, crsMa
     // 初始化 map
     const mapOptions = {
       ...this.mapOptions,
+      // 统一线图案方向，避免 Mapbox GL 默认方向与 WebMap 符号方向约定不一致；旧版资源翻转由 _getSpriteLoad 按地图版本处理。
+      linePatternOrientation: 'west-to-east',
+      onSpriteLoad: this._getSpriteLoad(),
       transformRequest: this._getTransformRequest(),
       container: this.options.target,
       crs: this._baseProjection,
@@ -317,6 +342,10 @@ export function createWebMapV3Extending(SuperClass, { MapManager, mapRepo, crsMa
     });
   }
 
+  _getSpriteLoad() {
+    return createSpriteLoadHandler(this._mapInfo && this._mapInfo.version);
+  }
+
   _getTransformRequest() {
     if (this.mapOptions.transformRequest) {
       return this.mapOptions.transformRequest;

src/common/mapping/index.js

@@ -2,4 +2,5 @@ export * from './WebMapV2Base';
 export * from './WebMapService';
 export * from './utils/epsg-define';
 export * from './WebMapBase';
-export * from './utils/SourceListModelV2';
+export * from './utils/SourceListModelV2';
+export { createSpriteLoadHandler } from './WebMapV3';

src/common/mapping/utils/util.js

@@ -216,4 +216,19 @@ export function getLayerCatalogRenderLayers(parts, catalogId, layersOnMap) {
 export function getMainLayerFromCatalog(layerParts, catalogId, layersOnMap) {
   const renderLayers = getLayerCatalogRenderLayers(layerParts, catalogId, layersOnMap);
   return layersOnMap.find(item => item.id === renderLayers[0]);
-}
+}
+
+// 垂直翻转 RGBA 图片，保持像素顺序并避免逐通道复制。
+export function flipImageVertically(imageData, width, height) {
+  const sourceData = imageData.data || imageData;
+  const flipped = new Uint8Array(sourceData.length);
+  const rowSize = width * 4;
+
+  for (let row = 0; row < height; row++) {
+    const sourceRowStart = row * rowSize;
+    const targetRowStart = (height - row - 1) * rowSize;
+    flipped.set(sourceData.subarray(sourceRowStart, sourceRowStart + rowSize), targetRowStart);
+  }
+
+  return flipped;
+}

src/mapboxgl/mapping/WebMap.js

@@ -31,7 +31,7 @@ import { GraticuleLayer } from '../overlay/GraticuleLayer';
  *      <p style="font-size: 13px"><a href="https://iclient.supermap.io/web/libs/antv/g2/4.2.8/g2.min.js">G2: </a>&lt;script type="text/javascript" src="https://iclient.supermap.io/web/libs/antv/g2/4.2.8/g2.min.js"&gt;&lt;/script&gt;</p>
  *      <p style="font-size: 13px"><a href="https://iclient.supermap.io/web/libs/antv/g6/4.3.2/g6.min.js">G6: </a>&lt;script type="text/javascript" src="https://iclient.supermap.io/web/libs/antv/g6/4.3.2/g6.min.js"&gt;&lt;/script&gt;</p>
  *      <p style="font-size: 13px"><a href="https://iclient.supermap.io/web/libs/fast-xml-parser/4.2.7/fxparser.min.js">fast-xml-parser: </a>&lt;script type="text/javascript" src="https://iclient.supermap.io/web/libs/fast-xml-parser/4.2.7/fxparser.min.js"&gt;&lt;/script&gt;</p>
- *      <p style="font-size: 13px"><a href="https://iclient.supermap.io/web/libs/mapbox-gl-js-enhance/1.12.1-13/mapbox-gl-enhance.jss">mapbox-gl-js-enhance: </a>&lt;script type="text/javascript" src="https://iclient.supermap.io/web/libs/mapbox-gl-js-enhance/1.12.1-13/mapbox-gl-enhance.js"&gt;&lt;/script&gt;</p>
+ *      <p style="font-size: 13px"><a href="https://iclient.supermap.io/web/libs/mapbox-gl-js-enhance/1.12.1-13/mapbox-gl-enhance.js">mapbox-gl-js-enhance: </a>&lt;script type="text/javascript" src="https://iclient.supermap.io/web/libs/mapbox-gl-js-enhance/1.12.1-13/mapbox-gl-enhance.js"&gt;&lt;/script&gt;</p>
  * </div>
  * @modulecategory Mapping
  * @param {number} id - iPortal|Online 地图 ID。

src/mapboxgl/mapping/index.js

@@ -1,3 +1,3 @@
 export { WebMap } from './WebMap';
 export { initMap } from './InitMap';
-export { VideoMap } from './VideoMap';
+export { VideoMap } from './VideoMap';

test/common/mapping/WebMapV3Spec.js

@@ -1,5 +1,8 @@
 import { createWebMapV3Extending } from '../../../src/common/mapping/WebMapV3';
 import { createMapClassExtending } from '../../../src/common/mapping/MapBase';
+import { createSpriteLoadHandler } from '../../../src/common/mapping';
+import { createSpriteLoadHandler as createPublicSpriteLoadHandler } from '../../../src/common/index.common';
+import { createWebMapBaseExtending } from '../../../src/common/mapping/WebMapBase';
 import { Events } from '../../../src/common/commontypes';
 import { FetchRequest } from '../../../src/common/util/FetchRequest';
 
@@ -175,6 +178,58 @@ describe('WebMapV3 - addLocalIdeographFontFamily', () => {
       inst._createMap();
       expect(capturedOptions).toBeDefined();
       expect(capturedOptions.localIdeographFontFamily).toBe('sans-serif,PingFang SC Regular');
+      expect(capturedOptions.linePatternOrientation).toBe('west-to-east');
+      expect(capturedOptions.onSpriteLoad).toEqual(jasmine.any(Function));
+    });
+  });
+
+  describe('_getSpriteLoad', () => {
+    it('should be exported for external WebApps', () => {
+      expect(createSpriteLoadHandler('3.3.7')).toEqual(jasmine.any(Function));
+      expect(createSpriteLoadHandler('3.3.8')).toBeUndefined();
+      expect(createPublicSpriteLoadHandler).toBe(createSpriteLoadHandler);
+    });
+
+    it('should flip line sprites for maps at version 3.3.7', () => {
+      instance._mapInfo = { version: '3.3.7' };
+      const onSpriteLoad = instance._getSpriteLoad();
+      const imageData = new Uint8Array([
+        1, 2, 3, 4,
+        5, 6, 7, 8
+      ]);
+
+      expect(onSpriteLoad('line-pattern', imageData, 1, 2)).toEqual(new Uint8Array([
+        5, 6, 7, 8,
+        1, 2, 3, 4
+      ]));
+      expect(onSpriteLoad('point-pattern', imageData, 1, 2)).toBeNull();
+    });
+
+    it('should not add a sprite callback for maps newer than version 3.3.7', () => {
+      instance._mapInfo = { version: '3.3.8' };
+
+      expect(instance._getSpriteLoad()).toBeUndefined();
+    });
+
+    it('should compare version components numerically', () => {
+      instance._mapInfo = { version: '3.3.10' };
+
+      expect(instance._getSpriteLoad()).toBeUndefined();
+    });
+
+    it('should disable the callback for higher major and minor versions', () => {
+      ['4.0.0', '3.4.0'].forEach(version => {
+        instance._mapInfo = { version };
+        expect(instance._getSpriteLoad()).toBeUndefined();
+      });
+    });
+
+    it('should keep the callback when the map version is missing', () => {
+      instance._mapInfo = {};
+      const onSpriteLoad = instance._getSpriteLoad();
+
+      expect(onSpriteLoad).toEqual(jasmine.any(Function));
+      expect(onSpriteLoad(null, new Uint8Array(4), 1, 1)).toBeNull();
     });
   });
 });

test/common/mapping/utils/UtilSpec.js

@@ -1,6 +1,26 @@
-import { isSameRasterLayer } from '../../../../src/common/mapping/utils/util';
+import { flipImageVertically, isSameRasterLayer } from '../../../../src/common/mapping/utils/util';
 
 describe('util', () => {
+  describe('flipImageVertically', () => {
+    it('flips RGBA rows in a typed array', () => {
+      const pixels = new Uint8Array([
+        1, 2, 3, 4, 5, 6, 7, 8,
+        9, 10, 11, 12, 13, 14, 15, 16
+      ]);
+
+      expect(flipImageVertically(pixels, 2, 2)).toEqual(new Uint8Array([
+        9, 10, 11, 12, 13, 14, 15, 16,
+        1, 2, 3, 4, 5, 6, 7, 8
+      ]));
+    });
+
+    it('accepts ImageData-like objects and a single-row image', () => {
+      const pixels = new Uint8ClampedArray([1, 2, 3, 4, 5, 6, 7, 8]);
+      const result = flipImageVertically({ data: pixels }, 2, 1);
+
+      expect(result).toEqual(new Uint8Array(pixels));
+    });
+  });
   it('isSameRasterLayer', (done) => {
     let res = isSameRasterLayer(
       { type: 'raster', tiles: ['http:17.0.0.1:8190/iserver/rest/maps/China'] },

test/mapboxgl/mapping/WebMapV3Spec.js

@@ -4,6 +4,7 @@ import { createWebMapV3Extending } from '../../../src/common/mapping/WebMapV3';
 import { createMapClassExtending } from '../../../src/common/mapping/MapBase';
 import { L7LayerUtil } from '../../../src/common/mapping/utils/L7LayerUtil';
 import { WebMap } from '../../../src/mapboxgl/mapping/WebMap';
+import { createSpriteLoadHandler } from '../../../src/mapboxgl';
 import * as MapManagerUtil from '../../../src/mapboxgl/mapping/webmap/MapManager';
 import { CRSManager } from '../../../src/mapboxgl/mapping/webmap/CRSManager';
 import { featureFilter, expression } from '@mapbox/mapbox-gl-style-spec';
@@ -15,6 +16,9 @@ import '../../resources/WebMapV3.js';
 import '../../resources/WebMapV5.js';
 var server = 'http://localhost:8190/iportal/';
 describe('mapboxgl-webmap3.0', () => {
+  it('exports the Sprite load handler from the package entry point', () => {
+    expect(createSpriteLoadHandler('3.3.7')).toEqual(jasmine.any(Function));
+  });
   var originalTimeout, testDiv;
   var id = 617580084;
   var mapstudioWebmap;