产品经理：客户想要个画板，你们前端能不能做？

创建项目并安装 excalidraw 包#

需要在 react 项目中使用，使用 vite 初始化一个 react 项目并通过 npm 安装 excalidraw：

1
# 安装@excalidraw/excalidraw包
2
yarn add @excalidraw/excalidraw

excalidraw 占用父元素 100% 宽度和高度，因此需要确保在其中呈现 excalidraw 的容器具有非零尺寸：

1
import { Excalidraw } from '@excalidraw/excalidraw'
2
function App() {
3
  return (
4
    <>
5
      <h1 style={{ textAlign: 'center' }}>Excalidraw Example</h1>
6
      <div style={{ height: 800, width: 800 }}>
7
        <Excalidraw />
8
      </div>
9
    </>
10
  )
11
}

一个功能完善的 excalidraw 项目就已经可以直接用了：

如何自定义样式#

使用CSS 变量，通过修改 excalidraw 所提供的 CSS 变量达到修改样式的效果，如顶部按钮背景色、鼠标 hover 状态等。

我们可以通过审查找到对应的元素，然后看元素对应的样式，只要是使用变量的这些我们都可以改。

1
<div style={{ height: 800, width: 800 }} className="one-excalidraw">
2
  <Excalidraw />
3
</div>

1
.one-excalidraw .excalidraw {
2
  --color-primary: #faa2c1;
3
  --color-primary-darker: #f783ac;
4
  --color-primary-darkest: #e64980;
5
  --color-primary-light: #fcc2d7;
6
}

Props: 传递 Excalidraw 的参数#

可选的 Props

Excalidraw 提供的 Props 很多，都是可选的。我们可以用来设置白板初始值、语言、一些操作的默认显示/隐藏状态等

• initialData

  用于加载 Excalidraw 画板的初始数据，接受一个对象，包含 elements、appState、files 等参数。 通过 appState 我们可以修改默认的一些样式，如 theme、background 等，我整理了一些配置如下：

  1
  export enum RoughnessEnum {
  2
    /** 直线 */
  3
    architect,
  4
    /** 艺术 */
  5
    artist,
  6
    /** 漫画家 */
  7
    cartoonist,
  8
  }
  9
  /** 边角风格 */
  10
  export enum RoundnessEnum {
  11
    /** 直角 */
  12
    sharp = 'sharp',
  13
    /** 圆角 */
  14
    round = 'round',
  15
  }
  16
  /** 字体风格 */
  17
  export enum FontFamilyEnum {
  18
    /** 艺术 */
  19
    'hand-drawn' = 1,
  20
    /** 普通 */
  21
    normal,
  22
    /** 代码 */
  23
    code,
  24
  }

  展开收起

• ref

  如果我们需要访问某些 Excalidraw API 时，可以通过传递一个 ref 来获取 Excalidraw 的实例，然后就可以在当前组件中去调用 Excalidraw 的 API，比如 current.refresh()、current.resetScene()等

• langCode

  Excalidraw 默认是英文的，需要设置为中文langCode='zh-CN'，所有支持的语言看这里

• viewModeEnabled

  是否是观察模式，即不可编辑，优先级高于intialData.appState.viewModeEnabled。类似的还有 zenModeEnabled 禅模式、gridModeEnabled 显示网格

• libraryReturnUrl

  用于指定安装模板的地址，默认为 window.location.origin + window.location.pathname；需要设置window.name=任何字母数字字符串，如果未设置时会打开新的选项卡。

  设置window.name和不设置时，跳到模板界面的 url 的不同，不设置时 target 为_blank，看到_blank就会联想到 a 标签的_blank，新页签打开

  

  excalidraw 源码 excalidraw-library 源码

  而想要正常的加载模板，还需要搭配useHandleLibrary来使用，否则添加模板不成功。

• Render Props

  可以用来自定义 UI，如renderTopRightUI用于自定义右上角的 UI，renderCustomStats用于自定义统计信息，renderSidebar用于自定义侧边栏 更多参考

• UIOptions

  主要用于自定义 Excalidraw 默认画布，如canvasActions用于控制菜单内画布操作的可见性，通过设置canvasActions.toggleTheme即可将切换主题的按钮去掉，exportOpts用于自定义导出对话框，dockedSidebarBreakpoint用于控制”侧边栏常驻”按钮是否显示，如果设置dockedSidebarBreakpoint数值小于 Excalidraw 的容器宽度时，显示此按钮，否则隐藏。

• onChange

  每次 Excalidraw 内容发生改变时，通过 onchange 回调函数获取最新的数据，包括 excalidrawElements（当前白板中的 excalidrawElements 数组）、appState（白板的一些状态）、files（添加到白板中的文件）。

  获取到这些数据后，就可以将数据保存到后端或选择本地存储。

• validateEmbeddable

  最新的 Excalidraw 支持 Web Embed 网页嵌入功能，可以将网页 url 复制到此组件中进行展示。默认情况下，仅支持 YouTube, Vimeo, Twitter, Excalidraw, Figma 这几个网站的 url，如果传递 true，则所有 URL 都可以支持。

Children components: 可用于自定义 UI 的官方组件#

在 Props 里，我们看到可以通过Render Props来自定义内部组件，Excalidraw 官方正在将这些 Render Props 迁移到子组件类型，目前只支持以下四种：

• MainMenu 自定义左侧菜单

  用于自定义左侧首选项菜单栏，提供多种类型的子组件供我们使用

• WelcomeScreen 自定义欢迎界面

  画布为空时展示的界面，包括一些快速操作项以及解释某些 UI 按钮功能的提示，一旦用户选择了一个工具，或者在画布上创建了一个元素，此界面就会消失。

  也可以自定义此组件，生成自己的欢迎界面。

• Footer 自定义底部工具栏

  用于自定义底部的操作栏，可以使用 useDevice 挂钩来检查设备类型，然后显示不同的样式。

• LiveCollaborationTrigger 自定义实时协作功能

  如果需要显示实时协作功能，需要在renderTopRightUIprops 中使用<LiveCollaborationTrigger/>组件来呈现。

Utils: 工具函数及可用于导出、恢复等的实用程序#

从@excalidraw/excalidraw 导出的纯函数，像前面提到的 useDevice 函数检查设备信息、usehandlelibrary 函数等

数据存储方案#

通过调用 onChange 方法，可以获取修改后的数据，数据格式如下：

1
{
2
  "excalidrawElements": [],
3
  "appState": {},
4
  "files": {}
5
}

• excalidrawElements: 画布中的每个元素，格式，
• appState：当前画布的配置信息，格式，不需要存储，
• files: 上传到白板中的文件，如：图片，以 base64 格式存储格式

缺点#

npm 包目前不支持：多人协作、共享链接等，不过 Excalidraw 团队已经在规划当中，不久就会以插件的形式支持。 如何实现协作：https://github.com/excalidraw/excalidraw/discussions/3879

github 地址：https://github.com/wang1xiang/excalidraw-demo，求 star^_^~