moon_excalidraw

    Renders .excalidraw files to SVG, byte-identical to the official exportToSvg, without a browser.

    excalidraw
    svg
    hand-drawn
    rough
    freehand
    Download zip
    Author
    Version
    0.2.0
    License
    MIT
    Last updated
    11 hours ago
    Downloads
    15

    #moon_excalidraw

    用 MoonBit 读取 .excalidraw 文件,不需要浏览器,输出和 Excalidraw 官方 exportToSvg 逐字节一致的 SVG。

    Excalidraw 是最流行的手绘风格白板,.excalidraw 文件是 JSON:每个元素记录位置、尺寸、颜色、填充样式、粗糙度和 seed,官方导出 SVG 时用 rough.js 画出手绘效果。本项目把这条导出流程用 MoonBit 重新实现,对照基准是 @excalidraw/excalidraw 0.18.1。

    $ excalidraw2svg diagram.excalidraw -o diagram.svg

    在线演示:https://sayoi7799.github.io/moon_excalidraw/。拖入一个 .excalidraw 文件,页面左边是本库(编译成 JS)渲染的 SVG,右边是官方 exportToSvg 渲染的,并告诉你两边是不是逐字节一致。页面里还内置了几张示例图,打开就能看。

    本库和官方 exportToSvg 并排渲染同一张图,页面显示两个 SVG 逐字节一致

    English: a MoonBit renderer for Excalidraw files. It reads .excalidraw JSON and writes the same SVG as Excalidraw 0.18.1's exportToSvg, byte for byte, without a browser. All expected outputs come from the pinned official package.

    #和其他项目的关系

    项目做什么和本项目的关系
    moon_roughrough.js 4.6.6 的逐位一致移植本项目依赖它画所有手绘图形。Excalidraw 用的是 rough.js 4.6.4,所以在 moon_rough 里加了 roughjs_464 选项(默认关闭,不影响原有行为)
    mizchi/moonlight一个“像 Excalidraw”的编辑器用自己的数据模型,不读写 .excalidraw 格式;本项目只渲染官方格式,不做编辑
    f4ah6o/papyr把 Excalidraw 数据当 JSON 原样放进 Markdown不渲染;本项目可以给它提供渲染
    perfect-freehandExcalidraw 手绘笔迹的算法MoonBit 里原先没有实现,本项目移植了 getStroke

    rough 以外的部分都是新增的:元素模型、各类元素的图形生成规则、箭头和箭头样式、文字、手绘笔迹、分组和 frame、导出布局、SVG 序列化。

    #安装

    在你的 MoonBit 项目里:

    moon add sayoi7799/moon_excalidraw

    然后在用到它的包的 moon.pkg 里导入:

    import { "sayoi7799/moon_excalidraw", }

    代码里用 @moon_excalidraw 访问。js、wasm-gc、native 三个后端都能用,开发和测试用的是 moon 0.1.20261104。命令行工具不随库安装,要克隆本仓库后用下面的 moon run 运行。

    #使用

    命令行:

    moon run --target js src/cmd/excalidraw2svg -- diagram.excalidraw -o diagram.svg

    excalidraw2svg <input.excalidraw> [options] -o, --output <file> 把 SVG 写到文件,而不是打印 --no-fonts SVG 里不带字体规则 --strict 遇到画不了的元素就报错,而不是跳过 -h, --help

    跳过的元素和其他“和官方结果不会一致”的情况会作为 warning 打印到 stderr;出错时退出码非零。在 Windows 的 native 版本上,stdout 是文本模式,换行会变成 \r\n;要得到逐字节一致的文件请用 -o(js 和 native 写出的文件完全相同)。

    作为库使用(安装见上)。下面是一个完整的 main,可以直接编译运行:

    ///|
    fn main {
    let text =
    #|{"type":"excalidraw","version":2,"elements":[
    #| {"type":"rectangle","id":"a","x":0,"y":0,"width":120,"height":60,"seed":1}
    #|]}
    let scene = @moon_excalidraw.parse_scene(text) catch {
    // 也接受 Obsidian 的 .excalidraw.md;非法 JSON、坏字段会 raise ParseError
    err => {
    println("bad file: \{err}")
    return
    }
    }
    let result = @moon_excalidraw.export_to_svg(
    scene,
    fonts=None, // Url(默认)或 None
    on_unsupported=SkipWithWarning, // 或 Error
    ) catch {
    err => {
    println("cannot draw: \{err}")
    return
    }
    }
    println(result.svg)
    for w in result.warnings {
    println(w.message)
    }
    }

    对比页:moon run --target js src/cmd/gallery -- gallery/index.html,每个场景并排放本库和官方的输出(仓库里的 gallery/index.html 已经生成好,290 个场景)。图片里的文字用浏览器的回退字体,因为 <img> 里的 SVG 不能加载外部字体。

    #Obsidian 文件

    很多人在 Obsidian 的 Excalidraw 插件里画图,文件是 .excalidraw.md,不是纯 JSON。excalidraw2svg、excalidraw2site 和库里的 parse_scene 都直接接受这种文件,不用先转换:

    moon run --target js src/cmd/excalidraw2svg -- note.excalidraw.md -o note.svg moon run --target js src/cmd/excalidraw2site -- vault-folder -o dist # 文件夹里的 .excalidraw 和 .excalidraw.md 都会处理

    文件的结构:Markdown 里 ## Drawing 下面的围栏( ```compressed-json 或 ```json )就是图的数据,压缩用的是 LZ-String 的 compressToBase64,每 256 个字符一段,段间空一行。文字元素存了两份:图的 JSON 里有 text,## Text Elements 里又有一份打字时的原文,每条后面跟 ^ 和 8 位元素 id。

    读取时的取舍:

    • 以图里保存的文字为准,也就是你上次在 Obsidian 里看到的样子。插件打开文件时会用 ## Text Elements 重新折行,折行要用浏览器的字体测量,这里做不到,所以只在图里的文字是空的时候才用 ## Text Elements 补上,并给出一条警告。
    • 手动改过 ## Text Elements 里的文字、和图里的不一致时,显示的仍是图里的,并给出一条警告(front matter 是 excalidraw-plugin: parsed 时两者本来就不同,不警告)。
    • 图片通常是 Obsidian 库里的文件,## Embedded Files 里只记路径,没有库就取不到,这些图片不会被画出来,警告里会写出它们的 [[路径]]。
    • LaTeX 公式和库里的其他嵌入内容同样取不到。

    测试:用插件的格式生成 19 个文件(压缩、不压缩、CRLF、单行、文字、库里的图片等),读出的 JSON 和原始场景逐字节相同,渲染结果和官方对原场景的导出逐字节相同;LZ-String 的压缩和解压对照 lz-string 1.5.0 逐字节一致。生成这些文件的脚本是 scripts/cases_obsidian.mjs。这些文件是按插件的文件格式写的,不是插件本身生成的。

    许可证:这里只参考了插件的文件格式,没有使用它的任何代码。插件仓库的 LICENSE 文件是 AGPL-3.0(package.json 里写的是 MIT,两者不一致),所以更是只看格式。LZ-String 是移植自 lz-string(MIT),不是插件的代码,版权声明在 THIRD_PARTY_LICENSES。

    #把一个文件夹的图变成网页

    moon run --target js src/cmd/excalidraw2site -- examples/site/diagrams -o examples/site/dist --title "我的图"

    读取文件夹里所有 .excalidraw 文件,生成 index.html、每张图的 SVG 和源文件副本。某张图渲染失败时其余照常生成,命令以非零码退出。怎么接到 GitHub Pages 或 CI,让图在每次提交时自动更新:见 examples/site(里面有可直接复制的工作流)。

    #支持范围

    内容状态
    元素:rectangle、diamond、ellipse(含圆角)支持
    元素:line、arrow(直线、曲线、12 种箭头样式)支持
    元素:freedraw(含闭合后的填充)支持
    元素:text(含绑定在矩形、菱形、椭圆、箭头里的文字)、image(含裁剪、翻转、圆角)、frame、magicframe支持
    样式:strokeColor、backgroundColor、fillStyle(hachure、cross-hatch、solid、zigzag)、strokeWidth、strokeStyle、roughness、opacity、angle、seed、link支持
    导出:画布大小、10px padding、背景色、元素顺序、frame 裁剪和标题、<a> 链接支持
    字体:FontMode::Url(官方取不到字体时的 @font-face URL 形式)、FontMode::None(对应 skipInliningFonts)支持
    容错:isDeleted、缺字段的旧文件(strokeSharpness、font、boundElementIds、draw 等)、未知字段支持
    Obsidian Excalidraw 插件的 .excalidraw.md(压缩的 compressed-json 和不压缩的 json,LF 或 CRLF)支持,见下面「Obsidian 文件」
    embeddable、iframe、肘形箭头(elbowed)、未知元素类型报错或跳过并警告,由调用方选择,不会静默画错
    命令行:excalidraw2svg(一个文件到一个 SVG,--strict、--no-fonts、-o)、excalidraw2site(一个文件夹到一个网页,可接 GitHub Pages 或 CI)支持,js 和 native 后端
    库:parse_scene、export_to_svg,wasm-gc 后端也能用支持
    对比:并排放本库和官方输出的静态页 gallery/index.html;在线演示页(浏览器里实时对照官方 exportToSvg)支持
    编辑和交互、PNG、协作、.excalidrawlib、深色模式、exportEmbedScene、导出单个 frame、字体子集化不做

    #和官方结果的差异

    下面这些是有意的,或者官方自己不确定:

    情况官方本库
    字体内联子集化后的 base64 字体只能是 URL 引用或不带字体。逐字节对照的是官方“取不到字体”时的输出
    embeddable、iframe、肘形箭头画占位框或肘形线报错或跳过并警告;跳过的元素也不计入画布大小
    未知元素类型静默丢弃同样不画,但给出警告
    缺 points 的 line/arrow、缺 pressures 又没开 simulatePressure 的 freedraw抛 TypeError,或画到一半静默丢掉这个元素整个文件返回 ParseError 并指出元素 id
    seed: 0用 Math.random,每次结果不同用 moon_rough 的固定回退序列,并给出警告
    重复的元素 id随机生成新 id保留,并给出警告
    frame 标题的宽度用浏览器 canvas 测量默认按每个字符 0.5 × 字号 估算,调用方可以传入 measure_text。只影响过长标题在哪里被截断
    标题截断时把一个代理对切成两半字符串里留下孤立代理项,保存成文件后是 U+FFFD直接输出 U+FFFD
    Math.pow(x, 3)(箭头标签位置用到)V8 调用平台的 C 库,最后一位随平台变化用正确舍入的立方;每次调用约有 0.04% 的概率和某个平台差最后一位
    画布里有一个 1e12 宽的 hachure 填充矩形内存耗尽(要画几十亿条线)同样的问题,没有额外保护
    Obsidian 文件里的文字插件打开文件时用 ## Text Elements 的原文,按浏览器的字体测量重新折行用图里保存的 text,只在它是空的时候才用 ## Text Elements 补上;两者不一致时警告
    Obsidian 文件里的库内图片、公式插件从库里读取取不到,不画,警告里写出 [[路径]]

    FontMode::Url 依赖官方包里的字体表(230 个字体文件及其 unicode-range)和 containsCJK 的字符集,字符集随生成 fixtures 的 Node 的 Unicode 版本而定。

    #对照结果

    预期值全部来自官方包,由 scripts/gen_fixtures.mjs 生成,不是手写的。moon test 对每个场景比较整份 SVG 字符串,不设数值容差;下面的表由 scripts/update_readme_stats.mjs 根据测试输出生成。

    SuiteWhat it coversScenesByte-identicalDifferent
    single basicRectangles, diamonds, ellipses × fill, stroke, roughness, roundness2522520
    single linearLines, arrows, closed fills, all arrowhead styles3623620
    single textText: every font id, alignment, direction, bound to shapes and arrows2002000
    single miscFreedraw, images, frames, links78780
    fontsFont rules (FontMode::Url) for each family and character set1851850
    combinedDiagrams (editor API, hand-made, random, and 3 drawn in the real editor)55550
    edge casesEmpty and degenerate scenes, extreme numbers, old formats, official errors65650
    obsidianObsidian .excalidraw.md files (compressed, plain, CRLF, texts, vault images) against the official export of the scene inside19190
    Total121612160

    Lower-level checkCasesDifferent
    perfect-freehand outlines, every number compared by bit pattern3220
    restoreElements normalisation of old and partial elements500
    JSON numbers read like V8 does100000
    LZ-String compress and decompress against lz-string 1.5.0 (the Obsidian file format)240
    Math.hypot52560
    Math.atan252560
    x³ correctly rounded (V8's Math.pow(x, 3) varies by platform)80000

    “Different”按差异类型分为结构不同、属性不同、数值不同,测试失败时会列出前几个失败场景的名字。

    预期值是在 Node 里用 jsdom 跑官方包得到的。为了确认 jsdom 的输出和真实浏览器一致,scripts/browser_check.mjs 在 Chromium 里对 21 个覆盖所有元素类型的场景重新导出,和 jsdom 的结果逐字节相同。在线演示页更进一步:官方包直接在访问者的浏览器里运行,和本库当场对照;CI 里的 scripts/demo_check.mjs 对示例图和真实编辑器画的图做同样的对照,发布页面之前必须先通过。

    场景的来源:

    • editor-api/:用官方 convertToExcalidrawElements(编辑器自己用来生成流程图的函数)构造,包括带标签的绑定箭头、frame、分组。
    • handmade/、random/:脚本写出的 JSON,包括旋转、透明度、固定种子的随机混合场景。
    • real/:3 个用鼠标在 excalidraw.com 上画出来的场景(流程图、frame、一个被删掉 frame 后遗留的混合场景),原样取自编辑器的存储。它们带有 0.18.1 之后才有的字段,官方 0.18.1 导出和本库都会忽略。详见 fixtures/scenes/SOURCES.md。
    • 没有 10 张手画图:用鼠标画图又慢又容易出错,所以手画的只有 3 张。

    #设计

    依赖方向从上到下。

    包核心逻辑
    export编排整个流程:过滤元素、给 frame 加标题文字、算画布大小(frame 里的元素不计入)、写根节点、裁剪路径、背景,再按顺序画每个元素,绑定文字紧跟它的容器
    shape把元素样式变成 rough 选项(线宽、虚线、小图形降低粗糙度),每类元素对应一次 rough 调用;箭头头部的方向取自 rough 画出的第一段或最后一段贝塞尔曲线,所以和 seed 有关;包围盒来自 rough 的路径
    freehandperfect-freehand 的 getStroke:先平滑输入点,再把笔迹向两侧偏移、加端帽,连成一个多边形
    text字体 id 到字体名和度量的表、基线位置的公式、RTL 判断、官方 @font-face 规则的选择
    svg一棵很小的 SVG 树,按 outerHTML 的规则序列化(属性顺序、转义)
    model读 JSON,丢掉已删除的元素,套用官方 restore 的规则补齐旧文件缺的字段;遇到 Obsidian 的 .excalidraw.md 就先交给 obsidian 取出场景
    obsidian找到 .excalidraw.md 里的 ## Drawing,解出 LZ-String 压缩的 JSON,并读出 ## Text Elements 和 ## Embedded Files;lzstring.mbt 是 lz-string 的 compressToBase64 和 decompressFromBase64
    site把一批 .excalidraw / .excalidraw.md 渲染成一个网页:每张图一个 SVG,用 <object> 嵌入(这样字体能加载、id 不冲突),某个文件坏了只在它的卡片上写明原因,其余照常
    cli、cmd/*命令行的参数解析和文件读写,逻辑都在库里,用假的文件系统测试,所以三个后端都能测
    web只导出一个 render 函数给 JavaScript,演示页的左边只调用它
    internal/jsnumMath.hypot、atan2、parseFloat 等 V8 行为,逐位对照

    一个容易忽略的细节:官方导出里,一个线性元素的“绝对坐标”取决于它的 rough 形状有没有被生成过(没生成过就用点估算,生成过就用真实曲线),所以导出结果依赖元素的绘制顺序。shape.ShapeCache 专门记录这个状态。

    #开发

    moon check --deny-warn moon fmt --check moon test --target all # js、wasm-gc、native

    重新生成 fixtures(需要 Node 24):

    cd scripts npm ci node gen_fixtures.mjs # 全部;也可以只跑某一组,如 `node gen_fixtures.mjs edge` cd .. && moon fmt # 生成的 .mbt 要格式化,之后和提交的应该完全一致 node scripts/update_readme_stats.mjs

    fixtures 的来源:scripts/package-lock.json 锁定 @excalidraw/excalidraw 0.18.1、perfect-freehand 1.2.0,并检查 roughjs 是 4.6.4、points-on-curve 是 1.0.1(官方 0.18.1 依赖的版本)。scripts/official_env.mjs 用 esbuild 打包官方发布的 bundle,在 jsdom 里运行,并补上 canvas、FontFace、Path2D 等几个桩。wasm-gc 后端读不了文件,所以生成的 fixtures 是内嵌在 src/internal/fixtures/ 里的 .mbt 文件。生成过程是可复现的:连续生成两次得到完全相同的文件。

    验证过 jsdom 的输出和真实 Chromium 一致:21 个覆盖所有元素类型的场景逐字节相同(scripts/browser_check.mjs)。

    演示页的源码在 demo/:src/web 把 render 函数导出成 JavaScript,页面的左边只调用它;官方包只画右边,页面里是分开加载的。本地构建和查看:

    moon build --target js --release cd scripts && npm ci node build_demo.mjs # 写到 demo-dist/ node serve.mjs ../demo-dist 4176

    node scripts/demo_check.mjs 用同一份 js 对示例图和真实编辑器画的图逐字节对照官方输出,CI 里会跑。页面对照时两边都不带字体、都用每字符 7px 的文字宽度(和测试一致),只影响 frame 标题。推送到 main 时 .github/workflows/pages.yml 会把页面发布到 GitHub Pages(仓库设置里 Pages 的 Source 要选 GitHub Actions)。

    CI 见 .github/workflows/check.yml:在 Linux、macOS、Windows 上跑 moon check --deny-warn、moon build、moon test(都带 --target all)、moon fmt --check,再确认 moon info 之后 git diff 为空;另有一个 job 安装 Node,重新生成 fixtures 并要求和仓库里的完全一致,同时检查 README 的对照表。Node 版本固定在 scripts/.nvmrc(24.20.0),因为 containsCJK 的字符集随 Node 的 Unicode 版本而定。

    #依赖 moon_rough 0.3.0

    官方用 rough.js 4.6.4,moon_rough 默认对应 4.6.6,两者在三处不同:hachureGap 是否取整、3 点曲线的填充算法、2 点曲线的画法。moon_rough 的 roughjs_464 选项还原了 4.6.4 的行为(8148 个数值逐位一致)。这个选项和本库用到的 Generator::polygon_points 都在已发布的 moon_rough 0.3.0 里,moon.mod 依赖的就是这个版本,克隆仓库后直接 moon test 即可,不需要本地副本。

    想同时改 moon_rough 和本库时,可以在仓库根目录用 moon work init . <moon_rough 的本地路径> 生成 moon.work(已被 .gitignore 忽略,不会提交),用完删掉。

    #参考来源和许可证

    本项目以 MIT 许可证发布(见 LICENSE)。

    只参考了下列项目的规范和行为,用 MoonBit 重新实现,没有复制它们的源文件。原作者的版权声明和许可证全文保留在 THIRD_PARTY_LICENSES:

    • excalidraw(MIT):元素模型、图形生成、SVG 导出
    • perfect-freehand(MIT):手绘笔迹轮廓
    • @braintree/sanitize-url(MIT):链接清理
    • V8(BSD-3-Clause,其中的 fdlibm 例程):Math.atan2、Math.hypot
    • roughjs(MIT):通过 moon_rough 使用
    • lz-string 1.5.0(MIT):src/obsidian/lzstring.mbt 是它 compressToBase64 和 decompressFromBase64 的移植,测试里的预期值由它生成
    • Obsidian Excalidraw 插件:只参考了 .excalidraw.md 的文件格式,没有使用它的代码;仓库的 LICENSE 是 AGPL-3.0

    这个项目用到了 AI 工具辅助开发。所有预期值来自官方包的真实输出,不是 AI 生成的。

    export_to_svg

    Renders a scene the way the official exportToSvg does. measure_text gives the width of frame titles, the only text measured at export time; the default estimates half the font size per character.

    parse_scene

    Reads a .excalidraw file. Elements marked isDeleted are dropped here, as the official editor does before it calls exportToSvg.