# @dwelle/excalidraw 中文文档

规范地址：https://npmcn.com/package/%40dwelle/excalidraw/

版本：0\.5\.0-88aedd6
npm 元数据更新时间：2026-11-12T18:05:51.759Z
中文译文更新时间：2026-11-13T01:18:28.740Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dwelle/excalidraw
原文对照：https://npmcn.com/package/%40dwelle/excalidraw/?lang=original
项目主页：https://github.com/excalidraw/excalidraw/tree/master/packages/excalidraw
源码仓库：https://github.com/excalidraw/excalidraw

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：53 MB，1256 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：33 个
- peer 依赖：react ^17\.0\.2 \|\| ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^17\.0\.2 \|\| ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2021-07-03T20:12:57.640Z
- 最新版本发布：2026-11-12T18:05:50.801Z
- 近 30 天下载量：8772（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：587（近 12 个月 116 个）

## 中文简介

作为反应组件的 excalidraw

## 安装

```sh
npm install @dwelle/excalidraw
```

也可以使用：`pnpm add @dwelle/excalidraw`、`yarn add @dwelle/excalidraw`、`bun add @dwelle/excalidraw`

## README

# 缩略图

**缩略图** 被导出为可直接嵌入到应用程序中的反效果组件.

## 安装

将软件包及其对应端依赖性一起安装 .

```bash
npm install react react-dom @excalidraw/excalidraw
# or
yarn add react react-dom @excalidraw/excalidraw
```

> **说明**: 如果你想尝试未释放的更改,请使用 `@excalidraw/excalidraw@next`。 。 。 .

## 快开始

最低工作设置有两个容易出错的要求:

1.  导入软件包 CSS :

```ts
import "@excalidraw/excalidraw/index.css";
```

2.  Render Excalidraw在非零高的容器内.

```tsx
import { Excalidraw } from "@excalidraw/excalidraw";
import "@excalidraw/excalidraw/index.css";

export default function App() {
  return (
    <div style={{ height: "100vh" }}>
      <Excalidraw />
    </div>
  );
}
```

Excalidraw 填充 `100%` 的宽度和高度。 如果父母没有身高,画布就看不到了.

## 下一.js/安全部门改革框架

应当对客户端进行Excalidraw. 在SSR框架如Next.js中,使用客户端组件并动态地加载SSR已禁用.

```tsx
// app/components/ExcalidrawClient.tsx
"use client";

import { Excalidraw } from "@excalidraw/excalidraw";
import "@excalidraw/excalidraw/index.css";

export default function ExcalidrawClient() {
  return (
    <div style={{ height: "100vh" }}>
      <Excalidraw />
    </div>
  );
}
```

```tsx
// app/page.tsx
import dynamic from "next/dynamic";

const ExcalidrawClient = dynamic(
  () => import("./components/ExcalidrawClient"),
  { ssr: false },
);

export default function Page() {
  return <ExcalidrawClient />;
}
```

完整的设置请参见本地示例 :

-   [实例/附带](https://github.com/excalidraw/excalidraw/tree/master/examples/with-nextjs)
-   [例/ 有书写浏览器](https://github.com/excalidraw/excalidraw/tree/master/examples/with-script-in-browser)

## LLM / 代理提示

如果 LLM 或编码代理正在设置 Excalidraw , 这些快捷键通常比重发时节省更多的时间 :

-   从平原开始 `<Excalidraw />` 在一个 `100vh` 集装箱。 增加裁判员, `initialData`, 持久性, 或自定义 UI 仅在基底嵌入工作之后.
-   如果画布为空白, 请先检查 CSS 导入和母高 。 这是两个最常见的一体化失败.
-   在 Next.js 或其他SSSR 框架中,先假设只客户渲染. 使用 `"use client"` 财务报告和审定财务报表 `dynamic(..., { ssr: false })` 在调试水合物之前或 `window is not defined` 错误.
-   如果进口或入境点不明确,则检查 `node_modules/@excalidraw/excalidraw/package.json`。安装的软件包导出是真理的来源.
-   未设置 `window.EXCALIDRAW_ASSET_PATH` 除非您是故意自宿字体/资产.
-   当文档和生成代码漂移时, 请复制此 repo 中最近的工作示例, 特别是 `examples/with-nextjs` 或者说 `examples/with-script-in-browser`。 。 。 .

## 移动到 `@excalidraw/excalidraw@0.18.x`

版本 `0.18.x` 删除旧的 `types/`\- 前置的深导入路径。 如果您从 `@excalidraw/excalidraw/types/...`,切换到下面的新类型的子路径.

| 旧路径 | 新路径 |
| --- | --- |
| `@excalidraw/excalidraw/types/data/transform.js` | `@excalidraw/excalidraw/element/transform` |
| `@excalidraw/excalidraw/types/data/types.js` | `@excalidraw/excalidraw/data/types` |
| `@excalidraw/excalidraw/types/element/types.js` | `@excalidraw/excalidraw/element/types` |
| `@excalidraw/excalidraw/types/utility-types.js` | `@excalidraw/excalidraw/common/utility-types` |
| `@excalidraw/excalidraw/types/types.js` | `@excalidraw/excalidraw/types` |

放下枪 `.js` 扩展名。 新的一揽子计划 `exports` 地图可以解决这些路径.

这些深潜道是用于 `import type` 只有这个 运行时导入应来自软件包根,加 `@excalidraw/excalidraw/index.css` 对于风格.

例如:

```ts
import { exportToSvg } from "@excalidraw/excalidraw";
```

## 自宿字体

默认情况下, Excalidraw 下载所需的字体 [光盘N](https://esm.run/@excalidraw/excalidraw/dist/prod)。 。 。 .

自我接待,复制内容 `node_modules/@excalidraw/excalidraw/dist/prod/fonts` 进入您的应用程序为静态资产服务的路径, 例如 `public/`设置 `window.EXCALIDRAW_ASSET_PATH` 走向同一路径:

```html
<script>
  window.EXCALIDRAW_ASSET_PATH = "/";
</script>
```

## 演示

试试看 [代码框示例](https://codesandbox.io/p/sandbox/github/excalidraw/excalidraw/tree/master/examples/with-script-in-browser)。 。 。 .

## 一体化

读取 [综合文件](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/integration)。 。 。 .

## API 密码

读取 [API 文件](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api)。 。 。 .

## 捐款

读取 [提供文件](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/contributing)。 。 。 .

## 常见问题

### @dwelle/excalidraw 是什么？

作为反应组件的 excalidraw

### 如何安装 @dwelle/excalidraw？

在项目目录运行 npm install @dwelle/excalidraw，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.2 \|\| ^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^17\.0\.2 \|\| ^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dwelle/excalidraw 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dwelle/excalidraw 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dwelle/excalidraw 可以商用吗？

@dwelle/excalidraw 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dwelle/excalidraw 的下载量有多少？

根据 npm 官方下载统计，@dwelle/excalidraw 在 2026/10/13 – 2026/11/11 这 30 天内被下载 8,772 次，日均约 292 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dwelle/excalidraw 还在维护吗？

最新版本 0\.5\.0-88aedd6 发布于 2026/11/13（今天）；至今共发布 587 个版本，其中过去 12 个月发布了 116 个；首次发布于 2021/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。