mxcad

图纸保存与数据持久化实战指南

1. 引言：从临时绘图到数据归档

在完成了环境搭建、视图控制、命令行驱动及图纸编辑的全流程探索后，数据持久化成为构建完整工程设计系统的关键一环。在工程实践中，图纸不仅需要在浏览器中实时渲染，更需要将修改后的数据安全回传服务器，或转换为通用格式（如DWG、PDF）进行归档。

MxCAD的保存机制并非简单的“文件下载”，而是一个基于“前端-后端”协同的复杂过程。本文将深入解析这一过程，帮助开发者构建完整的云端设计闭环。

2. 核心原理：云图开发包架构逻辑

在深入代码前，必须明确MxCAD的文件架构逻辑。为了实现Web端的高性能渲染，MxCAD采用了专有的mxweb格式作为核心数据载体。

核心逻辑： 浏览器中的JavaScript无法直接将图形数据转换为复杂的AutoCAD DWG格式。因此，保存图纸的实质是：将前端的mxweb数据上传至服务器，由服务器端的转换引擎（云图开发包）将其还原并转码为标准格式。

这一过程遵循“前端负责交互与展示，后端负责存储与转码”的架构思想。

3. 实战步骤详解

完整的图纸保存流程分为四个标准步骤：前端序列化、数据上传、后端转码、前端下载。

3.1 步骤一：前端序列化（生成 mxweb）

在 MxCAD 的架构中，前端是用户交互的入口，所有绘图、编辑、图层管理等操作都在浏览器内存中进行。为了将这些动态数据持久化，第一步必须将当前绘图环境“快照”下来。

MxCpp.getCurrentMxCAD().saveFile() 方法是 MxCAD 提供的核心 API，用于将当前绘图区的所有图形数据、图层状态、视图配置等信息序列化为 mxweb 格式的二进制数据。mxweb 是 MxCAD 为 Web 环境优化的专有格式，它轻量、高效，能够被浏览器快速解析和渲染。

saveFile(
  filename?: string,
  call?: (data: any) => void,
  isDownland?: boolean,
  isShowSaveFileDialog?: boolean,
  parameter?: object
): boolean;

API 参数说明：

filename：可选参数，指定保存文件的名称。如果不提供，系统将使用当前文件名或默认名称。
call：可选回调函数。当文件保存完成后，该函数会被调用，参数 data 包含序列化后的文件数据（通常是 ArrayBuffer 或 Blob）。
isDownland：布尔值，默认为 true。如果为 true，则保存后会自动触发浏览器下载；如果为 false，则仅生成数据，不触发下载，适合后续上传到服务器。
isShowSaveFileDialog：布尔值，默认为 true。如果为 true，会弹出系统保存对话框让用户选择保存位置；如果为 false，则静默保存，适合自动化流程。
parameter：可选对象，用于传递额外的参数，如自定义元数据、版本号等。

代码示例一：直接在当前界面下载图纸文件

import {  MxCpp } from "mxcad"

const btn = document.createElement("button")
btn.addEventListener("click",()=>{
    MxCpp.getCurrentMxCAD().saveFile(void 0, void 0, true, true, { compression: 0 })
})
document.body.appendChild(btn)

代码示例二：获取图纸Blob 对象

typescript

import { MxCpp } from "mxcad";

MxCpp.getCurrentMxCAD().saveFile(
  void 0, 
  (data) => {
    // 处理 Safari 兼容性
    let isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
    let blob = new Blob([data.buffer], { 
      type: isSafari ? "application/octet-stream" : "application/octet-binary" 
    });
    // 调用上传函数
    uploadFileToServer(blob);
  }, 
  false, // 不触发下载
  false, // 静默保存
  { compression: 0 } // 不压缩
);

3.2 步骤二：上传至后端（数据传输）

前端获取到Blob后，需通过HTTP协议传输至服务端。

传输逻辑： 使用FormData封装文件数据，通过fetch或axios发送POST请求。

代码示例：标准上传逻辑

javascript

const uploadFileToServer = async (fileData, fileName) => {
  const formData = new FormData();
  formData.append("file", fileData, fileName); // 封装文件
  formData.append("bizId", "project_12345"); // 携带业务参数

  try {
    const response = await fetch("http://localhost:1337/api/upload", {
      method: "POST",
      body: formData,
    });
    const result = await response.json();
    console.log("上传成功，服务器返回路径:", result.filePath);
    return result.filePath;
  } catch (error) {
    console.error("上传失败:", error);
  }
};

3.3 步骤三：后端转码（格式转换）

后端接收到.mxweb文件后，需调用本地MxCAD转换服务（如mxcadassembly）进行“无头”转换。

核心转换流程如下：

定位文件：获取前端上传的 .mxweb 文件在服务器上的临时存储路径。
构建命令：组装转换指令，指定输入文件（源）和输出文件（目标），以及目标格式（如 DWG, PDF）。
执行转换：通过子进程调用转换引擎。

下面以转换dwg图纸格式为例：

命令格式为 ./mxcadassembly '{"srcpath":"输入路径","outpath":"输出目录", "outname":"文件名"}'。
Node.js 后端核心片段：

javascript

const { exec } = require('child_process');
const path = require('path');

function convertMxWebToDwg(mxwebFilePath, outputDwgPath, response) {
  const converterPath = '/path/to/mxcadassembly'; // 转换工具路径
  
  // 构建参数对象
  const params = {
    srcpath: mxwebFilePath,
    outpath: path.dirname(outputDwgPath),
    outname: path.basename(outputDwgPath, '.dwg'),
    compression: 0
  };

  // 组装命令 (注意 JSON 字符串外层的单引号)
  const command = `"${converterPath}" '${JSON.stringify(params)}'`;
  
  console.log("执行命令:", command);

  // 执行转换
  exec(command, (error, stdout, stderr) => {
    if (error) {
      return response.json({ ret: 'ConvertFailed', error: error.message });
    }
    
    try {
      const result = JSON.parse(stdout.trim());
      if (result.code === 0) {
        response.json({ 
          ret: 'Ok', 
          file: `/mxcad/file/${path.basename(outputDwgPath)}` 
        });
      }
    } catch (e) {
      response.json({ ret: 'Error', message: '解析失败' });
    }
  });
}

注意：后端转码服务通常依赖于 Windows 环境或特定的 Linux 容器环境，且需要安装对应的 MxCAD 服务端组件。

3.4 步骤四：前端下载（本地归档）

当后端完成转换，文件已变为用户熟悉的 .dwg 或 .pdf 格式。此时，前端只需要提供一个文件访问入口，让用户将这些标准文件下载到本地进行归档就完成了操作闭环。

虽然 saveFile 方法本身支持直接下载（isDownland: true），但在上述“上传-转码”流程中，下载通常是一个独立的后续操作，因此需要配合整体流程共同完成。

4. 基于 Node 服务的快速实现

若不想从零搭建后端，可直接使用 MxCAD 云图开发包预置的转换服务。

4.1 快速启动

下载并解压 MxCAD 云图开发包。
进入目录：MxDrawCloudServer/Bin/MxDrawServer/Windows。
启动服务：在终端执行 node app.js。
端口：服务默认监听 1337 端口。

4.2 核心接口速查

启动服务后，只需要调用服务内置的接口配合 saveFileToUrl 方法来完成保存，无需手动处理上传和转码的繁琐细节，接口示例如下：

目标格式	接口	说明
DWG	`http://localhost:1337/mxcad/savedwg`	保存为 AutoCAD 格式
PDF	`http://localhost:1337/mxcad/savepdf`	保存为 PDF 文档
JPG	`http://localhost:1337/mxcad/convert/cad2jpg`	仅 Windows 支持，保存为图片
MXWEB	`http://localhost:1337/mxcad/savemxweb`	保存为 MxCAD 专用格式
DWG	`http://localhost:1337/mxcad/cut_dwg`	裁剪图纸并保存为dwg格式
MXWEB	`http://localhost:1337/mxcad/cut_mxweb`	裁剪图纸并保存为 mxweb 格式

4.3 核心 API：`saveFileToUrl`

saveFileToUrl 是 MxCAD 云图开发包中封装的核心 API，用于将当前图纸数据异步传输至指定的后端服务地址。该接口的强大之处在于其通用性：用户无需编写复杂的上传逻辑，只需根据需求传入不同的后端接口 URL，即可实现保存为 DWG、MXWEB 或 PDF 等不同格式。

saveFileToUrl(
    sSaveProgramUrl: string, 
    call: (iResult: number, sServerResult: string) => void, 
    filename?: string, 
    param?: any
): boolean;

API 参数说明：

sSaveProgramUrl:目标后端接口地址。这是决定文件保存格式的关键
call:回调函数。用于接收服务端的响应。
filename:指定保存的文件名（可选）。
param:额外的 JSON 参数（如 PDF 的宽高设置）。

调用示例一：保存为 DWG

typescript

import { MxCpp } from "mxcad"

// 1. 获取当前 MxCAD 对象
const mxcad = MxCpp.getCurrentMxCAD()

// 2. 调用接口，传入保存 DWG 的后端地址
mxcad.saveFileToUrl("http://localhost:1337/mxcad/savedwg", (iResult, sServerResult) => {
    // 3. 处理服务端返回结果
    if (iResult === 0) {
        // sServerResult 是服务端返回的 JSON 字符串
        // 结构示例: { "ret": "ok", "file": "test.dwg" }
        const retData = JSON.parse(sServerResult);

        if (retData.ret === "ok") {
            console.log("文件保存成功，服务器路径：",
                        `http://localhost:1337/mxcad/file/${retData.file}`);
            
            // 此时 retData.file 即为保存后的文件访问路径（相对路径或完整URL）
            // 开发者可将其用于后续的文件下载或归档逻辑
        }
    } else {
        console.error("文件上传失败");
    }
});

调用示例二：保存为 PDF 并带参数

如果需要保存为 PDF 并指定图纸尺寸，可以通过第四个参数 param 传递配置：

import { MxCpp } from "mxcad"

const mxcad = MxCpp.getCurrentMxCAD()

// 传入第四个参数 JSON.stringify({ width: "2000", height: "2000" }) 设置 PDF 尺寸
mxcad.saveFileToUrl(
    "http://localhost:1337/mxcad/savepdf", 
    (iResult, sServerResult) => {
        const ret = JSON.parse(sServerResult);
        if (ret.ret === "ok") {
            // 获取生成的 PDF 下载链接
            const pdfUrl = "http://localhost:1337/mxcad/file/" + ret.file;
            console.log("PDF生成成功:", pdfUrl);
        }
    }, 
    "my_drawing", // 文件名
    JSON.stringify({ width: "2000", height: "2000" }) // 额外参数
);

4.3 文件存储路径管理

默认情况下，转换后的文件会被存储在云图开发包的 public/mxcad/file/ 目录下。

访问地址：http://localhost:1337/mxcad/file/文件名
路径修改：如需更改存储位置，请编辑 ini.js 配置文件中的 uploadPath 字段

// 修改 MxDrawCloudServer\Bin\MxDrawServer\Windows 下的 ini.js 文件
this.mxcad = { 
    uploadPath: "./public/mxcad/file/", // 修改此处为你自定义的路径
    mxbinPath: "../../MxCAD/Release/" 
};

5. 总结

本文详细阐述了 MxCAD 图纸保存的“四步走”策略。

核心在于理解：

前端负责交互与展示，生成轻量级的mxweb数据。
后端负责存储与转码，利用引擎将mxweb还原为标准格式。

通过利用云图开发包提供的 Node 服务，开发者可以跳过复杂的底层转换逻辑，快速实现 DWG、PDF 等格式的导出。至此，我们已涵盖了从“看图”、“编辑”到“保存”的完整生命周期。

开始

指南

基础绘图

交互绘图

图纸编辑

数据库

最佳实践

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

相关文章

入门指南

CAD 功能开发

应用集成

图纸保存与数据持久化实战指南

1. 引言：从临时绘图到数据归档

2. 核心原理：云图开发包架构逻辑

3. 实战步骤详解

3.1 步骤一：前端序列化（生成 mxweb）

3.2 步骤二：上传至后端（数据传输）

3.3 步骤三：后端转码（格式转换）

3.4 步骤四：前端下载（本地归档）

4. 基于 Node 服务的快速实现

4.1 快速启动

4.2 核心接口速查

4.3 核心 API：`saveFileToUrl`

4.3 文件存储路径管理

5. 总结

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

入门指南

CAD 功能开发

应用集成

图纸保存与数据持久化实战指南 ​

1. 引言：从临时绘图到数据归档 ​

2. 核心原理：云图开发包架构逻辑 ​

3. 实战步骤详解 ​

3.1 步骤一：前端序列化（生成 mxweb） ​

3.2 步骤二：上传至后端（数据传输） ​

3.3 步骤三：后端转码（格式转换） ​

3.4 步骤四：前端下载（本地归档） ​

4. 基于 Node 服务的快速实现 ​

4.1 快速启动 ​

4.2 核心接口速查 ​

4.3 核心 API：saveFileToUrl ​

4.3 文件存储路径管理 ​

5. 总结 ​

图纸保存与数据持久化实战指南

1. 引言：从临时绘图到数据归档

2. 核心原理：云图开发包架构逻辑

3. 实战步骤详解

3.1 步骤一：前端序列化（生成 mxweb）

3.2 步骤二：上传至后端（数据传输）

3.3 步骤三：后端转码（格式转换）

3.4 步骤四：前端下载（本地归档）

4. 基于 Node 服务的快速实现

4.1 快速启动

4.2 核心接口速查

4.3 核心 API：`saveFileToUrl`

4.3 文件存储路径管理

5. 总结