@kq_npm/client3d_webgl_vue 4.5.55 → 4.5.57

package/adddata/index.js

@@ -489,12 +489,32 @@ var _useGlobalConfig = __webpack_require__(22686);
  * All rights reserved.
  */
 
-//添加数据逻辑类
+/**
+ * @class AddDataViewModel
+ * @classdesc 添加数据逻辑类，负责本地文件与 URL 数据源的解析加载、图层树节点管理与服务分发
+ * @param {Object} scenceView 三维场景视图对象，需包含 _viewer 与 _layerManager
+ * @param {Object} options 初始化选项
+ * @param {String} options.geometryServerUrl 几何服务地址前缀
+ * @param {String} options.geometryServerToken 几何服务 ua_token
+ * @param {Object} [options.geojsonStyle] 自定义 geojson 渲染样式，会与默认样式合并
+ */
 class AddDataViewModel {
+  /**
+   * @description 构造函数，初始化场景视图、图层管理器、几何服务地址与 token、geojson 样式
+   * @param {Object} scenceView 三维场景视图对象，需包含 _viewer 与 _layerManager
+   * @param {Object} options 初始化选项
+   * @param {String} options.geometryServerUrl 几何服务地址前缀
+   * @param {String} options.geometryServerToken 几何服务 ua_token
+   * @param {Object} [options.geojsonStyle] 自定义 geojson 渲染样式，会与默认样式合并
+   */
   constructor(scenceView, options) {
+    // 三维场景视图实例
     this._viewer = null;
+    // 图层管理器，负责临时图层节点、图层列表的维护
     this._layerManager = null;
+    // 当前语言环境与语言包
     this._language = null;
+    // geojson 数据默认渲染样式：包含 label/billboard/polyline/polygon 四类要素样式
     this._geojsonStyle = {
       label: {
         express: "name",
@@ -539,17 +559,26 @@ class AddDataViewModel {
     this._layerManager = scenceView._layerManager;
     this._geometryServerUrl = options.geometryServerUrl;
     this._geometryServerToken = options.geometryServerToken;
+    // 自定义样式与默认样式合并，未传入时保持默认
     if (options.geojsonStyle) this._geojsonStyle = Object.assign({}, this._geojsonStyle, options.geojsonStyle);
+    // 兼容网格编码相关异步模块挂载
     if (window.Module) window.mapGridAsync = window.Module;
   }
 
-  //解析文件
+  /**
+   * @description 解析本地文件并加载到三维场景：根据扩展名分流处理 zip/txt/csv/xls/xlsx/dwg/dxf
+   *              及 json/geojson/kml/kmz/czml/kqgeobody 等格式，加载成功后添加临时图层节点
+   * @param {File} file 待解析的文件对象，依据 file.name 的扩展名决定解析方式
+   * @param {Function} [cb] 加载完成回调，参数为图层节点信息（失败时传 "error"）
+   * @returns {Promise} 解析结果的 Promise，成功 resolve("success")，失败 reject 错误信息
+   */
   parseFile(file, cb) {
     var that = this;
     return new Promise((resolve, reject) => {
       var ext = file.name.replace(/.+\./, "").toLowerCase(); //文件扩展名
       var name = file.name.replace(/(.*\/)*([^.]+).*/gi, "$2"); //文件名
       if (ext === "zip") {
+        // zip 压缩包：通过几何服务解析为 SHP 后转为 geojson 数据源加载
         (0, _util.uploadSHP)(file, function (res) {
           if (res) {
             var ds = new Cesium.Kq3dGeoJsonDataSource(name);
@@ -587,6 +616,7 @@ class AddDataViewModel {
           }
         });
       } else if (ext === "txt") {
+        // txt 文本：调用几何服务解析坐标文本后转为 geojson 数据源加载
         let dataUrl = that._geometryServerUrl + (that._geometryServerToken ? "?ua_token=" + that._geometryServerToken : "");
         (0, _util.readTxT)(file, dataUrl, "4326", this._language.value.common, res => {
           if (res) {
@@ -625,6 +655,7 @@ class AddDataViewModel {
           }
         });
       } else if (ext === "csv") {
+        // csv 表格：本地解析后按 LAT/LNG 或 X/Y 列提取坐标构造 FeatureCollection
         (0, _util.readFile)(file, res => {
           var features = _papaparse.default.parse(res, {
             skipEmptyLines: true,
@@ -700,6 +731,7 @@ class AddDataViewModel {
           }
         });
       } else if (ext === "xls" || ext === "xlsx") {
+        // xls/xlsx 表格：通过几何服务解析为 geojson 后加载
         (0, _util.readExcel)(file, this._language.value.common, res => {
           if (res) {
             var ds = new Cesium.Kq3dGeoJsonDataSource(name);
@@ -736,6 +768,7 @@ class AddDataViewModel {
           }
         });
       } else if (ext === "dwg" || ext === "dxf") {
+        // dwg/dxf CAD 文件：通过几何服务解析为 geojson 后加载，并清理 srs/crs 字段
         (0, _util.uploadCad)(this._geometryServerUrl, file, this._geometryServerToken, this._language.value.common, "4326", function (res) {
           // console.log(res);
           if (res) {
@@ -781,6 +814,7 @@ class AddDataViewModel {
           }
         });
       } else {
+        // 其余文本类格式（json/geojson/topojson/kml/kmz/czml/kqgeobody）：以文本方式读取后按扩展名分流
         var reader = new FileReader();
         reader.readAsText(file); //文本
         //readAsDataURL(file);  //base64 图片
@@ -793,6 +827,7 @@ class AddDataViewModel {
             case "json":
             case "geojson":
             case "topojson":
+              // geojson 类：解析为对象后加载，若含 geometryType 字段则按 ArcGIS EsriGeoJson 处理
               ret = ret.replace(/(^\s*)|(\s*$)/, "");
               ret = ret.substring(ret.indexOf("{"));
               try {
@@ -842,6 +877,7 @@ class AddDataViewModel {
               });
               break;
             case "kml":
+              // kml 文本：转为 Blob 后由 KmlDataSource 加载
               ret = ret.replace(/(^\s*)|(\s*$)/, "");
               var options = {
                 name: name,
@@ -870,6 +906,7 @@ class AddDataViewModel {
               });
               break;
             case "kmz":
+              // kmz 二进制压缩包：直接以 File 对象交给 KmlDataSource 加载
               var options = {
                 name: name,
                 camera: that._viewer.scene.camera,
@@ -894,6 +931,7 @@ class AddDataViewModel {
               });
               break;
             case "czml":
+              // czml：解析为对象后加载，并显示时间轴与动画控件
               ret = ret.replace(/(^\s*)|(\s*$)/, "");
               try {
                 var data = JSON.parse(ret);
@@ -901,6 +939,7 @@ class AddDataViewModel {
                   ret = data;
                 }
               } catch (e) {}
+              // 首次加载 czml 时显示时间轴/动画控件并启动时钟
               if (that._viewer.timeline.container.style.display != 'block') {
                 that._viewer.bottomContainer.style.bottom = '15px';
                 that._viewer.timeline.container.style.display = 'block';
@@ -927,6 +966,7 @@ class AddDataViewModel {
               });
               break;
             case "kqgeobody":
+              // kqgeobody 地质体：解析为数组后构造 Kq3dGeologyBody 并定位到包围球
               ret = ret.replace(/(^\s*)|(\s*$)/, "");
               try {
                 let data = JSON.parse(ret);
@@ -940,9 +980,11 @@ class AddDataViewModel {
               geology.name = name;
               that._viewer.geologyBodyCollection.push(geology);
               geology.createGeology(ret).then(function (geobody) {
+                // 将地质体图元集合加入场景 primitives（若尚未加入）
                 if (!geobody.viewer.scene.primitives.contains(geobody.geologyPrimitives)) {
                   geobody.geologyPrimitives = geobody.viewer.scene.primitives.add(geobody.geologyPrimitiveCollection);
                 }
+                // 汇总所有图元的包围球并飞行定位
                 let boundingSpheres = [];
                 geobody.geologyPrimitives._primitives.forEach(primitive => {
                   if (primitive.geometryInstances.geometry.boundingSphere) {
@@ -981,11 +1023,21 @@ class AddDataViewModel {
     });
   }
 
-  //解析数据源
+  /**
+   * @description 解析 URL 数据源：校验 url 有效性后通过 fetch 探测服务可用性，
+   *              再调用 parseService 按类型加载；stkterrain/kqgis3dserver 会自动拼接探测地址
+   * @param {Object} options 数据源选项
+   * @param {String} options.type 数据源类型（如 kqgis3dserver/wms/wmts/3dtiles/geojson 等）
+   * @param {String} options.url 服务地址
+   * @param {String} [options.name] 节点名称
+   * @param {Function} [cb] 加载完成回调，参数为图层节点信息
+   * @param {Function} [loadCustom] 自定义加载函数（仅 KQGIS 地图服务生效，earthstudio 使用）
+   */
   parseDataSource(options, cb, loadCustom) {
     options = options || {};
     if (options.url && options.url !== "") {
       let url = options.url;
+      // stkterrain 地形服务：自动拼接 layer.json 用于可用性探测
       if (options.type === "stkterrain") {
         if (url.indexOf("?") > 0) {
           url = url.replace("?", "layer.json?");
@@ -993,6 +1045,7 @@ class AddDataViewModel {
           url += "layer.json";
         }
       } else if (options.type === "kqgis3dserver") {
+        // KQGIS 三维服务：自动拼接 /tilesets 用于可用性探测
         if (url.indexOf("?") > 0) {
           url = url.replace("?", "/tilesets?");
         } else {
@@ -1039,13 +1092,23 @@ class AddDataViewModel {
     }
   }
 
-  //解析服务
+  /**
+   * @description 解析服务：按 options.type 分发到各类型服务的加载逻辑，
+   *              加载完成后构造图层节点并调用 _layerManager.addTempLayerNode 注册
+   * @param {Object} options 数据源选项
+   * @param {String} options.type 数据源类型（小写匹配 switch 分支）
+   * @param {String} options.url 服务地址
+   * @param {String} [options.name] 节点名称，为空时按 url 自动推断
+   * @param {Function} [cb] 加载完成回调，参数为图层节点信息
+   * @param {Function} [loadCustom] 自定义加载函数（仅 KQGIS 地图服务生效）
+   */
   parseService(options, cb, loadCustom) {
     let that = this;
     let url = options.url;
     let type = options.type || "";
     type = type.toLowerCase();
     let name = options.name;
+    // 名称缺省时：文件型服务取 url 末段，其余服务取 url 倒数第二段作为名称
     if (!name || name === "") {
       let ext;
       if (url.lastIndexOf(".") > url.lastIndexOf("/")) {
@@ -1127,6 +1190,7 @@ class AddDataViewModel {
         cb && cb(node);
         break;
       case "3dtiles":
+        // 3DTiles 瓦片集：作为 primitive 加入场景
         var tileset = this._viewer.scene.primitives.add(new Cesium.Cesium3DTileset({
           name: name,
           url: url
@@ -1165,6 +1229,7 @@ class AddDataViewModel {
             var addType = "";
             let promiseList = [];
             for (var i = 0; i < layers.length; i++) {
+              // 按图元类型识别 KQGIS 三维服务子图层，并归类 serverType/addType
               if (layers[i] instanceof Cesium.Cesium3DTileset) {
                 serverType = "3dtiles";
                 addType = "3dtiles";
@@ -1184,6 +1249,7 @@ class AddDataViewModel {
                 url = layers[i]._originUrl;
                 this._layerManager._terrainProviders.push(layers[i]);
               } else if (layers[i] instanceof Cesium.Kq3dGeoJsonDataSource) {
+                // geojson 数据源：监听 loadingEvent 完成后构造子节点（含点线面类型判断）
                 serverType = "datasource";
                 addType = "geojson";
                 url = layers[i]._url;
@@ -1271,6 +1337,7 @@ class AddDataViewModel {
             let list = service.collectionInfoList;
             if (list && list.length > 0) {
               list.forEach(item => {
+                // 多维气象数据走 windy 气象渲染通道
                 if (item.type === 'Image' && item.hasMultidimension && item.additionInfo) {
                   let params = that._layerManager._windyViewModel.getWeatherDataOptions(item);
                   let layerConfig = {
@@ -1338,6 +1405,7 @@ class AddDataViewModel {
 
         window.KqGIS.getVectorStyleForDataService(url, 'EPSG:3857').then(data => {
           let style = data.style;
+          // 将带图标的 symbol 图层替换为圆点文本样式，规避图标缺失导致的渲染问题
           style.layers.forEach(item => {
             if (item.type == "symbol") {
               if (item.layout["icon-image"]) {
@@ -1562,6 +1630,7 @@ class AddDataViewModel {
         });
         break;
       case "wms":
+        // OGC WMS 服务：加载图层组并补充 KQGIS 服务信息用于查询分析
         this._viewer.addWMSLayerGroup(url).then(group => {
           node = {
             guid: group.guid,
@@ -1590,6 +1659,7 @@ class AddDataViewModel {
           // this._layerManager.addTempLayerNode(node);
           // cb && cb(node);
 
+          // wms 节点先以深拷贝形式回调，再异步补充 KQGIS 图层信息后注册到图层树
           cb && cb(JSON.parse(JSON.stringify(node)));
           this._addKQGISInfo(url, node);
         });
@@ -1598,6 +1668,7 @@ class AddDataViewModel {
       case "kqgistileserver": // KQGIS 瓦片服务
       case "kqgisaggregationserver":
         // KQGIS 聚合服务
+        // KQGIS 瓦片服务需拼接 /wmts 后再按 WMTS 流程解析
         if (type === "kqgistileserver") {
           if (url.indexOf("?") > 0) {
             url = url.replace("?", "/wmts?");
@@ -1621,6 +1692,7 @@ class AddDataViewModel {
           if (tileMatrix.length > 0) {
             let scale = Number(tileMatrix[0].ScaleDenominator);
             let precision = scale * 0.001;
+            // 校验顶层比例尺是否符合标准 WMTS（0 层或 1 层比例尺），符合才加载
             if (Math.abs(scale - 559082264.028716) < precision || Math.abs(scale - 279541132.014358) < precision) {
               this._viewer.addWMTSLayerGroup(url).then(group => {
                 // if(type === "kqgistileserver") defaultName = name;
@@ -1652,6 +1724,7 @@ class AddDataViewModel {
                     });
                   }
                 }
+                // wmts 走 KQGIS 信息补充流程；瓦片/聚合服务直接注册图层树
                 if (type === "wmts") {
                   cb && cb(JSON.parse(JSON.stringify(node)));
                   this._addKQGISInfo(url, node);
@@ -1670,6 +1743,7 @@ class AddDataViewModel {
         });
         break;
       case "wfs":
+        // OGC WFS 服务：先 GetCapabilities 获取所有 typeName，再逐个 GetFeature 转 geojson 加载
         let serverInfo = new KqGIS.Data.WFSInfoService(url);
         serverInfo.dataWFSInfo({
           request: 'GetCapabilities'
@@ -1750,6 +1824,7 @@ class AddDataViewModel {
         });
         break;
       case "geojson":
+        // geojson URL：直接加载为 Kq3dGeoJsonDataSource，并为面要素补充边框线
         var ds = new Cesium.Kq3dGeoJsonDataSource(name);
         ds.load(url, this._geojsonStyle).then(ds => {
           ds.entities.values.forEach(entity => {
@@ -1780,6 +1855,7 @@ class AddDataViewModel {
         });
         break;
       case "arcjson":
+        // ArcGIS JSON URL：使用 EsriGeoJsonDataSource 加载，label 字段固定为 NAME
         var ds = new Cesium.Kq3dEsriGeoJsonDataSource(name);
         var geojsonStyle = {
           ...this._geojsonStyle
@@ -1813,6 +1889,7 @@ class AddDataViewModel {
         });
         break;
       case "kml":
+        // kml URL：通过 KmlDataSource 加载，需传入 camera 与 canvas
         var ds = new Cesium.KmlDataSource({
           name: name,
           camera: this._viewer.camera,
@@ -1835,6 +1912,7 @@ class AddDataViewModel {
         });
         break;
       case "czml":
+        // czml URL：通过 CzmlDataSource 加载
         var ds = new Cesium.CzmlDataSource(name);
         ds.load(url).then(ds => {
           this._viewer.dataSources.add(ds);
@@ -1853,6 +1931,7 @@ class AddDataViewModel {
         });
         break;
       case "s3m":
+        // S3M 模型服务：作为 Kq3dS3MTilesLayer 图元加入场景
         layer = this._viewer.scene.primitives.add(new Cesium.Kq3dS3MTilesLayer({
           context: this._viewer.scene._context,
           url: url,
@@ -1878,7 +1957,11 @@ class AddDataViewModel {
     }
   }
 
-  // KQGIS地图服务wms或者wmts方式加载, 添加KQGIS服务图层信息用于查询和分析
+  /**
+   * @description KQGIS 地图服务以 wms/wmts 方式加载时，补充 KQGIS 服务图层信息用于查询和分析
+   * @param {String} url 服务地址，需包含 /kqgis/ 与 /map/wmts 或 /map/wms 才走补充流程
+   * @param {Object} node 已构造的图层树节点，children 会被 layerInfo 合并增强
+   */
   _addKQGISInfo(url, node) {
     if (url.indexOf("/kqgis/") > -1 && (url.indexOf("/map/wmts") > -1 || url.indexOf("/map/wms") > -1)) {
       let serverName = url.split("services/")[1].split("/")[0];
@@ -1919,6 +2002,12 @@ class AddDataViewModel {
       this._layerManager.addTempLayerNode(node);
     }
   }
+
+  /**
+   * @description 加载 KQGIS 数据服务下所有数据源与数据集，构建图层树子节点数组
+   * @param {String} url 数据服务地址
+   * @returns {Promise} resolve 为子节点数组；失败时 reject([])
+   */
   addDataServer(url) {
     return new Promise((resolve, reject) => {
       Cesium.Kq3dService.datasourceService(url).getDatasources(async e => {
@@ -1945,6 +2034,13 @@ class AddDataViewModel {
       });
     });
   }
+
+  /**
+   * @description 获取指定数据源下的数据集列表
+   * @param {String} url 数据服务地址
+   * @param {String} datasourceName 数据源名称
+   * @returns {Promise} resolve 为数据集数组；失败时 reject([])
+   */
   _getDatasetList(url, datasourceName) {
     let params = new window.KqGIS.Data.GetDatasetsInfoParams({
       datasourceName: datasourceName
@@ -1964,7 +2060,13 @@ class AddDataViewModel {
     });
   }
 
-  // 加载数据集
+  /**
+   * @description 加载数据集：按 isParentDataset 区分父子层级，递归构建数据源节点树
+   * @param {String} url 数据服务地址
+   * @param {String} datasourceName 数据源名称
+   * @param {Array} datasetList 数据集列表
+   * @param {Array} nodes 输出参数，构建完成的数据源节点会被 push 进该数组
+   */
   async _addDataSets(url, datasourceName, datasetList, nodes) {
     let dataSourceNode = {
       guid: window.Cesium.createGuid(),
@@ -1975,8 +2077,10 @@ class AddDataViewModel {
     // 获取数据集类型数据
     const datasetArr = datasetList.filter(o => o['isParentDataset'] === true);
     if (datasetArr.length === 0) {
+      // 无父数据集：直接将所有数据集作为要素加载
       await this._addFeatures(url, datasourceName, datasetList, dataSourceNode);
     } else {
+      // 存在父子层级：先建立父节点，再按 parentDatasetName 分组加载子数据集
       datasetArr.forEach(dataset => {
         dataSourceNode.children.unshift({
           guid: window.Cesium.createGuid(),
@@ -1993,7 +2097,14 @@ class AddDataViewModel {
     nodes.push(dataSourceNode);
   }
 
-  // 加载要素
+  /**
+   * @description 加载要素：遍历数据集，逐个获取要素并转为 geojson 数据源，挂到父节点下
+   * @param {String} url 数据服务地址
+   * @param {String} datasourceName 数据源名称
+   * @param {Array} datasetList 数据集列表
+   * @param {Object} parentNode 父节点，加载完成的子节点会 push 到其 children
+   * @returns {Promise} 所有数据集加载完成后 resolve
+   */
   async _addFeatures(url, datasourceName, datasetList, parentNode) {
     let promises = [];
     for (let i = 0; i < datasetList.length; i++) {
@@ -2034,6 +2145,14 @@ class AddDataViewModel {
       });
     });
   }
+
+  /**
+   * @description 获取指定数据集的要素列表（带几何、输出 EPSG:4326）
+   * @param {String} url 数据服务地址
+   * @param {String} datasourceName 数据源名称
+   * @param {String} datasetName 数据集名称
+   * @returns {Promise} resolve 为要素结果（附加 datasetName 字段）；失败时 reject(null)
+   */
   _getFeatureList(url, datasourceName, datasetName) {
     let params = new window.KqGIS.Data.GetFeaturesParamsBase({
       datasourceName: datasourceName,
@@ -2057,34 +2176,46 @@ class AddDataViewModel {
       });
     });
   }
+
+  /**
+   * @description 飞行定位到指定图层：按图层类型分别采用 getViewableRectangle、
+   *              boundingSphere、rectangle 或 flyTo 等方式定位
+   * @param {Object} layer 目标图层，支持 ImageryLayer/Cesium3DTileset/S3MTilesLayer/GeoJsonDataSource/KmlDataSource/CzmlDataSource/地形 Provider/I3SDataProvider 等
+   */
   flyToLayer(layer) {
     let viewer = this._viewer;
     if (layer instanceof Cesium.ImageryLayer) {
+      // 影像图层：飞到可视矩形
       layer.getViewableRectangle().then(function (rectangle) {
         viewer.camera.flyTo({
           destination: rectangle
         });
       });
     } else if (layer instanceof Cesium.Cesium3DTileset) {
+      // 3DTiles：飞到包围球
       layer.readyPromise.then(function () {
         viewer.camera.flyToBoundingSphere(layer.boundingSphere, {
           offset: new Cesium.HeadingPitchRange(0.0, Cesium.Math.toRadians(-90.0), layer.boundingSphere.radius * 2)
         });
       });
     } else if (layer instanceof Cesium.Kq3dS3MTilesLayer) {
+      // S3M 模型：飞到图层 rectangle
       layer.readyPromise.then(function (tileset) {
         viewer.camera.flyTo({
           destination: tileset.rectangle
         });
       });
     } else if (layer instanceof Cesium.GeoJsonDataSource || layer instanceof Cesium.Kq3dGeoJsonDataSource || layer instanceof Cesium.Kq3dEsriGeoJsonDataSource) {
+      // GeoJson 数据源：俯视定位
       let offset = new Cesium.HeadingPitchRange(0, Cesium.Math.toRadians(-90), 0);
       viewer.flyTo(layer, {
         offset
       });
     } else if (layer instanceof Cesium.KmlDataSource || layer instanceof Cesium.CzmlDataSource) {
+      // KML/CZML：直接 flyTo
       viewer.flyTo(layer);
     } else if (layer instanceof Cesium.Kq3dKQGISServerTerrainProvider || layer instanceof Cesium.Kq3dFileTerrainProvider || layer instanceof Cesium.CesiumTerrainProvider) {
+      // 地形 Provider：优先用 ExtentSource 范围，否则用可视矩形
       layer.getViewableRectangle().then(function (rectangle) {
         if (layer.ExtentSource) {
           var rectangle = Cesium.Rectangle.fromDegrees(layer.ExtentSource.left, layer.ExtentSource.bottom, layer.ExtentSource.right, layer.ExtentSource.top);
@@ -2098,7 +2229,7 @@ class AddDataViewModel {
         }
       });
     } else if (Cesium.I3SDataProvider) {
-      // i3s图层定位
+      // i3s 图层定位
       if (layer instanceof Cesium.I3SDataProvider) {
         viewer.camera.flyTo({
           destination: layer.extent
@@ -2108,7 +2239,11 @@ class AddDataViewModel {
   }
 }
 
-// 设置子节点addType属性
+/**
+ * @description 递归设置节点树叶子节点的 addType 属性
+ * @param {Array} nodeList 图层节点数组
+ * @param {String} addType 待设置的 addType 值
+ */
 exports["default"] = AddDataViewModel;
 function setChildrenAddType(nodeList, addType) {
   for (let i = 0; i < nodeList.length; i++) {
@@ -2623,6 +2758,8 @@ const _hoisted_11 = {
 const _hoisted_12 = {
   class: "btns_box"
 };
+// 允许上传的文件扩展名清单
+
 const __default__ = {
   name: "Kq3dAddData"
 };
@@ -2712,31 +2849,42 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
     expose: __expose
   }) {
     let accept = ".zip,.geojson,.topojson,.json,.kml,.kmz,.czml,.csv,.xls,.xlsx,.txt,.dwg,.dxf,.kqgeobody";
+    // 当前语言环境与语言包
     const {
       lang,
       locale
     } = (0, _useGlobalConfig.useLocale)();
+    // 监听语言切换，重新生成数据源类型列表并同步当前选中的类型
     (0, _vue.watch)(() => lang.value, (newVal, oldVal) => {
       dataSourceTypeList.value = setDataSourceType();
       dataSourceType.value = dataSourceTypeList.value[selectTypeIndex.value];
     });
+    // 当前选中的数据源类型索引
     let selectTypeIndex = (0, _vue.ref)(0);
     //选择的数据源类型
     let dataSourceType = (0, _vue.ref)({});
+    // URL 加载表单数据：服务地址与节点名称
     let dataSource = (0, _vue.reactive)({
       url: "",
       name: ""
     });
+
+    // 拖拽上传组件的 ref 引用
     let upload_ref = (0, _vue.ref)(null);
+    // 点击选择文件按钮对应的上传组件 ref 引用
     let upload_btn_ref = (0, _vue.ref)(null);
+    // 待加载的本地文件列表
     let fileList = (0, _vue.ref)([]);
+    // 本地文件加载中状态标识
     let loadingFile = (0, _vue.ref)(false);
 
     // 获取组件传参
     const props = __props;
     //URL服务支持的数据源类型
     let dataSourceTypeList = (0, _vue.ref)(setDataSourceType());
+    // 初始化当前选中的数据源类型
     dataSourceType.value = dataSourceTypeList.value[selectTypeIndex.value];
+    // 将文件列表按每行 3 个分组，用于在界面上以栅格形式展示
     let operatorArray = (0, _vue.computed)(() => {
       let array = [];
       let list = [...fileList.value];
@@ -2746,6 +2894,8 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
       }
       return array;
     });
+
+    // 加载按钮禁用状态：当文件列表为空时禁用
     let disabled = (0, _vue.computed)(() => {
       let flag = true;
       if (fileList.value.length > 0) {
@@ -2759,8 +2909,12 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
 
     // 生成组件默认header
     let headerTemp = (0, _vue.ref)();
+    // 头部模板组件实例引用
     let headerTempRef = (0, _vue.ref)();
+    // 业务逻辑类实例
     let viewModel = null;
+
+    /** @description 构造 URL 服务支持的数据源类型列表（依据 isShowKQGISKey 与 hideServiceTypes 进行过滤和文本替换） */
     function setDataSourceType() {
       let types = [
       // {
@@ -2909,6 +3063,8 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
       }
       return types;
     }
+
+    /** @description 组件挂载钩子：定位容器、监听 position 与 showHeaderTemp 变化、实例化 AddDataViewModel */
     (0, _vue.onMounted)(() => {
       (0, _util.updatePosition)(boxRef.value, props);
       (0, _vue.watch)(() => props.position, (newVal, oldVal) => {
@@ -2942,22 +3098,34 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
       }
     };
 
-    // 切换tab页
+    /**
+     * @description 切换tab页
+     * @param {Object} pane 切换后的 tab pane 对象
+     */
     function handleChange(pane) {}
 
-    // 切换类型
+    /**
+     * @description 切换类型，重置当前数据源类型对象与表单输入
+     * @param {Number} index 新选中的数据源类型在 dataSourceTypeList 中的索引
+     */
     function changeType(index) {
       dataSourceType.value = dataSourceTypeList.value[index];
       dataSource.url = "";
       dataSource.name = "";
     }
 
-    //选择文件
+    /**
+     * @description 选择文件回调，将新选择的文件追加到文件列表
+     * @param {Object} file kq-upload 组件返回的文件对象
+     */
     function changeFile(file) {
       fileList.value.push(file);
     }
 
-    // 删除文件
+    /**
+     * @description 删除文件，依据 uid 从文件列表中移除指定文件
+     * @param {Object} file 待删除的文件对象
+     */
     function removeFile(file) {
       fileList.value.forEach((item, index) => {
         if (item.uid === file.uid) {
@@ -2966,14 +3134,14 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
       });
     }
 
-    //清空所有文件
+    /** @description 清空所有文件，重置上传组件并清空文件列表 */
     function removeFiles() {
       upload_ref.value.$refs.child.clearFiles();
       upload_btn_ref.value.$refs.child.clearFiles();
       fileList.value = [];
     }
 
-    //加载文件
+    /** @description 加载文件：并发解析所有已选文件，成功后清空列表，失败则提示 */
     function loadFiles() {
       loadingFile.value = true;
       let promiseList = [];
@@ -2994,7 +3162,7 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
       });
     }
 
-    //加载URL
+    /** @description 加载URL：去除 url 前后空格后调用 ViewModel.parseDataSource 解析 */
     function loadURL() {
       dataSource.url = dataSource.url.trim();
       viewModel.parseDataSource({
@@ -3004,13 +3172,13 @@ var _default = exports.A = /*@__PURE__*/Object.assign(__default__, {
       }, props.loadCallback, props.loadCustom);
     }
 
-    // 重置
+    /** @description 重置 URL 加载表单：清空 url 与 name 字段 */
     function reset() {
       dataSource.url = "";
       dataSource.name = "";
     }
 
-    // 销毁
+    /** @description 组件销毁前钩子（预留清理逻辑） */
     (0, _vue.onBeforeUnmount)(() => {});
     __expose({});
     return (_ctx, _cache) => {
@@ -3455,11 +3623,11 @@ Object.defineProperty(exports, "__esModule", ({
   value: true
 }));
 exports.kq_npm_client_leaflet_vue = exports.kq_npm_client_common_vue = exports.kq_npm_client3d_webgl_vue = void 0;
-let kq_npm_client_common_vue = exports.kq_npm_client_common_vue = window.kq_npm_client_common_vue = window.kq_npm_client_common_vue || {};
+const kq_npm_client_common_vue = exports.kq_npm_client_common_vue = window.kq_npm_client_common_vue = window.kq_npm_client_common_vue || {};
 __webpack_require__.g.kq_npm_client_common_vue = kq_npm_client_common_vue;
-let kq_npm_client_leaflet_vue = exports.kq_npm_client_leaflet_vue = window.kq_npm_client_leaflet_vue = window.kq_npm_client_leaflet_vue || {};
+const kq_npm_client_leaflet_vue = exports.kq_npm_client_leaflet_vue = window.kq_npm_client_leaflet_vue = window.kq_npm_client_leaflet_vue || {};
 __webpack_require__.g.kq_npm_client_leaflet_vue = kq_npm_client_leaflet_vue;
-let kq_npm_client3d_webgl_vue = exports.kq_npm_client3d_webgl_vue = window.kq_npm_client3d_webgl_vue = window.kq_npm_client3d_webgl_vue || {};
+const kq_npm_client3d_webgl_vue = exports.kq_npm_client3d_webgl_vue = window.kq_npm_client3d_webgl_vue = window.kq_npm_client3d_webgl_vue || {};
 __webpack_require__.g.kq_npm_client3d_webgl_vue = kq_npm_client3d_webgl_vue;
 
 /***/ })