一、 引言：从临时绘图到数据归档

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

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

二、 核心原理：云图开发包架构逻辑

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

核心逻辑：

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

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

三、实战步骤详解

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

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 对象

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`后，需通过协议传输至服务端。

传输逻辑：

使用`FormData`封装文件数据，通过`fetch`或`axios`发送POST请求。

代码示例：标准上传逻辑

const uploadFileToServer = async (fileData, fileName) => {
  const formData = new FormData();
  formData.append("file", fileData, fileName); // 封装文件
  formData.append("bizId", "project_12345"); // 携带业务参数
  try {
    const response = await fetch("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`）进行“无头”转换。

核心转换流程如下：

1. **定位文件**：获取前端上传的 `.mxweb` 文件在服务器上的临时存储路径。

2. **构建命令**：组装转换指令，指定输入文件（源）和输出文件（目标），以及目标格式（如 DWG, PDF）。

3. **执行转换**：通过子进程调用转换引擎。

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

1. 命令格式为 `./mxcadassembly '{"srcpath":"输入路径","outpath":"输出目录", "outname":"文件名"}'`。

2. Node.js 后端核心片段：

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`），但在上述“上传-转码”流程中，下载通常是一个独立的后续操作，因此需要配合整体流程共同完成。

四、基于 Node 服务的快速实现

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

4.1 快速启动

1. 下载并解压 MxCAD 云图开发包。

2. 进入目录：`MxDrawCloudServer/Bin/MxDrawServer/Windows`。

3. 启动服务：在终端执行 `node app.js`。

4. 端口：服务默认监听 `1337` 端口。

4.2 核心接口速查

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

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

import { MxCpp } from "mxcad"
// 1. 获取当前 MxCAD 对象
const mxcad = MxCpp.getCurrentMxCAD()
// 2. 调用接口，传入保存 DWG 的后端地址
mxcad.saveFileToUrl("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("文件保存成功，服务器路径：",
                        `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(
    "localhost:1337/mxcad/savepdf", 
    (iResult, sServerResult) => {
        const ret = JSON.parse(sServerResult);
        if (ret.ret === "ok") {
            // 获取生成的 PDF 下载链接
            const pdfUrl = "localhost:1337/mxcad/file/" + ret.file;
            console.log("PDF生成成功:", pdfUrl);
        }
    }, 
    "my_drawing", // 文件名
    JSON.stringify({ width: "2000", height: "2000" }) // 额外参数
);

4.3 文件存储路径管理

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

* 访问地址：`localhost:1337/mxcad/file/文件名`

* 路径修改：如需更改存储位置，请编辑 `ini.js` 配置文件中的 `uploadPath` 字段

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

五、 总结

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

**核心在于理解：**

- **前端**负责交互与展示，生成轻量级的`mxweb`数据。

- **后端**负责存储与转码，利用引擎将`mxweb`还原为标准格式。

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