# WMS Map React 组件 (WMS 地图 React 元件) ## 概述 `@rytass/wms-map-react-components` 提供交互式仓库空间编辑元件，基于ReactFlow (XYFlow)，支持背景图、曲线/路径估值、梯度编辑和历史管理。 ## 快速入门 ### 安装 npm install @rytass/wms-map-react-components @xyflow/react @mezzanine-ui/react ### 基本使用从 '@rytass/wms-map-react-components' 导入 { WMSMapModal, ViewMode }; 函数应用程序（）{ const [isOpen, setIsOpen] = useState(false); 返回（ <> setIsOpen(false)} viewMode={ViewMode.编辑} onSave={(mapData) => { console.log('已保存：', mapData); // 提交到头部 }} /> ）； } ## 核心组件 ### WMSMapModal 主要的地图编辑模式框：接口 WMSMapModalProps { 打开：布尔值； onClose: () => void; 视图模式？：视图模式； // 编辑 |查看（默认编辑）标题？：字符串； // 模态框标题 colorPalette？：字符串[]； // 区域颜色选项 onNodeClick？：（信息：WMSNodeClickInfo）=> void； onSave?: (mapData: 地图) => void; onBreadcrumbClick？：（warehouseId：字符串，索引：数字）=> void； onNameChange?: (名称: 字符串) => Promise; // 名称变更回呼初始节点？：FlowNode[]；初始边缘？：FlowEdge[]；调试模式？：布尔值； maxFileSizeKB？：数字； // 背景图大小限制（默认30720 = 30MB）仓库ID？：字符串[]； // 以太坊 ID 列表（用于面包屑） // 必要回呼：处理图片上传 onUpload: (文件: File[]) => Promise; // 回传上传后的文件名阵列 // 任选：获取完整图片网址 getFilenameFQDN?: (文件名: 字符串) => Promise<字符串> |细绳; } ### 子元素元件| 说明 ---|--- `WMSMapHeader` | 工具列与标题 `WMSMapContent` | 内容优化与编辑控制 `面包屑` | 交通体系导航 `上下文菜单` | 右键菜单 `工具栏` | 编辑工具列 ### 节点类型节点 | 说明 ---|--- `图像节点` | 背景图节点 `矩形节点` | 战略区域节点 `路径节点` | 路径/作业节点 ## 枚举 ### 查看模式枚举视图模式{ EDIT = 'EDIT', // 编辑模式 VIEW = 'VIEW', // 检视模式 } ### 编辑模式枚举编辑模式{ Background = 'BACKGROUND', // 背景图编辑 LAYER = 'LAYER', // 区域层编辑 } ### 绘图模式枚举绘图模式{ NONE = 'NONE', // 无光照 RECTANGLE = 'RECTANGLE', // 估值误差 PEN = 'PEN', // 自由强度/路径 } ### 图层绘图工具枚举图层绘图工具 { SELECT = 'SELECT', // 一些工具 RECTANGLE = 'RECTANGLE', // 几何工具 PEN = 'PEN', // 钢笔工具 } ### 地图范围类型枚举 MapRangeType { RECTANGLE = 'RECTANGLE', // 几何区域 POLYGON = 'POLYGON', // 烘焙区域 } ### 地图范围颜色枚举 MapRangeColor { 红色='红色'，黄色='黄色'，绿色='绿色'，蓝色='蓝色'，黑色=“黑色”， } ## 数据结构 ### ID 型别别名导出类型 ID = 字符串； ### 地图接口映射{ id：身份证号；背景：MapBackground[]；范围：MapRange[]； // 地图矩形范围 |地图多边形范围 } 接口地图背景{ id：字符串；文件名：字符串； // 文件名称（非完整 URL）宽度：数量；高度：数字； x：数字； y：数字； } 接口 MapRectangleRange { 类型：MapRangeType.RECTANGLE； // '矩形' id：字符串； x：数字； y：数字；宽度：数量；高度：数字；颜色: 字符串; } 接口MapPolygonRange { 类型：MapRangeType.POLYGON； // '多边形' id：字符串；点：MapPolygonRangePoint[]；颜色: 字符串; } 接口MapPolygonRangePoint { x：数字； y：数字； } ### WMSNodeClickInfo 输入 WMSNodeClickInfo = |图像节点点击信息 |矩形节点点击信息 |路径节点点击信息； // 基础介面接口 NodeClickInfo { id：字符串；类型：字符串；位置：{ x：数字； y：数字}； zIndex？：数字；选择？：布尔值； } 接口 ImageNodeClickInfo 扩展 NodeClickInfo { 类型：'图像节点'；图像数据：{ 文件名：字符串；尺寸：{ 宽度：数量；高度：数字}；原始尺寸：{ 宽度：数量；高度：数字}；图片网址：字符串； }; 地图背景：地图背景； // 可直接传给远程的格式 } 接口 RectangleNodeClickInfo 扩展 NodeClickInfo { 类型：'矩形节点'；矩形数据：{ 颜色: 字符串; 尺寸：{ 宽度：数量；高度：数字}； }; 地图矩形范围：地图矩形范围； // 可直接传给远程的格式 } 接口 PathNodeClickInfo 扩展 NodeClickInfo { 类型：'路径节点'；路径数据：{ 颜色: 字符串; 笔画宽度：数字； pointCount：数量；点：{ x：数字； y: 数字 }[]; 界限：{ minX：数字； minY：数量； maxX：数量； maxY：数量； } |无效的; }; 地图多边形范围：地图多边形范围； // 可直接传给远程的格式 } ## 实用函数 ###数据转换导入{ 变换节点到点击信息，将节点变换为地图数据，转换ApiDataToNodes，验证地图数据，从Api加载MapData，计算多边形边界，计算NodeZIndex，日志地图数据，日志节点数据，来自“@rytass/wms-map-react-components”； // ReactFlow 节点 → 点击资讯 const clickInfo = TransformNodeToClickInfo(节点); // ReactFlow 节点 → 地图资料 (表单格式) const mapData =transformNodesToMapData(节点); // API资料→ReactFlow节点（支持自订图片URL产生器） const 节点 =transformApiDataToNodes(apiData); constnodesWithCustomUrl=transformApiDataToNodes(apiData,(文件名)=>{ 返回 `https://cdn.example.com/images/${filename}`; }); // 验证地图资料格式 const isValid = validateMapData(mapData); // 辅助函数：计算仓库边界 const 边界 = 计算多边形边界（点）； // 回传: { minX, maxX, minY, maxY, width, height } // 辅助函数：计算节点zIndex const zIndex =calculateNodeZIndex(existingNodes, '矩形节点'); // 调试工具：整理输出数据到控制台 logMapData(mapData); // 输出完整地图资料 logNodeData(节点); // 产出单一节点详细资讯 ## 完整示例从 'react' 导入 { useState, useCallback }; 导入{ WMSMapModal, 视图模式, 将节点变换为地图数据，转换ApiDataToNodes， WMSNodeClickInfo, 地图, 来自“@rytass/wms-map-react-components”；函数 WarehouseMapEditor() { const [isOpen, setIsOpen] = useState(false); const [mapData, setMapData] = useState(空); // 从传入加载地图资料 const loadMapData = async () => { const response = wait fetch('/api/warehouse/map'); const data =等待response.json(); 设置地图数据（数据）； }; // 上传图片到云端（必要回呼） const handleUpload = useCallback(async (files: File[]): Promise => { const formData = new FormData(); files.forEach((file) => formData.append('files', file)); const 响应 = 等待 fetch('/api/warehouse/upload', { 方法：'POST'，正文：表单数据， }); const { 文件名 } = 等待响应.json(); 返回文件名； // 回传文件名数组 }, []); // 获取图片完整网址（可选） const getFilenameFQDN = useCallback((文件名：字符串) => { 返回 `https://cdn.example.com/warehouse-images/${filename}`; }, []); // 存储地图数据到本地 const handleSave = useCallback(async (data: Map) => { 等待 fetch('/api/warehouse/map', { 方法：'放置'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify（数据）， }); 设置地图数据（数据）； setIsOpen(假); }, []); // 处理区域点击 const handleNodeClick = useCallback((info: WMSNodeClickInfo) => { if (info.type === '矩形节点') { // 获取前端格式的数据 console.log('点击区域：', info.mapRectangleRange); // 可以导航到该区域的库存页面 } }, []); 返回（

<按钮 onClick={() => { loadMapData(); setIsOpen(真); }}> 编辑以太坊地图 setIsOpen(false)} viewMode={ViewMode.编辑} title="仓库A地图" 调色板={[ '#FF6B6B', // 红色 - 危险品区 '#4ECDC4', // 青 - 冷藏区 '#45B7D1', // 蓝 - 将军区 '#96CEB4', // 绿 - 出货区 '#FFEAA7', // 黄 - 暂存区 ]} 初始节点={地图数据？ TransformApiDataToNodes(mapData, getFilenameFQDN) : 未定义} onSave={handleSave} onNodeClick={handleNodeClick} onUpload={处理上传} getFilenameFQDN={getFilenameFQDN} maxFileSizeKB={30720} // 30MB（默认值） warehouseIds={['10001', '10001A']} />

）； } // 唯读检视元件（VIEW模式不需要onUpload）函数 WarehouseMapViewer({ 地图数据 }: { 地图数据: 地图 }) { const [selectedZone, setSelectedZone] = useState<字符串 |空>(空); const getFilenameFQDN = (文件名: 字符串) => `https://cdn.example.com/warehouse-images/${文件名}`; 返回（ {}} 视图模式={ViewMode.VIEW} 初始节点={transformApiDataToNodes(mapData, getFilenameFQDN)} onUpload={async () => []} // VIEW模式下可用空实作 onNodeClick={（信息）=> { if (info.type === '矩形节点') { setSelectedZone(info.id); } }} /> ）； } ## 多体系导航函数 WarehouseNavigator() { const [面包屑，setBreadcrumb] = useState([ { id: 'warehouse-1', name: '主仓库' }, ]); const handleBreadcrumbClick = (warehouseId: 字符串, 索引: 数字) => { // 导航到特定体系 setBreadcrumb(breadcrumb.slice(0, 索引 + 1)); loadWarehouseMap(warehouseId); }; const handleZoneClick = (信息: WMSNodeClickInfo) => { if (info.type === '矩形节点') { // 进入子区域（需手机维护区域名称对应） setBreadcrumb([...breadcrumb, { id: info.id, name: `区域 ${info.id}` }]); loadWarehouseMap(info.id); } }; 返回（ {}} 视图模式={ViewMode.VIEW} onBreadcrumbClick={handleBreadcrumbClick} onNodeClick={handleZoneClick} /> ）； } ## 常量 > **注意：** Constants 目前未从主入口导出，若需使用请直接从 Constants 路径导入： > > > 从 '@rytass/wms-map-react-components/constants' 导入 { UI_CONFIG, CANVAS_CONFIG }; > // 现状 DEFAULT_IMAGE_WIDTH // 300 DEFAULT_IMAGE_HEIGHT // 200 DEFAULT_RECTANGLE_WIDTH // 150 DEFAULT_RECTANGLE_HEIGHT // 100 // 颜色 DEFAULT_RECTANGLE_COLOR // '#3b82f6' SELECTION_BORDER_COLOR // '#3b82f6' DEFAULT_BACKGROUND_TOOL_COLOR // '#3b82f6' // 最小尺寸最小矩形尺寸 // 10 最小调整宽度 // 50 最小调整高度 // 30 // 文字标签 DEFAULT_RECTANGLE_LABEL // '几何区域' DEFAULT_PATH_LABEL // '路径区域' // 宽度 ACTIVE_OPACITY // 1 INACTIVE_OPACITY // 0.4 RECTANGLE_INACTIVE_OPACITY // 0.6 // 调整大小控制项尺寸调整大小控制大小 // 16 IMAGE_RESIZE_CONTROL_SIZE // 20 // 用户界面配置 UI_CONFIG.HISTORY_SIZE // 50（撤消/重做历史大小） UI_CONFIG.COLOR_CHANGE_DELAY // 800ms UI_CONFIG.STAGGER_DELAY // 100ms (图片上传间隔) UI_CONFIG.NODE_SAVE_DELAY // 50ms // 画布配置 CANVAS_CONFIG.MIN_ZOOM // 0.1 CANVAS_CONFIG.MAX_ZOOM // 4 CANVAS_CONFIG.DEFAULT_VIEWPORT // { x: 0, y: 0, 缩放: 1 } CANVAS_CONFIG.BACKGROUND_COLOR // '#F5F5F5' // 文件上传配置 UPLOAD_CONFIG.DEFAULT_MAX_FILE_SIZE_KB // 30720 (30MB) UPLOAD_CONFIG.SUPPORTED_MIME_TYPES // ['image/png', 'image/jpeg', ...] // 支持的图片类型 SUPPORTED_IMAGE_TYPES.ACCEPT // '图像/png,图像/jpeg,图像/jpg' SUPPORTED_IMAGE_TYPES.PATTERN // /^图像\/(png|jpeg|jpg)$/ SUPPORTED_IMAGE_TYPES.EXTENSIONS // ['png', 'jpg', 'jpeg'] //仓库ID DEFAULT_WAREHOUSE_IDS // ['10001', '10001A', '10002', '100002B', '100003', '100003B'] ## 依赖关系 **必填：** * `@xyflow/react` ^12.10.0 **对等依赖性：** * `@mezzanine-ui/react` * `@mezzanine-ui/react-hook-form-v2` * `react`, `react-dom` * `反应钩子形式` ## 故障排除 ### 地图无法显示确保ReactFlow Provider正确包装： // WMSMapModal 内部已包含 ReactFlowProvider // 不需要额外包装 ###背景图上传失败检查 `maxFileSizeKB` 设置，默认为 30720KB (30MB)。 ### 节点无法拖曳确认`viewMode`设为`ViewMode.EDIT`。 ## 反应钩子 `@rytass/wms-map-react-components` 提供以下内部 Hooks，用于地图编辑器的核心功能。 > **注意：** 这些 Hooks 目前为内部使用，未在主入口汇出。若需使用，请直接从相应文件导入： > > > 从 '@rytass/wms-map-react-components/hooks/use-context-menu' 导入 { useContextMenu } ； > ### 使用上下文菜单管理节点的右键菜单与布局排列操作。接口 UseContextMenuProps { id：字符串； // 节点ID 编辑模式：编辑模式； // 当前编辑模式是否可编辑：布尔值； // 是否可编辑节点类型？： '矩形节点' | '路径节点' | '图像节点'; } 接口 UseContextMenuReturn { contextMenu: { 可见: 布尔值; x：数字； y：数字}； handleContextMenu: (事件: React.MouseEvent) => void; 处理CloseContextMenu: () => void; 处理删除：() => void; 安排动作：{ onBringToFront: () => void; // 移至最上层 onBringForward: () => void; // 上移一层 onSendBackward: () => void; // 下移一层 onSendToBack: () => void; // 移至最下层 }; 安排状态：{ canBringToFront：布尔值； canBringForward：布尔值；可以向后发送：布尔值； canSendToBack：布尔值； }; getNodes: () => Node[]; setNodes: (节点: Node[] | ((节点: Node[]) => Node[])) => void; } const { contextMenu、handleContextMenu、arrangeActions } = useContextMenu({ id：节点ID，编辑模式：编辑模式.LAYER，是否可编辑：正确，节点类型：'矩形节点'， }); ### useDirectStateHistory 直接状态历史系统，支持Undo/Redo功能。接口 UseDirectStateHistoryOptions { maxHistorySize？：数字； // 预设50 调试模式？：布尔值； // 默认 false } 接口 UseDirectStateHistoryReturn { saveState: (节点: FlowNode[], 边: FlowEdge[], 操作: string, editMode: EditMode) => void; 撤消：() => { 节点：FlowNode[];边缘：FlowEdge[]；编辑模式：编辑模式 } |无效的; 重做：() => { 节点：FlowNode[];边缘：FlowEdge[]；编辑模式：编辑模式 } |无效的; 可以撤消：布尔值；可以重做：布尔值；初始化历史记录：（initialNodes：FlowNode []，initialEdges：FlowEdge []，editMode：EditMode）=> void；清除历史记录：() => void; getHistorySummary: () => HistorySummary; 历史？：历史状态[]； // debugMode 启用时可用当前索引？：数字； // debugMode 启用时可用 } 常量{ 保存状态，撤消，重做，可以撤消，可以重做，初始化历史记录， } = useDirectStateHistory({ maxHistorySize: 100, debugMode: false }); // 初始化初始化历史记录（节点，边，EditMode.LAYER）； // 保存操作后状态 saveState(节点，边，'添加矩形'，EditMode.LAYER); // 执行撤消 const prevState = 撤消(); 如果（上一个状态）{ setNodes(prevState.nodes); setEdges(prevState.edges); } ### 使用钢笔绘图钢笔工具缺乏/路径区域。接口 UsePenDrawingProps { 编辑模式：编辑模式；绘图模式：绘图模式； onCreatePath: (点: { x: 数字; y: 数字 }[]) => void; } 接口 UsePenDrawingReturn { 容器引用：React.RefObject; // 绑定到容器正在绘图：布尔值； // 是否存在短缺预览路径：{ x：数字； y: 数字 }[] |无效的; // 预览路径当前点：{ x：数字； y: 数字 }[]; // 已存在的点第一个点：{ x：数字； y: 数字 } |无效的; // 第一点（结束提示用）可以关闭：布尔值； // 是否可关闭（>=3点）强制完成：() => void; // 强制完成强度 } 常量{ 容器参考，是图画，预览路径, 可以关闭， } = 使用笔绘图({ 编辑模式：编辑模式.LAYER，绘图模式：绘图模式.PEN， onCreatePath: (点) => { // 建立左侧节点创建路径节点（点）； }, }); // 操作方式： // - 单击：添加点 // - 回转：完成并闭合路径 // - 点击第一个点：关闭路径 // - 输入：完成并关闭路径 // - Escape：取消无数 // - Shift + 点击：约束至45度角 ### 使用矩形绘图规划区域工具较少。接口 UseRectangleDrawingProps { 编辑模式：编辑模式；绘图模式：绘图模式； onCreateRectangle: (startX: 数字, startY: 数字, endX: 数字, endY: 数字) => void; } 接口 UseRectangleDrawingReturn { 容器引用：React.RefObject; 正在绘图：布尔值；预览矩形：{ x：数字； y：数字；宽度：数量；高度：数字； } |无效的; } 常量{ 容器参考，是图画，预览矩形, } = 使用矩形绘图({ 编辑模式：编辑模式.LAYER，绘图模式：绘图模式.RECTANGLE， onCreateRectangle: (x1, y1, x2, y2) => { 创建矩形节点（x1，y1，x2，y2）； }, }); // 操作方式： // - 按住滑鼠拖曳建立平面图 // - 放开滑鼠完成建立 // - 最大尺寸限制：MIN_RECTANGLE_SIZE ### 使用文本编辑节点文字标签编辑功能。接口 UseTextEditingProps { id：字符串； // 节点ID 标签：字符串； // 当前标签文字是否可编辑：布尔值； // 是否可编辑 onTextEditComplete?: (id: string, oldText: string, newText: string) => void; } 接口 UseTextEditingReturn { 正在编辑：布尔值；编辑文本：字符串； inputRef：React.RefObject; setEditingText: React.Dispatch>; handleDoubleClick: (事件: React.MouseEvent) => void; // 左侧开始编辑 handleKeyDown: (事件: React.KeyboardEvent) => void; // 键盘事件处理处理模糊：（）=>无效； // 失去焦保存 updateNodeData：（更新：记录<字符串，未知>）=> void； } 常量{ 正在编辑，编辑文本，输入参考，设置编辑文本，处理双击，处理按键按下，处理模糊， } = 使用文本编辑({ id：节点ID，标签：“A区”，是否可编辑：正确， onTextEditComplete: (id, oldText, newText) => { console.log(`节点${id}标签从 "${oldText}" 改为 "${newText}"`); saveState(节点, 边, '编辑标签', editMode); }, }); // 操作方式： // - 左侧节点：开始编辑 // - 输入：确认保存 // - Escape：取消编辑 // - 点击外部：自动保存 ### Hooks 使用注意事项 1. **必须在 ReactFlowProvider 内使用** ：所有钩子依赖 `useReactFlow` 2. **内部使用主控**：这些hooks主要提供WMS组件内部使用 3. **历史记录整合**：异构与编辑操作应搭配`useDirectStateHistory`记录 4. **模式检查** ：各钩子会检查 `editMode` 和 `drawingMode` 状态

Wms 反应组件

包含技能