CAD 图纸操作 · 前端 mxcad 指南

适用范围：网页中预览、浏览、编辑、绘制、标注、测量 CAD 图纸（mxcad 前端）。路由规则见入口指引；后端操作见后端 MxServiceCode 指南。

一、程序与资源
二、官方文档章节索引
三、任务→文档检索指引

一、程序与资源

1.0 程序获取

转换程序有两种获取方式：下载单独 MxConvert zip（仅含转换程序，推荐）或后端服务 zip（也含转换程序）。固定临时路径（只下载一次，跨会话复用）：Windows = %TEMP%\MxCAD\，Linux = /tmp/MxCAD/；按入口指引的排查步骤执行——缺转换程序时按"链接清单"取"单独转换程序"对应行的地址下载并解压到临时路径（重新下载前先清空临时路径），已有则先检测过期再使用。试用版期限 6 个月。

转换程序目录：两个 zip 解压后都只有一个顶层目录（与 zip 同名）。后端服务包 = Windows 临时路径下 MxServiceCode_TryVersion\MxCAD\Release\、Linux 下 MxServiceCode_TryVersion\Linux\MxCAD\；单独 MxConvert 包 = MxConvert_TryVersion\ 目录本身就是转换程序目录（mxcadassembly 等文件直接在其中）。该目录下含 mxcadassembly.exe / mxcadassembly 及：运行依赖 dll/so、mxcad_ini.json、mxcode.bin、mxiconv.data、fonts\（字体目录）、files\。

三类资源来源：

资源	来源
格式转换程序（DWG→mxweb）	单独 MxConvert zip（推荐）或后端服务 zip（含转换程序）
mxcad 前端核心（JS + wasm）	官方 npm 包 `mxcad`、`mxdraw`，或 CDN `https://unpkg.com/mxcad/dist/...`、`https://unpkg.com/mxdraw/dist/...`（不在转换程序 zip 里）
前端字体目录	直接复制转换程序目录下的 `fonts\`

转换可执行文件：mxcadassembly.exe（Windows）/ mxcadassembly（Linux），DWG/DXF/MXWEB/PDF/JPG 互转，用法见二-(八) 图纸转换详细说明
Linux 首次使用：chmod 777 mxcadassembly 及 mx/so/*

mxcad 前端只认 mxweb 格式（wgh 已废弃）。浏览器显示前必须先经 mxcadassembly 完成 DWG→mxweb 转换。

1.1 浏览器预览一张 DWG（实测流程）

转换：mxcadassembly 生成 t1.mxweb（参数编码见《部署与启动说明.md》第三节）。⚠️ outpath 目录必须预先存在（程序不自动创建，目录不存在时返回 {"code":2,"message":"write file error"}）
字体：把转换程序目录下 fonts\ 整目录复制到 Web 工程字体目录（如 web/fonts/）
预览页 web/index.html（前端库走 CDN，字体与图纸走本地 HTTP）：
html
```
<!DOCTYPE html>
<html lang="zh"><head><meta charset="utf-8">
<title>t1 图纸预览</title>
<script type="importmap">
{ "imports": {
    "mxdraw": "https://unpkg.com/mxdraw/dist/mxdraw.esm.js",
    "mxcad":  "https://unpkg.com/mxcad/dist/mxcad.es.js"
} }
</script>
</head><body style="margin:0">
<div id="box" style="width:100%;height:100vh;overflow:hidden"><canvas id="c"></canvas></div>
<script type="module">
  import { McObject } from "mxcad";
  new McObject().create({
    canvas: '#c',
    // 可访问的网络地址：本例 mxweb 与页面同目录（静态服务器根下），浏览器按页面 URL 自动解析为完整地址（与官方 CDN 示例 "./test2.mxweb" 同理）
    fileUrl: 't1.mxweb',
    // 可访问的网络地址：官方 CDN 示例用 "https://unpkg.com/mxcad/dist/fonts/"（完整 CDN 地址亦可），但实测该目录缺若干字体文件，本例改用转换程序 fonts\ 复制到本地目录
    fontspath: 'fonts/',
    locateFile: (n) => 'https://unpkg.com/mxcad/dist/wasm/2d-st/' + n, // wasm 走 CDN（与官方一致）
    onOpenFileComplete: () => console.log('图纸打开成功')
  });
</script>
</body></html>
```
⚠️ fileUrl / fontspath / locateFile 的取值规则（与官方《快速入门》一致，按创建方式调整）：三者最终都必须解析为浏览器可访问的网络地址（官方原文："create() 的参数 fontspath、fileUrl 包括 locateFile 的值均为网络路径"）。取值形式由"谁来解析、资源部署在哪"决定，随创建 mxcad 的方式变化——不能固定一种写法，更不能照搬上面示例的值，按你的项目情况取：
- CDN / ESM importmap / UMD（无打包工具）：写相对路径（如 "t1.mxweb"、"fonts/"），浏览器会按页面 URL 自动解析成完整地址——前提是资源部署在页面所在目录下（官方 CDN 示例即此）；资源在 CDN 上则直接写完整 CDN 地址（官方示例的 fontspath 用的就是 "https://unpkg.com/mxcad/dist/fonts/"）。⚠️ 不要用 location.protocol + host + pathname 手动拼绝对 URL：实测会请求到 :8080/://127.0.0.1:8080/t1.mxweb 这类畸形地址（404，onOpenFileComplete 不触发）
- Vite / 打包工具：用 new URL("../src/assets/t1.mxweb", import.meta.url).href 以模块位置为基准计算完整地址（官方 Vite 章节写法）
- webpack：写静态资源相对路径（如 "test.mxweb"），资源目录与 new URL 处理在 webpack.config.js 里配置（CopyWebpackPlugin 拷贝到 dist，见官方 webpack 章节）
核对方法：打开 DevTools Network，确认 .mxweb / 字体 / .wasm 请求的 URL 是真实可达的地址（无畸形拼接、无 404）。
（本地离线测试可用开发包 mxcadAppAssets\ 里的 UMD 库：先引 mxdraw.umd.js 再引 mxcad.umd.js，全局 MxCAD.McObject，wasm 指向 mxcadAppAssets\wasm\2d-st\。）
⚠️ ESM 构建不定义 MxCAD 全局（实测，2026-11）：上面的页面是 ESM importmap 方式，库从 "mxcad" 模块具名导入——这种构建下不存在 MxCAD 全局对象。若在 ESM 页面里写 MxCAD.MxCpp.getCurrentMxCAD()、ent instanceof MxCAD.McDbLine 等 UMD 风格代码，会报 ReferenceError: MxCAD is not defined（1.2 节的验证代码均为 UMD 实测写法，不能直接粘进 ESM 页面）。ESM 下改为具名导入，模块级单例 MxCpp 等价于 UMD 的 MxCAD.MxCpp：
js
```
import { McObject, MxCpp, McDbLine } from "mxcad";
MxCpp.getCurrentMxCAD().zoomAll();   // 视图控制
ent instanceof McDbLine;             // 实体类型判断
```
判断标准：页面里写的是 import ... from "mxcad"（ESM）还是 src="...mxcad.umd.js"（UMD）。UMD 用 MxCAD. 全局，ESM 用具名导入，两者不可混用。
起静态服务器：web\ 必须走 HTTP（file:// 下 wasm 不可用），且 .wasm MIME 须为 application/wasm
打开：浏览器访问 http://127.0.0.1:<port>/index.html。以 onOpenFileComplete 回调为准（wasm 约 3.9MB，本地约 10~15 秒）；图纸不在视区时调用全幅显示：MxCpp.getCurrentMxCAD().zoomAll()（ESM）/ MxCAD.MxCpp.getCurrentMxCAD().zoomAll()（UMD，见上方 ESM 警告）

⚠️ 运行时转换功能（用户上传图纸自己打开）与上面一次性流程的区别：1.1 是"AI 当场转好再展示"。如果要做成用户自己上传图纸、功能运行时现场转换的功能，转换程序就是该功能的运行时依赖，不能写死临时路径——临时路径会被清空（换包前）或被 OS 自动清理，功能会断且不会自愈。按 SKILL.md"程序获取"节的"两种使用模式"处理：推荐把整个转换程序目录复制进项目（如 tools/mxcad/），功能代码引用项目内路径（试用版 6 个月到期后重新复制一份）；或运行时按序动态解析临时路径下的两个可能位置（Windows：MxConvert_TryVersion\ → MxServiceCode_TryVersion\MxCAD\Release\；Linux：MxConvert_Ubuntu20_TryVersion/ → MxServiceCode_TryVersion/Linux/MxCAD/）。字体按步骤 2 复制进项目后无运行时依赖，两种方式下都不受影响。

1.2 验证与排错要点（实测）

canvas 是 WebGL：2D getImageData/drawImage 采样读到的是清空后的黑色缓冲区，像素法验证不可靠
画布尺寸交给 mxcad 自管：切勿手动设 canvas.width/height、不要加 window.resize 监听——会反复清空 WebGL 画布并造成尺寸反馈循环，界面持续闪烁。<canvas> 不带宽高，铺满容器交给 CSS（#box canvas{width:100%;height:100%}）

可靠验证：读 mxcad 数据库统计实体，与后端提取结果交叉比对：

// 以下均为 UMD 写法（MxCAD 全局）；ESM 页面先 import { MxCpp, McDbLine } from "mxcad"，
// 把 MxCAD.MxCpp 换成 MxCpp、MxCAD.McDbLine 换成 McDbLine（见 1.1 的 ESM 警告）
const db = MxCAD.MxCpp.getCurrentMxCAD().getDatabase();
const ids = db.currentSpace.getAllEntityId();          // 前端 API，注意与后端不同名
const ent = ids[0].getMcDbObject();                    // 前端是 getMcDbObject，不是 getObject
ent instanceof MxCAD.McDbLine; ent.layer; ent.startPoint.x

前端 API 与后端 API 名称不同（以 UMD 实测为准）：currentSpace 是属性不是方法；空间取实体用 getAllEntityId()（后端是 getAllEntity）；id 取对象用 getMcDbObject()（后端是 getObject）
UMD 与 ESM 写法不同：UMD 用 MxCAD. 全局；ESM（importmap/npm ESM）无 MxCAD 全局，用具名导入 import { MxCpp, McDbLine, ... } from "mxcad"（见 1.1 警告）
其他可用视图 API：zoomAll、zoomCenter、zoomScale、getViewBackgroundColor（0=黑底）、openWebFile(url)
排错顺序：onOpenFileComplete 未触发 = 文件/资源没加载（查 404/MIME）；触发了但看不到图形 = 视区问题，先 zoomAll()

二、官方文档章节索引

本节所有链接均为站点内相对链接（官方文档与本指南同站点，站点发布在哪个域名下链接都自动生效）。

2.1 开始

文档	链接
简介	链接
快速入门（Vite/CDN/ES/webpack 集成 + 示例代码）	链接
图纸转换	链接
打开和保存图纸	链接

2.2 指南

文档	链接
数学库	链接

2.3 基础绘图（17 个图元）

图元	链接
点	链接
直线	链接
多段线	链接
圆	链接
圆弧	链接
椭圆	链接
尺寸标注	链接
文字	链接
自定义实体	链接
填充	链接
路径	链接
图块	链接
图片	链接
样条线	链接
面域	链接
射线	链接
构造线	链接

2.4 交互绘图

文档	链接
命令行	链接
UI 交互	链接
动态绘制	链接

2.5 图纸编辑

文档	链接
选择图形	链接
常用编辑操作	链接
视区设置	链接
事件监听	链接

2.6 数据库

文档	链接
概述	链接
图层表	链接
文字样式表	链接
系统变量	链接
块表	链接
全局字典	链接
实体	链接
线型表	链接
标注样式表	链接

2.7 最佳实践

文档	链接
MxCADApp Npm 应用集成（npm 包 mxcad-app，Vite/webpack 插件）	链接
项目集成基本说明	链接
扩展插件的开发	链接
扩展插件二次开发地图	链接
mapbox 与 CAD 图纸结合	链接
打包桌面 MxCAD APP	链接
常见问题（FAQ）	链接

功能示例：

测量标注

功能	链接
测量圆	链接
测量面积	链接
点到直线距离	链接
弧长	链接
连续测量	链接
局部放大	链接
测量坐标	链接
测量角度	链接
箭头引注	链接
引出标注	链接
标高标注	链接

绘图工具

功能	链接
中心矩形	链接
星形	链接
保温棉	链接
画指北针	链接
加折断线	链接
画对称轴	链接

编辑工具

功能	链接
矩形缩放	链接
临时隐藏	链接
打断	链接
移动	链接
缩放	链接
镜像	链接
旋转	链接
偏移	链接

文字工具

功能	链接
文字加框	链接
提取文字	链接
文字查找	链接

其他

功能	链接
导出 JPG	链接
导出 PDF	链接
指定范围输出 DWG	链接

2.8 相关文章

文档	链接
MxCAD 产品介绍	链接
云图开发包使用说明（开发包整体结构）	链接
图纸转换详细说明（mxcadassembly 命令行 + HTTP 全参数，含 cut_dwg / print_to_pdf / JPG 导出）	链接
MxCAD/MxDraw Web 预览批注实战	链接
视图控制与图层管理系统实现	链接
命令行驱动与参数化绘图	链接
从浏览图纸到编辑图纸	链接
mxcad 实现图纸保存功能	链接
MxServiceCode 详解（后端，见后端指南）	链接
mxcad 绘制条形码、二维码	链接
MxCAD 多行文本扩展	链接
mxcad 中组相关功能开发	链接
mxcad 实现绘制粗糙度标注功能	链接
浏览器中的专业 CAD	链接
对象捕捉（OSMODE）	链接
MxCAD 基础图形绘制	链接
MxCAD 基础绘图进阶	链接
mxcad-app 集成说明	链接
MxCAD APP 调用内部弹框	链接
mxcad 对 CAD 项目配置属性的详细介绍	链接
MxCAD 项目中的插件上文 MxPluginContext	链接

2.9 API 文档

完整类/枚举/接口参考（McDb* 实体类、选择集、插件基类、tools.MxCanvas2Image、mapbox.MxMap）：

<../../api/README.html>

三、任务→文档检索指引

任务类型	应访问文档
集成/部署（npm、CDN、Vite、webpack、Vue、React）	2.1 快速入门 + 2.7 Npm 应用集成 + 2.8 mxcad-app 集成说明
查看/打开/保存图纸	2.1 打开和保存图纸 + 2.8 mxcad 实现图纸保存功能
浏览器预览 DWG（本地静态）	本指南 1.1 实操 + 2.1 快速入门
画某图元（线/圆/多段线/标注/文字/填充/图块…）	2.3 基础绘图对应条目
自定义命令/工具栏/交互	2.4 交互绘图 + 2.8 MxPluginContext + 2.7 扩展插件的开发
选择/移动/复制/编辑	2.5 图纸编辑 + 2.7 功能示例-编辑工具
图层/线型/文字样式/标注样式/系统变量	2.6 数据库对应条目
测量（面积/距离/角度/坐标/半径）	2.7 功能示例-测量标注
导出（PDF/JPG/指定范围 DWG）	2.7 功能示例-其他 + 2.8 图纸转换详细说明
格式转换（DWG/DXF/MXWEB/PDF 互转）	2.1 图纸转换 + 2.8 图纸转换详细说明
事件/回调	2.5 事件监听
对象捕捉	2.8 对象捕捉（OSMODE）
问题排查	2.7 常见问题
某 API 的完整签名/参数	2.9 API 文档

开始

指南

基础绘图

交互绘图

图纸编辑

数据库

最佳实践

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

相关文章

入门指南

MxCAD功能介绍

CAD 功能开发

应用集成

AI执行手册

后端参考文档

CAD 图纸操作 · 前端 mxcad 指南

一、程序与资源

1.0 程序获取

1.1 浏览器预览一张 DWG（实测流程）

1.2 验证与排错要点（实测）

二、官方文档章节索引

2.1 开始

2.2 指南

2.3 基础绘图（17 个图元）

2.4 交互绘图

2.5 图纸编辑

2.6 数据库

2.7 最佳实践

2.8 相关文章

2.9 API 文档

三、任务→文档检索指引

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

入门指南

MxCAD功能介绍

CAD 功能开发

应用集成

后端参考文档

CAD 图纸操作 · 前端 mxcad 指南 ​

一、程序与资源 ​

1.0 程序获取 ​

1.1 浏览器预览一张 DWG（实测流程） ​

1.2 验证与排错要点（实测） ​

二、官方文档章节索引 ​

2.1 开始 ​

2.2 指南 ​

2.3 基础绘图（17 个图元） ​

2.4 交互绘图 ​

2.5 图纸编辑 ​

2.6 数据库 ​

2.7 最佳实践 ​

2.8 相关文章 ​

2.9 API 文档 ​

三、任务→文档检索指引 ​

CAD 图纸操作 · 前端 mxcad 指南

一、程序与资源

1.0 程序获取

1.1 浏览器预览一张 DWG（实测流程）

1.2 验证与排错要点（实测）

二、官方文档章节索引

2.1 开始

2.2 指南

2.3 基础绘图（17 个图元）

2.4 交互绘图

2.5 图纸编辑

2.6 数据库

2.7 最佳实践

2.8 相关文章

2.9 API 文档

三、任务→文档检索指引