Virtual whiteboard for sketching hand-drawn like diagrams
feat: Export API's to export the drawing to canvas, svg and blob (#3258)
Aakansha Doshiedc62c550adc
diff --git a/src/packages/excalidraw/CHANGELOG.md b/src/packages/excalidraw/CHANGELOG.mdindex ec8bd23bff..a949b1d638 100644--- a/src/packages/excalidraw/CHANGELOG.md+++ b/src/packages/excalidraw/CHANGELOG.md@@ -18,6 +18,7 @@ Please add the latest change on the top under the correct section.### Features+- Export API to export the drawing to canvas, svg and blob [#3258](https://github.com/excalidraw/excalidraw/pull/3258). For more info you can check the [readme](https://github.com/excalidraw/excalidraw/tree/master/src/packages/excalidraw/README.md#user-content-export-utils)- Add a `theme` prop to indicate Excalidraw's theme. [#3228](https://github.com/excalidraw/excalidraw/pull/3228). When this prop is passed, the theme is fully controlled by host app.- Support `libraryReturnUrl` prop to indicate what URL to install libraries to [#3227](https://github.com/excalidraw/excalidraw/pull/3227).diff --git a/src/packages/excalidraw/README.md b/src/packages/excalidraw/README.mdindex 6cd8b652ef..26474b5202 100644--- a/src/packages/excalidraw/README.md+++ b/src/packages/excalidraw/README.md@@ -635,3 +635,93 @@ import { restore } from "@excalidraw/excalidraw";```This function makes sure elements and state is set to appropriate values and set to default value if not present. It is combination of [restoreElements](#restoreElements) and [restoreAppState](#restoreAppState)++**_The below APIs will be available in [next version](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/CHANGELOG.md#unreleased)_**++<details id="export-utils">+<summary><strong>Export utilities</strong></summary>++#### `exportToCanvas`++**_Signature_**++<pre+>exportToCanvas({+ elements,+ appState+ getDimensions,+}: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L10">ExportOpts</a>+</pre>++| Name | Type | Default | Description |+| --- | --- | --- | --- |+| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types) | | The elements to be exported to canvas |+| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L12) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |+| getDimensions | `(width: number, height: number) => {width: number, height: number, scale: number)` | `(width, height) => ({ width, height, scale: 1 })` | A function which returns the width, height and scale with which canvas is to be exported. |++**How to use**++```js+import { exportToCanvas } from "@excalidraw/excalidraw";+```++This function returns the canvas with the exported elements, appState and dimensions.++#### `exportToBlob`++**_Signature_**++<pre>+exportToBlob(+ opts: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L10">ExportOpts</a> & {+ mimeType?: string,+ quality?: number;+})+</pre>++| Name | Type | Default | Description |+| --- | --- | --- | --- |+| opts | | | This param is passed to `exportToCanvas`. You can refer to [`exportToCanvas`](#exportToCanvas) |+| mimeType | string | "image/png" | Indicates the image format |+| quality | number | 0.92 | A value between 0 and 1 indicating the [image quality](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob#parameters). Applies only to `image/jpeg`/`image/webp` MIME types. |++**How to use**++```js+import { exportToBlob } from "@excalidraw/excalidraw";+```++Returns a promise which resolves with a [blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob). It internally uses [canvas.ToBlob](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob).++#### `exportToSvg`++**_Signature_**++<pre>+exportToSvg({+ elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>,+ appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a>,+ exportPadding?: number,+ metadata?: string,+}+</pre>++| Name | Type | Default | Description |+| --- | --- | --- | --- |+| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78) | | The elements to exported as svg |+| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |+| exportPadding | number | 10 | The padding to be added on canvas |+| metadata | string | '' | The metadata to be embedded in svg |++This function returns a svg with the exported elements.++##### Additional attributes of appState for `export\*` APIs++| Name | Type | Default | Description |+| --- | --- | --- | --- |+| exportBackground | boolean | true | Indicates whether background should be exported |+| viewBackgroundColor | string | #fff | The default background color |+| shouldAddWatermark | boolean | false | Indicates whether watermark should be exported |+| exportWithDarkMode | boolean | false | Indicates whether to export with dark mode |++</details>diff --git a/src/packages/excalidraw/index.tsx b/src/packages/excalidraw/index.tsxindex 8c1e3b1f13..868cf47cff 100644--- a/src/packages/excalidraw/index.tsx+++ b/src/packages/excalidraw/index.tsx@@ -112,3 +112,8 @@ export {} from "../../element";export { defaultLang, languages } from "../../i18n";export { restore, restoreAppState, restoreElements } from "../../data/restore";+export {+ exportToCanvas,+ exportToBlob,+ exportToSvg,+} from "../../packages/utils";diff --git a/src/packages/utils.ts b/src/packages/utils.tsindex 25731ef66a..0f4c1c402e 100644--- a/src/packages/utils.ts+++ b/src/packages/utils.ts@@ -6,10 +6,11 @@ import { getDefaultAppState } from "../appState";import { AppState } from "../types";import { ExcalidrawElement } from "../element/types";import { getNonDeletedElements } from "../element";+import { restore } from "../data/restore";type ExportOpts = {elements: readonly ExcalidrawElement[];- appState?: Omit<AppState, "offsetTop" | "offsetLeft">;+ appState?: Partial<Omit<AppState, "offsetTop" | "offsetLeft">>;getDimensions: (width: number,height: number,@@ -18,17 +19,22 @@ type ExportOpts = {export const exportToCanvas = ({elements,- appState = getDefaultAppState(),+ appState,getDimensions = (width, height) => ({ width, height, scale: 1 }),}: ExportOpts) => {+ const { elements: restoredElements, appState: restoredAppState } = restore(+ { elements, appState },+ null,+ );+ const {+ exportBackground,+ viewBackgroundColor,+ shouldAddWatermark,+ } = restoredAppState;return _exportToCanvas(- getNonDeletedElements(elements),- { ...appState, offsetTop: 0, offsetLeft: 0 },- {- exportBackground: appState.exportBackground ?? true,- viewBackgroundColor: appState.viewBackgroundColor ?? "#FFF",- shouldAddWatermark: appState.shouldAddWatermark ?? false,- },+ getNonDeletedElements(restoredElements),+ { ...restoredAppState, offsetTop: 0, offsetLeft: 0 },+ { exportBackground, viewBackgroundColor, shouldAddWatermark },(width: number, height: number) => {const canvas = document.createElement("canvas");const ret = getDimensions(width, height);@@ -81,8 +87,12 @@ export const exportToSvg = ({exportPadding?: number;metadata?: string;}): SVGSVGElement => {- return _exportToSvg(getNonDeletedElements(elements), {- ...appState,+ const { elements: restoredElements, appState: restoredAppState } = restore(+ { elements, appState },+ null,+ );+ return _exportToSvg(getNonDeletedElements(restoredElements), {+ ...restoredAppState,exportPadding,metadata,});