web-component-gallery 2.3.3 → 2.3.5

package/lib/amap-draw/index.jsx

@@ -8,36 +8,38 @@ const BASE_IP = process.env.VUE_APP_STATIC_URL || location.origin
 
 // 统一配置管理
 const CONFIG = {
+  // 定义绘制类型与高德地图对应对象类型的映射关系
   drawTypes: {
-    point: 'marker',
-    line: 'polyline', 
-    polygon: 'polygon'
+    point: 'marker',    // 点标记
+    line: 'polyline',   // 折线
+    polygon: 'polygon'  // 多边形
   },
+  // 地图图层类型：电子地图和卫星图
   layers: ['电子', '卫星']
 }
 
 export const AmapDrawProps = {
-  // 地图容器实例名称
+  // 地图容器DOM元素ID
   drawEl: PropTypes.string.def('AmapDraw'),
-  // 绘制类型
+  // 当前绘制类型：point(点)/line(线)/polygon(面)
   drawType: PropTypes.string.def('point'),
-  // 绘制图标
+  // 点标记的图标路径
   drawIcon: PropTypes.any.def(`${BASE_IP}/poi/poi-marker-default.png`),
-  // 绘制个数
+  // 允许绘制的最大数量
   drawCount: PropTypes.number.def(1),
-  // 绘制物配置项
+  // 绘制物的自定义配置项（如颜色、大小等）
   drawOptions: PropTypes.object.def({}),
-  // 绘制物信息
-  drawInfo: PropTypes.object,
-  // 所有不同类型绘制物信息 格式: { point: ([] || {}), line: ([] || {}) }
+  // 当前绘制物的信息（坐标、地址等）
+  drawInfo: PropTypes.oneOfType([PropTypes.object, PropTypes.string]),
+  // 包含所有类型绘制物信息的对象，格式: { point: [], line: [] }
   drawInfoAll: PropTypes.object,
-  // 限制区域
-  drawLimitArea: PropTypes.oneOfType([PropTypes.object, PropTypes.string]),
-  // 限制区域样式配置
+  // 限制绘制区域的边界坐标数组
+  drawLimitArea: PropTypes.oneOfType([PropTypes.array, PropTypes.string]),
+  // 限制区域的样式配置
   drawLimitAreaOptions: PropTypes.object.def({}),
-  // 纯地图展示数据
+  // 是否为纯展示模式（不显示控制按钮）
   isExhibition: PropTypes.bool.def(false),
-  // 自定义绘制操作
+  // 自定义绘制操作按钮
   drawButtonOperate: PropTypes.array
 }
 
@@ -47,221 +49,286 @@ export default {
   
   data() {
     return {
-      // 地图实例
+      // 高德地图实例引用
       amap: null,
-      // 地图存储商店
+      // 地图服务存储实例
       amapStore: null,
+      // 限制绘制区域的多边形对象
       drawArea: null,
+      // 当前绘制的图层对象
       drawLayers: null,
+      // 鼠标绘制工具实例
       drawMouseTool: null,
+      // 绘制操作按钮配置
       drawOperates: [
         { type: 'primary', text: '绘制', event: { click: () => this.handleDrawStart() } },
         { text: '清除', event: { click: this.handleDrawClear } },
         { type: 'primary', text: '保存', event: { click: this.handleDrawSave } },
         { text: '取消', event: { click: this.handleDrawReset } }
       ],
-      // 地图类型
+      // 地图显示类型：0-电子地图，1-卫星图
       amapType: 1,
-      // 卫星图
+      // 卫星图层对象
       amapSatellite: null,
-      //记录当前活跃操作的下标，-1表示无活跃操作
+      // 记录当前活跃操作的下标，-1表示无活跃操作
       activeOperateIndex: -1
     }
   },
 
   computed: {
+    // 绘制图层信息的计算属性，用于获取和设置绘制结果
     drawLayersInfo: {
-      get() { return this.drawInfo },
+      get() { return transferData(this.drawInfo, 'Object') },
       set(newValue) { 
+        // 触发外部事件，传递绘制的图层信息
         this.$emit('getAMapLayersInfo', this.initDrawInfo(newValue))
       }
     }
   },
 
   watch: {
+    // 监听绘制信息变化，当变化时重新渲染对应类型的绘制图层
     drawInfo: {
       handler(newVal) { newVal && this.echoDrawLayers(this.drawType) },
       deep: true
     },
+    // 监听所有绘制信息变化，重新渲染全部绘制图层
     drawInfoAll(newValue) { newValue && this.echoDrawLayers() },
-    // 检测options覆盖物配置是否更改，更改后要同步到地图上
+    // 监听绘制选项变化，更新已存在的覆盖物样式
     drawOptions(newValue) { Object.keys(newValue).length && this.setOverlayOptions(newValue) },
+    // 监听限制区域变化，重新设置限制区域
     drawLimitArea(newValue) { newValue && this.setDrawLimitArea() }
   },
 
   async mounted() {
+    // 获取高德地图实例
     this.amapStore = await getAMapInstance()
+    // 初始化地图容器
     this.amap = this.amapStore.initMap(this.drawEl)
+    // 初始化地图相关组件
     this.initMap()
     
+    // 如果提供了自定义操作按钮，则合并到默认按钮中
     if (this.drawButtonOperate?.length) {
       this.drawOperates = this.drawButtonOperate.concat(this.drawOperates.slice(2))
     }
     
+    // 渲染已有的绘制图层
     this.echoDrawLayers(this.drawType)
-    // 如有限制区域，则描绘在地图上
+    // 如果设置了限制区域，则在地图上绘制限制区域
     this.drawLimitArea && this.setDrawLimitArea()
   },
 
   beforeDestroy() {
+    // 组件销毁前清理资源
     this.cleanupResources()
   },
 
   methods: {
-    // 初始化地图实例
+    // 初始化地图实例及相关组件
     initMap() {
       this.amap = this.amapStore.initMap(this.drawEl)
+      // 创建卫星图层
       this.amapSatellite = new this.amapStore.AMap.TileLayer.Satellite()
+      // 将卫星图层添加到地图
       this.amap.add(this.amapSatellite)
     },
 
     // 根据绘制类型初始化绘制属性
     initDrawInfo(newValue) {
+      // 如果传入了新值则直接返回，否则根据绘制类型返回默认结构
       return Object.keys(newValue).length ? newValue : 
         this.drawType === 'point' ? 
           { longitude: null, latitude: null, address: null } : 
           { range: null }
     },
 
-    // 开始绘制
+    // 开始绘制操作
     handleDrawStart(i = 0) {
+      // 检查是否已在绘制模式
       if (this.activeOperateIndex === i) return this.$message.warning('已处于绘制模式！')
+      
       // 如果存在其他活跃操作项，先关闭并重置状态
       if (this.activeOperateIndex !== -1 && this.activeOperateIndex !== i) {
         this.drawMouseTool.close()
         this.updateDrawOperateState('primary')
       } 
 
+      // 设置当前活跃操作索引
       this.activeOperateIndex = i
+      // 更新操作按钮状态为危险（红色）
       this.updateDrawOperateState('danger')
+      // 初始化绘制工具
       this.initDrawTool()
     },
 
     // 处理绘制完成事件
     handleDrawComplete(drawObject) {
+      // 检查绘制对象是否超出限制区域
       if (this.isOutOfBoundary(drawObject)) return
-
+    
+      // 更新绘制图层
       this.updateDrawLayers(drawObject)
-
+    
+      // 检查是否已完成所有绘制
       if (this.isDrawComplete()) this.finishDrawing()
     },
-
+    
+    // 检查绘制对象是否超出边界限制
     isOutOfBoundary(obj) {
+      // 如果没有设置限制区域或者对象在边界内，则返回false
       if (!this.drawArea || this.checkInBoundary(obj)) return false
-      
+          
+      // 移除超出边界的对象
       this.amap.remove(obj)
       this.$message.error('未在范围内描绘！')
       return true
     },
-
-    // 检查绘制是否完成
+    
+    // 检查绘制是否完成（达到最大绘制数量）
     isDrawComplete() {
       return this.drawLayers && 
         (this.drawLayers.length === this.drawCount || this.drawCount === 1)
     },
-
-    // 结束绘制
+    
+    // 结束绘制流程
     finishDrawing() {
+      // 关闭鼠标绘制工具
       this.drawMouseTool.close()
+      // 恢复操作按钮状态
       this.updateDrawOperateState('primary')
+      // 重置活跃操作索引
       this.activeOperateIndex = -1
       this.$message.success('绘制结束！')
     },
 
-    // 更新绘制物
+    // 更新绘制图层（支持单个或多个绘制对象）
     updateDrawLayers(drawObject) {
+      // 如果允许绘制多个对象，则将新对象追加到现有对象数组中，否则直接替换
       this.drawLayers = this.drawCount > 1 ? 
         (this.drawLayers || []).concat(drawObject) : 
         drawObject
 
-      // 实时保存绘制
+      // 实时保存绘制结果
       this.assignDrawLayers(this.drawType)
     },
 
-    // 清除绘制
+    // 清除当前绘制的所有图层
     handleDrawClear() {
+      // 清理地图上的所有覆盖物
       this.cleanOverlays()
+      // 重置绘制图层数组
       this.drawLayers = null
+      // 重置绘制图层信息
       this.drawLayersInfo = {}
     },
 
-    // 保存绘制
+    // 保存当前绘制结果
     handleDrawSave() {
+      // 如果没有绘制任何内容，则重置绘制状态
       if (!this.drawLayers) {
         return this.handleDrawReset()
       }
+      // 分配绘制图层信息
       this.assignDrawLayers(this.drawType)
     },
 
-    // 取消绘制
+    // 取消绘制操作
     handleDrawReset() {
+      // 直接调用清除方法
       this.handleDrawClear()
     },
 
-    // 搜索地址选择
+    // 处理搜索结果选择
     searchChoose(searchMarker, searchInfo) {
+      // 清除当前绘制内容
       this.handleDrawClear()
+      // 将选中的标记添加到地图
       searchMarker.setMap(this.amap)
+      // 设置地图缩放级别和中心点
       this.amap.setZoomAndCenter(15, searchMarker.getPosition())
+      // 如果是点类型绘制，则更新绘制信息
       this.drawType === 'point' && (this.drawLayersInfo = searchInfo)
     },
 
-    // 设置覆盖物参数
+    // 设置覆盖物的参数选项
     setOverlayOptions(options) {
+      // 如果没有绘制图层则直接返回
       if (!this.drawLayers) return
       
+      // 将绘制图层转换为数组以便统一处理
       const layers = Array.isArray(this.drawLayers) ? this.drawLayers : [this.drawLayers]
+      // 为每个图层设置新的选项
       layers.forEach(item => item.setOptions(options))
     },
 
-    // 设置绘制限制区域
+    /**
+     * 设置绘制限制区域（在指定区域内才能进行绘制）
+     */
     setDrawLimitArea() {
-      let areaRange = []
       try {
-        areaRange = JSON.parse(this.drawLimitArea)
-      } catch {
-        areaRange = this.drawLimitArea
+        // 验证限制区域数据是否存在
+        if (!this.drawLimitArea) return
+
+        // 转换区域范围数据为数组格式
+        const areaRange = transferData(this.drawLimitArea, 'Array')
+
+        // 移除现有的限制区域
+        if (this.drawArea) {
+          this.amap.remove(this.drawArea)
+          this.drawArea = null
+        }
+
+        // 设置新的地图区域
+        this.setMapArea(areaRange)
+
+        // 验证现有覆盖物是否在区域内
+        this.validateOverlays()
+      } catch (error) {
+        console.error('设置绘制限制区域失败:', error)
       }
-      
-      this.drawArea && this.amap.remove(this.drawArea)
-      this.setMapArea(areaRange)
-      this.validateOverlays()
     },
 
-    // 设置地图区域范围
+    // 设置地图限制区域范围
     setMapArea(jurisdictionRange) {
+      // 创建限制区域多边形
       this.drawArea = new this.amapStore.AMap.Polygon({
         map: this.amap,
         path: jurisdictionRange,
-        extData: 'Area',
-        strokeWeight: 6,
-        ...this.drawLimitAreaOptions
+        extData: 'Area',      // 标记为区域类型，避免被误删
+        strokeWeight: 6,      // 边框粗细
+        ...this.drawLimitAreaOptions  // 应用用户自定义样式
       })
       
+      // 获取限制区域中心点并设置地图视图
       const { lng, lat } = this.drawArea.getBounds().getCenter()
       this.amap.setZoomAndCenter(15, [lng, lat])
     },
 
-    // 验证覆盖物是否在边界内
+    // 验证覆盖物是否在边界内，不在边界内的覆盖物会被移除
     validateOverlays() {
+      // 获取地图上所有覆盖物
       this.amap?.getAllOverlays().forEach(layer => {
+        // 排除限制区域本身，并检查是否在边界内
         if (layer.getExtData() !== 'Area' && !this.checkInBoundary(layer)) {
           this.removeOverlay(layer)
         }
       })
     },
 
-    // 检查是否在边界内
+    // 检查对象是否在边界内
     checkInBoundary(object) {
       const type = this.drawType
+      // 根据绘制类型选择相应的边界检查方法
       return type === 'line' ? 
         this.isLineInBoundary(object) : 
         this.isPointInBoundary(object)
     },
 
-    // 检查线段是否在边界内
+    // 检查线段是否完全在边界内
     isLineInBoundary(polyline) {
       const paths = polyline.getPath()
+      // 检查线段的所有点是否都在边界内
       return paths.every(point => this.isPointInBoundary(point))
     },
 
@@ -269,22 +336,27 @@ export default {
     isPointInBoundary(point) {
       let position
       try {
+        // 尝试获取点的位置信息
         position = point.getPosition()
       } catch {
+        // 如果获取失败，则直接使用传入的点作为位置
         position = point
       }
+      // 使用高德地图的几何工具判断点是否在多边形内
       return this.amapStore.AMap.GeometryUtil.isPointInRing(
           position, 
           this.drawArea.getPath()
         )
     },
 
-    // 移除覆盖物
+    // 移除超出边界的覆盖物
     removeOverlay(layerItem) {
+      // 从地图上移除覆盖物
       this.amap.remove(layerItem)
       this.$message.error('未在区域范围内，请重新描绘！')
       
       try {
+        // 如果绘制图层是数组，则从中移除对应的元素
         if (Array.isArray(this.drawLayers)) {
           const index = this.drawLayers.findIndex(
             layer => layer.getExtData() === layerItem.getExtData()
@@ -294,6 +366,7 @@ export default {
           }
           return
         }
+        // 如果不是数组，直接重置绘制图层
         this.drawLayers = null
         this.drawLayersInfo = {}
       } catch (error) {
@@ -303,40 +376,49 @@ export default {
 
     // 初始化绘制工具
     initDrawTool() {
+      // 创建鼠标绘制工具实例
       this.drawMouseTool = new this.amapStore.AMap.MouseTool(this.amap)
+      // 清除之前的绘制内容
       this.handleDrawClear()
+      // 准备绘制图层
       this.prepareDrawLayers(this.drawType)
 
-      // 准备绘制环境
+      // 监听绘制完成事件
       this.drawMouseTool.on('draw', ({ obj }) => {
         this.handleDrawComplete(obj)
       })
     },
 
-    // 准备绘制图层
+    // 准备绘制图层（根据绘制类型设置默认选项）
     async prepareDrawLayers(drawType) {
+      // 根据绘制类型设置默认选项
       const defaultOptions = drawType === 'point' ? {
-            anchor: 'bottom-center',
-            icon: await this.amapStore.setIcon(this.drawIcon)
-          } : { strokeWeight: 8 }
+            anchor: 'bottom-center',  // 点标记锚点位置
+            icon: await this.amapStore.setIcon(this.drawIcon)  // 设置图标
+          } : { strokeWeight: 8 }  // 线条宽度
       
+      // 根据绘制类型启动相应的绘制工具
       this.drawMouseTool[CONFIG.drawTypes[drawType]]({
         ...defaultOptions,
-        ...this.drawOptions
+        ...this.drawOptions  // 合并用户自定义选项
       })
     },
 
-    // 分配图层数据
+    // 根据绘制类型分配图层数据
     assignDrawLayers(drawType) {
+      // 根据绘制类型调用相应的处理方法
       drawType === 'point' ? this.handlePointDraw() : this.handleShapeDraw()
     },
 
-    // 处理点绘制
+    // 处理点类型绘制，获取点的详细地址信息
     handlePointDraw() {
+      // 获取点的经纬度坐标
       const { lng, lat } = this.drawLayers.getPosition()
       const position = { longitude: lng, latitude: lat }
       
+      // 通过坐标获取详细地址信息
       this.amapStore.getMapAddress(position, address => {
+        // 合并坐标和地址信息
         this.drawLayersInfo = {
           ...position,
           ...address
@@ -344,27 +426,34 @@ export default {
       })
     },
 
-    // 处理形状绘制
+    // 处理形状类型绘制（线或多边形），提取路径坐标
     handleShapeDraw() {
+      // 将路径转换为经纬度坐标数组
       const range = this.drawLayers.getPath().map(({ lng, lat }) => [lng, lat])
+      // 更新绘制图层信息
       this.drawLayersInfo = { range }
     },
 
-    // 回显绘制图层
+    // 回显绘制图层（根据已有数据重新渲染地图上的绘制内容）
     echoDrawLayers(drawType) {
+      // 检查地图实例是否存在
       if (!this.amapStore || !this.amap) return
       
+      // 清理现有覆盖物
       this.cleanOverlays()
       
+      // 根据是否有全部绘制信息决定渲染方式
       this.drawInfoAll ? 
         this.renderAllDrawLayers() : 
         this.renderSingleDrawLayer(drawType)
       
+      // 如果没有活跃操作，则自动调整地图视野以适应所有图层
       if (this.activeOperateIndex === -1) setTimeout(this.amap.setFitView(), 0)
     },
 
-    // 清理覆盖物
+    // 清理地图上除限制区域外的所有覆盖物
     cleanOverlays() {
+      // 获取地图上所有覆盖物并移除非区域类的覆盖物
       this.amap?.getAllOverlays().forEach(layer => {
         if (layer.getExtData() !== 'Area') {
           this.amap.remove(layer)
@@ -372,91 +461,101 @@ export default {
       })
     },
 
-    // 渲染所有绘制图层
+    // 渲染所有绘制图层（遍历所有类型的绘制信息并渲染）
     renderAllDrawLayers() {
       for (const key in this.drawInfoAll) {
         const isArray = Array.isArray(this.drawInfoAll[key])
         
         if (isArray) {
+          // 如果是数组类型，则遍历数组中的每一项进行渲染
           this.drawInfoAll[key].forEach((item, index) => {
             this.renderDrawLayer(item, key, index)
           })
           return
         }
 
+        // 如果不是数组，则直接渲染单个项目
         this.renderDrawLayer(this.drawInfoAll[key], key)
       }
     },
 
     // 渲染单个绘制图层
     renderSingleDrawLayer(drawType) {
+      // 使用当前绘制图层信息进行渲染
       this.renderDrawLayer(this.drawLayersInfo, drawType)
     },
 
-    // 渲染绘制图层
+    // 渲染单个绘制图层（根据类型创建相应的地图对象）
     async renderDrawLayer(drawItem, type, index = 0) {
       if (!drawItem) return
       
       const { longitude, latitude, range, options: innerOptions } = drawItem
       
-      // 验证必要参数
+      // 验证必要参数是否存在
       if (!((longitude && latitude) || range)) return
     
-      // 创建图层选项
+      // 合并图层选项（基础选项、用户选项和内部选项）
       const layerOptions = {
-        extData: `draw${type}${index}`,
-        ...this.drawOptions,
-        ...innerOptions
+        extData: `draw${type}${index}`,  // 设置扩展数据标识
+        ...this.drawOptions,             // 用户自定义选项
+        ...innerOptions                  // 内部选项
       }
       
       let layerItem = null
       
-      // 根据类型创建不同的图层
+      // 根据绘制类型创建不同的地图对象
       if (type === 'point') {
+        // 创建点标记
         layerItem = await this.amapStore.setMarker(this.drawIcon, {
-          position: [longitude, latitude],
-          ...layerOptions
+          position: [longitude, latitude],  // 设置点位置
+          ...layerOptions                   // 应用图层选项
         })
       } else {
+        // 创建线或面对象
         const options = {
-          path: transferData(range, 'Array'), 
-          strokeWeight: 8,
-          ...layerOptions
+          path: transferData(range, 'Array'),  // 路径坐标
+          strokeWeight: 8,                     // 线宽
+          ...layerOptions                      // 应用图层选项
         }
         
-        // 根据类型创建线或面
+        // 根据类型创建线或多边形
         layerItem = type === 'line' 
-          ? new this.amapStore.AMap.Polyline(options) 
-          : new this.amapStore.AMap.Polygon(options)
+          ? new this.amapStore.AMap.Polyline(options)   // 折线
+          : new this.amapStore.AMap.Polygon(options)    // 多边形
       }
       
-      // 将图层添加到地图
+      // 将创建的地图对象添加到地图上
       layerItem?.setMap(this.amap)
     },
 
-    // 切换地图类型
+    // 切换地图显示类型（电子地图/卫星图）
     onLayersSwitch(key) {
+      // 更新地图类型状态（0为电子地图，1为卫星图）
       this.amapType = key
+      // 根据选择的类型显示或隐藏卫星图层
       this.amapType ? this.amapSatellite.show() : this.amapSatellite.hide()
     },
 
-    // 更改操作状态
+    // 更新绘制操作按钮的状态（如颜色变化）
     updateDrawOperateState(type) {
-      // 创建新的操作数组副本
+      // 创建新的操作数组副本以避免直接修改原数组
       const newOperates = [...this.drawOperates]
       
-      // 更新指定索引的操作项类型
+      // 更新指定索引的操作项类型（例如：primary/danger）
       newOperates[this.activeOperateIndex] = {
         ...newOperates[this.activeOperateIndex],
         type
       }
       
+      // 更新操作按钮数组
       this.drawOperates = newOperates
     },
 
-    // 清理资源
+    // 清理组件使用的资源，防止内存泄漏
     cleanupResources() {
+      // 清除地图上的所有绘制内容
       this.handleDrawClear()
+      // 关闭并清理鼠标绘制工具
       this.drawMouseTool && this.drawMouseTool.close()
     }
   },
@@ -492,4 +591,4 @@ export default {
       </div>
     )
   }
-}
+}