返回介绍

指南

MxCAD API 文档

文江博客 开发文档 MxCAD 中文文档 和 API 文档 文章详情

1. 快速入门

发布于 2024-07-31 21:40:00 字数 37866 浏览 0 评论 0 收藏 0

快速入门

简介

什么是mxcad?

mxcad 是用于构建在线cad预览编辑图纸的JavaScript 框架, 它基于TypeScript构建, 并提供了一套适用于CAD图纸预览编辑功能的API, 能在网页中完成大部分基础CAD相关功能开发。

其中在线CAD梦想画图项目就是基于mxcad搭建的, 可点击查看具体效果。

mxcad会渲染一个mxweb格式文件, 该文件是由mxdraw云图开发包提供的图纸转换程序, 将CAD图纸转换成为mxweb文件

然后由mxcad处理mxweb文件, 而提供渲染能力的是mxdraw库, mxcad依赖于mxdraw库提供的渲染能力。

所以 mxcad必须和mxdraw一起使用 如果你不了解mxdraw库 请参考：https://www.wenjiangs.com/docs/mxcad-docs-and-api

mxdraw不再维护wgh文件格式, mxcad也只支持渲染mxweb格式的文件。

基本用法

推荐使用vite作为构建工具

<div style="height: 600px; overflow: hidden;"> <canvas id="myCanvas"></canvas></div>

import { createMxCad } from "mxcad"
// 需要等canvas元素加载到页面文档中后才能调用createMxCad方法
createMxCad({
    canvas: "#myCanvas",
    locateFile: (fileName)=> new URL(`/node_modules/mxcad/dist/wasm/2d/${fileName}`, import.meta.url).href,
    // 提供要打开的文件 注意../assets/test.mxweb 是相对路径下的文件地址, 
    // 在vite中可用通过这样的方式得到该文件正确的的网络地址
    fileUrl: new URL("../assets/test.mxweb", import.meta.url).href,
    // 提供加载字体的目录路径
    fontspath:  new URL("node_modules/mxcad/dist/fonts", import.meta.url).href,
}).then((mxcad)=> {
    // 我想换一个文件显示?
    mxcad.openWebFile(new URL("../assets/test2.mxweb", import.meta.url).href)
    // 我想保存我修改后的文件？
    // (你可以在dom元素事件函数中调用，这样可以使用一些最新的浏览器特性保存文件)
    mxcad.saveFile()
})

vite.config.ts的配置:

import { defineConfig } from "vite"
// 让devServe 开发服务器设置响应头支持SharedArrayBuffer特性
export default defineConfig({
    server: {
        headers: {
          "Cross-Origin-Opener-Policy": "same-origin",
          "Cross-Origin-Embedder-Policy": "require-corp",
        }
    }
})

::: tip 重要提示

因为mxcad默认使用了SharedArrayBuffer 需要在服务端设置相应对应的响应头, 上面说明vite开发服务器如何设置, 而在线上服务器中以nodejs为例设置如下配置:


const http = require('http');
http.createServer((req, res)=> {
    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
    res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
})

如果你不希望使用SharedArrayBuffer 则可与在使用wasm文件包时选择2d-st这个目录而不是2d这个目录,

mxcad node_modules/mxcad/dist/wasm/ 目录下 有三个wasm文件包: 2d, 2d-st, 3d

如果你希望无论如何都能够正常加载wasm文件并正确运行， 可以同时将这些wasm文件包放在静态服务器中然后通过locateFile参数指定wasm文件包中对应文件的路径。

import { createMxCad } from "mxcad"
// 将2d和2d-st 都放入静态资源中可以保证无论是否开启SharedArrayBuffer 都可以正常运行
const mode = "SharedArrayBuffer" in window ? "2d" : "2d-st"
createMxCad({
  // ...
   locateFile: (fileName)=> {
    new URL(`/node_modules/mxcad/dist/wasm/${mode}/${fileName}`, import.meta.url).href
   },
})

:::

目前的前端应用大部分都是基于打包工具构建的，以上是基于vite打包的前端应用使用mxcad的简单说明。

mxcad在这些基于打包工具的前端应用中使用时, 只要了解以下原则, 就可用让mxcad在任何打包工具中使用:

  1. mxcad的核心是依赖包中/mxcad/dist/wasm中对应分类(2d|2d-st|3d)目录中的文件, 要保证locateFile的返回值能正确返回wasm目录中的对应文件的路径(fontspath、fileUrl包括locateFile的返回值都必须是网络路径)。 也就是说locateFile返回的网络地址, 在浏览器中一定是要能访问到对应文件的。而wasm目录是在mxcad的依赖包中， 所以所有打包工具都应该将wasm目录拷贝到对应对应的静态资源目录, 然后locateFile返回正确的网络路径，你可用选择手动拷贝也可用选择用打包工作拷贝, 具体如何操作, 请参考打包工具的文档。

  2. 要正确显示图纸中的文字, 就必须加载对应的字体文件, fontspath参数就是存放字体文件目录的网络路径, 在mxcad依赖包中提供了默认的dist/fonts字体目录,一样需要拷贝到静态资源中, 并且你也可用在里面添加自己打开的图纸需要的各种字体文件在该目录中。

  3. 为了性能考虑, mxcad默认开启SharedArrayBuffer 支持多线程。你需要在服务器响应头中添加对应配置(在上面已经说明), 如果你不想开启SharedArrayBuffer, 那么在locateFile返回的地址中，选择/wasm/2d-st/目录中的文件， 否则使用/wasm/2d开启SharedArrayBuffer支持多线程

最后如果你对前端的打包工具不太熟悉, 建议先熟悉打包工具(webpack|vite)的使用。

下面将说明在不同打包工具中如何使用mxcad, 并且不同打包工具应该如何配置, 来让你更容易理解上述原则。

目前的前端应用构建都需要依赖NodeJS, 请先安装完成NodeJS环境再熟悉命令行的情况下继续阅读。

如果你对打包工具较为熟悉请直接点击跳转到示例参考查看对应打包工具使用mxcad的源码快速了解使用。

在vite中使用mxcad

参考示例源码: https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip

1.安装vite和mxcad

npm install vite -D
npm install mxcad

2.新建一个项目根目录并在其中新建html文件

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>vite use mxcad</title>
</head>
<body>
    <div style="height: 600px; overflow: hidden;"> <canvas id="myCanvas"></canvas></div>
    <script type="module" src="./src/index.ts"></script>
</body>
</html>

3.在根目录下新建src目录 在src目录下新建index.ts文件（vite默认支持ts）代码如下:

import { createMxCad } from "mxcad"
import { MxFun } from "mxdraw"

createMxCad({
    canvas: "#myCanvas",
    locateFile: (fileName)=> new URL(`/node_modules/mxcad/dist/wasm/2d/${fileName}`, import.meta.url).href,
    fileUrl: new URL("../assets/test.mxweb", import.meta.url).href,
    fontspath:  new URL("node_modules/mxcad/dist/fonts", import.meta.url).href,
})

4.在src目录下创建assets并(https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip)然后重命名复制为test.mxweb文件到该目录下

5.在根目录下创建vite.config.ts文件

import { defineConfig } from "vite"

export default defineConfig({
    server: {
        headers: {
          "Cross-Origin-Opener-Policy": "same-origin",
          "Cross-Origin-Embedder-Policy": "require-corp",
        }
    }
})

6.完成以上步骤在根目录执行如下命令

npx vite

在webpack中使用mxcad

参考示例源码:

https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip

https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip

1.安装

npm install webpack webpack-cli copy-webpack-plugin@5 -D

2.在根目录下创建webpack.config.js文件

const path = require('path');
// copy-webpack-plugin@5 兼容webpack4和5的版本请放心使用
const CopyWebpackPlugin = require("copy-webpack-plugin");

module.exports = {
  mode: process.env.development === "development" ? "development" : "production",
  entry: './src/index.js',
  devServer: {
    static: './dist',
    headers: {
      "Cross-Origin-Opener-Policy": "same-origin",
      "Cross-Origin-Embedder-Policy": "require-corp"
    }
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'main.js',
  },
  plugins: [
    new CopyWebpackPlugin([
      // 拷贝mxcad wasm 相关的核心代码 mxcad默认请求的路径是 /* 所有 需要把文件放dist2d下
      {
        from: "node_modules/mxcad/dist/wasm/2d/*",
        to: path.resolve(__dirname, "dist"),
        flatten: true
      },
      // 必须要字体文件来显示图纸中的文字，mxcad库默认请求URL路径为 /fonts/* 所有需要放在dist/fonts下
      {
        from: "node_modules/mxcad/dist/fonts",
        to: path.resolve(__dirname, "dist/fonts"),
        flatten: true,
        toType: "dir"
      },
    ])
  ],
  // mxcad 和 mxdraw库的js代码打包超过webpack默认限制的大小，需要设置hints: false关闭警告
  performance: {
    hints: false,
  }
};

3.在根目录新建index.html文件

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>起步</title>
    <script src="https://unpkg.com/lodash@4.17.20"></script>
  </head>
  <body>
     <div style="height: 600px; overflow: hidden;"> <canvas id="myCanvas"></canvas></div>
    <script src="./src/index.js"></script>
  </body>
</html>

4.在根目录新建src目录 并在src目录下新建index.js文件

createMxCad({
    canvas: "#myCanvas",
    // 通过需要访问：http:xxx.com/test.mxweb 获取对应的文件
    // 请你自行提供该文件
    fileUrl: "test.mxweb"
})

5.完成上述步骤执行npx webpack serve命令运行查看效果

在html文件中直接使用mxcad

上面一直在讲述基于前端框架或者前端打包工具的前端应用应该如何使用mxcad, 但是有时候我们只希望用html、js简单的去使用mxcad。

在mxcad中我们提供了CDN和NPM两种方式去使用mxcad, 前面一直在NPM的方式, 下面我们以CDN的方式来加载使用mxcad

这里我们使用了 unpkg，但你也可以使用任何提供 npm 包服务的 CDN，你也可以下载此文件并自行提供服务

::: tip 提示 如果直接在浏览器中打开了上面的 index.html，你会发现它抛出了一个错误, 需要启动一个node服务来显示页面,你可用直接参考https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip实现对应的node.js代码 :::

使用全局构建版本

参考示例源码: https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip

<script scr="https://unpkg.com/mxdraw/dist/mxdraw.umd.js" crossorigin="anonymous"></script>
<script scr="https://unpkg.com/mxcad/dist/mxcad.umd.js" crossorigin="anonymous"></script>
<script>
    const { MxFun } = Mx
    const { createMxCad } = mxcad
    window.onload = function() {
        createMxCad({
            canvas: "#myCanvas",
            locateFile(fileName) {
                /***
                 * 你可以不设置locateFile属性，
                 * 默认通过该https://unpkg.com CDN加载或者无法使用SharedArrayBuffer的情况
                 * mxcad会自动引入2d-st的资源
                 * 2d与2d-st的区别就是2d-st未使用worker多线程优化，
                 * 导致在打开图纸时会阻塞js线程导致打开图纸过程中页面卡死的情况
                 * 推荐使用2d wasm资源，你需要在服务器设置响应头：
                 * "Cross-Origin-Opener-Policy": "same-origin",
                 * "Cross-Origin-Embedder-Policy": "require-corp"
                 * 
                 * 并对于2d wasm资源遵从浏览器同源策略
                 * (也就是说 locateFile返回的url需要是和自己的服务器域名相同的域名端口才行)
                 * */
                return "https://unpkg.com/mxcad/dist/wasm/2d-st/" + fileName
            },
            // 请自行在静态服务器上添加test.mxweb文件 如http://xxx.com/test.mxweb
            fileUrl: "test.mxweb"
        })
    }
</script>

使用 ES 模块构建版本

参考示例源码: https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip

因为mxcad依赖mxdraw库, 所以要导入映射表 (Import Maps)来告诉浏览器如何定位到导入的 mxdraw模块和mxcad模块

你也可以在映射表中添加其他的依赖——但请务必确保你使用的是该库的 ES 模块版本。 :::tip 导入映射表是一个相对较新的浏览器功能。请确保使用其支持范围内的浏览器。请注意，只有 Safari 16.4 以上版本支持。 :::

<div style="height: 600px; overflow: hidden;"> <canvas id="myCanvas" style="height: 300px"></canvas></div>
<script type="importmap">
    {
      "imports": {
        "mxdraw": "https://unpkg.com/mxdraw/dist/mxdraw.esm.js",
        "mxcad": "https://unpkg.com/mxcad/dist/mxcad.es.js"
      }
    }
</script>
<script type="module">
    import { MxFun, loadCoreCode } from "mxdraw"
    import { createMxCad } from "mxcad"

    window.onload = function() {
        createMxCad({
            canvas: "#myCanvas",
            locateFile: (fileName)=> "https://unpkg.com/mxcad/dist/wasm/2d-st/" + fileName,
            fontspath: "https://unpkg.com/mxcad/dist/fonts/",
            fileUrl: "/test2.mxweb"
        })
    }
</script>

示例参考

在git中查看示例 github | https://www.wenjiangs.com/wp-content/uploads/2024/07/examples.zip

或者通过 执行以下命令查看所有实例, 以vite目录示例为例:

git clone https://github.com/mxcad/mxcad_docs
cd mxcad_docs
cd examples
cd vite
npm install
npm run dev

其他示例一样进入对应目录

npm install
npm run dev

::: tip 注意examples/public 是所有示例目录公用的静态资源, 如果你复制某个示例目录到其他位置, 请自行阅读代码将使用了静态资源的路径修改为正确的位置

例如webpack-v4 或者webpack-v5 目录中的webpack.config.js中在开发模式下的测试用的mxweb文件的移动配置

plugins: [
        new CopyWebpackPlugin([
            // 这里拷贝的是转换后的图纸文件 对应在src/index.js中 `mxcadObj.openWebFile("test2.mxweb")`
            // 这只是转换后的测试图纸文件 你应该转换自己的图纸文件
            {
              from: "../public/test2.mxweb",
              to: path.resolve(__dirname, "dist"),
              flatten: true
            }
          ]),

    ],

vite目录中src/index.ts 用于指定mxweb路径和字体文件路径的参数:

 createMxCad({
    fileUrl: new URL("../../public/test2.mxweb", import.meta.url).href,
    fontspath:  new URL("../../public/fonts", import.meta.url).href,
})

:::

通过示例查看具体如何在不同打包器或者不适应打包器的情况下使用mxcad库

你还可以通过演练场在线编辑修改代码查看运行后的效果

上面的所有示例都只是最简单的使用mxcad库的项目,并没有通过mxcad中提供的各种方法来实现CAD中的相关功能。

在线浏览编辑CAD图纸的前端应用项目

针对不同用户的需求, mxcad提供了包含各种功能的使用mxcad提供的API实现的完整的在线浏览编辑CAD图纸的前端应用项目,

你可用根据我们提供的项目源码参考实现各种功能的实现，也可用直接通过<iframe>标签直接引入。

前端源码下载地址: https://demo.mxdraw3d.com:3562/MxCADCode.7z

浏览版预览地址: https://www.mxdraw3d.com/sample/vuebrowse

编辑版预览地址: https://demo.mxdraw3d.com:3000/mxcad

下面是浏览版的完整说明，编辑版请直接跳转到示例项目二次开发查看完整说明。

MxCADCode.7z解压后对应的目录地址: \Browse\2d\Browse 浏览版源码

最简单的方式自然是通过<iframe>, 对应的在\Browse\2d\Browseiframe目录中就是使用iframe的方式集成\Browse\2d\Browse的浏览版前端页面

具体启动这两个项目的步骤如下:

# 进入MxCADCode.7z解压后的目录
cd MxCADCode
cd Browse/2d/Browse
npm install
npm run serve
# 开启另一个命令行 进入MxCADCode.7z解压后的目录
cd MxCADCode
cd Browse/2d/Browseiframe
npm install
npm run serve

最后访问http://localhost:8051/?debug=true

如果你是前端开发人员, 也可用直接参考\Browse\2d\Browse中的源码, 用mxdraw实现需要的功能

下面讲解如何通过页面中的功能按钮找到源码中的对应实现:

运行项目 打开网址http://localhost:8089/, 打开开发者工具(按F12)

点击菜单栏中的任意按钮控制台都会打印一行字符，这就是该功能对应的命令，

我们打开编辑器(VsCode) 打开该\Browse\2d\Browse项目, 然后搜索该命令可用发现类似如下代码:

// 第二个参数参数函数内的实现就是该按钮功能的对应实现
MxFun.addCommand("你搜索的命令字符串", ()=> {});

mxcad是通过mxdraw来实现渲染的，该浏览版的前端项目只是通过mxcad来读取mxweb文件

而实现各种各样的渲染功能主要是通过mxdraw提供的各种图形绘制类或者方法来实现批注等与浏览相关功能。

这些图形数据最终不会保存到mxweb文件中, 更不会保存到图纸中

如果希望讲这些图形数据保存到图纸中, 请前面https://help.mxdraw.com/?pid=115了解。

演练场

::: tip 提示 github以及网络问题加载可能较慢，可能需要等待几分钟... 点击图纸图形选中元素，可以点击操作夹点改变图形； 按下鼠标滚轮移动鼠标可以拖动图纸； 滚动鼠标滚轮放大缩小图纸； 按Esc键取消所有选中 :::

:::demo

// 这是createMxCad 实现的大致流程 
// 如果你希望整个创建过程是透明公开的,
// 你可以不使用createMxCad 而是使用下面的代码自行创建

import { createMxCad } from "mxcad"
export default () => {
    createMxCad({
      canvas: "#myCanvas",
      locateFile: (fileName: string)=> {
            // CDN 加载必须使用wasm/2d-st中的资源、因为github的限制无法使用wasm/2d 资源
            // 需要使用wasm/2d需要遵循浏览器同源策略或使用其他手段规避浏览器同源策略
            return "https://unpkg.com/mxcad/dist/wasm/2d-st/" + fileName
      },
      // 加载字体的目录位置
      fontspath: self.location.origin + "/mxcad_docs/fonts",
      // 加载转换后的图纸文件
      fileUrl: self.location.origin + "/mxcad_docs/test2.mxweb"
    })
    .then((mxcad)=> {

    })
    return (<div style="height: 600px; overflow: hidden;"><canvas id="myCanvas" style="height: 300px"></canvas></div>)
}

:::

如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论， 你可以免费 注册 一个本站的账号。
列表为空，暂无数据
    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站，即表示您同意使用 Cookies 和您的相关数据。
    原文