Excalidraw Math Preview

在 VS Code 中绘制 Excalidraw 图形，并直接输入、保存和重新编辑 LaTeX / AsciiMath 公式。

非官方扩展。 使用 Excalidraw 数学预览版 的数学编辑实现，基于该网站版本 2024-10-07T00:09:35Z-c93e2fa 对应的源码构建，与 Excalidraw 官方团队没有隶属或背书关系。来源记录见安装包中的 UPSTREAM.json。

Unofficial VS Code integration of the Excalidraw math preview. Draw diagrams with editable LaTeX and AsciiMath formulas, save local files, and import reusable shapes from the Excalidraw library catalog. The editor and MathJax run locally; no preview-site account is required.

功能

• 绘制手绘风格的图形、流程图及数学示意图。
• 输入 LaTeX 或 AsciiMath，双击公式可编辑原始表达式。
• 支持 .excalidraw、.excalidraw.json，以及内嵌画布数据的 .excalidraw.svg / .excalidraw.png。
• 通过“浏览素材库”在线添加素材，导入后可持久保存。
• 编辑器和公式渲染在本地运行，支持中文界面及深浅色主题。

安装和打开

在 VS Code 扩展面板搜索 Excalidraw Math Preview，选择发布者 ChaoyangLuo。也可以运行：

code --install-extension ChaoyangLuo.excalidraw-math-preview

要求 VS Code 1.74 或更高版本。安装扩展后，右键 .excalidraw 文件，选择“打开方式…” → Excalidraw Math Preview。如需默认使用它，选择“配置默认编辑器…”。

如果使用 VSIX 安装包，在命令面板运行 Extensions: Install from VSIX…，选择下载的 .vsix 文件。更新后若提示重新加载窗口，请先完成重新加载。

新建画布：命令面板 → Excalidraw Math Preview: New File，或新建一个空的 .excalidraw 文件并用本扩展打开。

输入公式

点击顶部工具栏右侧的数学按钮（根号图标），或按 M 开启数学工具，再点击画布输入。右键数学按钮可切换 Standard input（LaTeX）和 Simplified input（AsciiMath）。

在左侧选择 Math only 后，可直接输入：

\frac{a}{b} + \sqrt{x^2+y^2}

在 Mixed text 模式中，LaTeX 数学内容使用 \(...\) 包裹，例如 距离：\(d=\sqrt{x^2+y^2}\)。AsciiMath 混排内容使用反引号包裹。双击公式可重新编辑原始表达式。

使用 Ctrl+S（macOS：Cmd+S）保存。支持 .excalidraw / .excalidraw.json，以及内嵌源数据的 .excalidraw.svg / .excalidraw.png。普通 SVG/PNG 图片不包含可编辑的画布源数据。

在线素材库

打开素材库面板，点击“浏览素材库”，会在系统浏览器中打开官方素材网站。选择素材后点击 Add to Excalidraw；浏览器提示打开 Visual Studio Code 时选择允许。素材会导入当前扩展并保存，重新打开画布后仍可使用。

此回跳流程适用于桌面版 VS Code。也可以通过素材库菜单导入已下载的 .excalidrawlib 文件。外部链接和公共素材库需要联网。下载失败会在 VS Code 中显示错误原因。

设置

{
  "excalidrawMath.language": "zh-CN",
  "excalidrawMath.theme": "auto"
}

如需配置默认关联，将以下条目合并进现有 workbench.editorAssociations 对象：

{
  "workbench.editorAssociations": {
    "*.excalidraw": "editor.excalidrawMath",
    "*.excalidraw.json": "editor.excalidrawMath",
    "*.excalidraw.svg": "editor.excalidrawMath",
    "*.excalidraw.png": "editor.excalidrawMath"
  }
}

通过 excalidrawMath.workspaceLibraryPath 可指定相对于工作区根目录的素材库文件路径；未设置时，素材保存在 VS Code 用户存储中。

版本与兼容性

自动验证包括离线公式渲染、LaTeX/AsciiMath 编辑、创建数学元素、保存时刷新待处理内容，以及 JSON/SVG/PNG 的保存和重新编辑。另有文件保存等待、错误传播、备份和恢复、素材库导入与持久保存测试。编辑器本地运行，无需访问预览网站。

桌面端安装和素材库回跳已在 Windows 上使用验证；macOS、Linux 及浏览器版 VS Code 尚未进行完整实机验证。

这是固定版本的预览源码，未来网页更新不会自动同步到扩展。数学元素使用预览版特有的 subtype / customData；需要继续编辑公式时，请使用这个扩展或相同数学预览版。

来源和许可证

• 数学编辑器：excalidraw/excalidraw，MIT 许可证。
• VS Code 集成基于 excalidraw/excalidraw-vscode，保留原项目版权及 MIT 许可证。
• 公式渲染：MathJax，Apache-2.0 许可证，包含上游 Excalidraw 提供的浏览器补丁。

安装包内的 UPSTREAM.json 记录精确源码版本，LICENSE 和 THIRD_PARTY_NOTICES.txt 包含版权及第三方许可证说明。

从源码构建

源项目与 excalidraw-math-upstream 放在同一父目录下。首次准备：

npm install
npm run prepare-upstream
npm run package
npm test
npm run typecheck

prepare-upstream 下载并核验固定的官方源码版本，仅安装编辑器所需的运行依赖，并应用官方 MathJax 浏览器补丁。

浏览器回归测试通过已有 @vscode/test-web 的 Playwright 运行，默认使用本机 Chromium 1208，可修改测试脚本中的 executablePath 适配其他机器：

npm run test:browser

打包：npx @vscode/vsce package --no-dependencies --allow-missing-repository。发布者标识必须与实际 Marketplace 发布者一致。