From edc62c550adc480423e333890cd78591d41c9ada Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Tue, 16 Mar 2021 22:21:56 +0530 Subject: [PATCH] feat: Export API's to export the drawing to canvas, svg and blob (#3258) * feat: Export utilities from package/utils * update * fix * collapsible * Update README.md * update change * update * fix * Apply suggestions from code review Co-authored-by: David Luzar * Apply suggestions from code review Co-authored-by: David Luzar * update * Apply suggestions from code review Co-authored-by: David Luzar --- src/packages/excalidraw/CHANGELOG.md | 1 + src/packages/excalidraw/README.md | 90 ++++++++++++++++++++++++++++ src/packages/excalidraw/index.tsx | 5 ++ src/packages/utils.ts | 32 ++++++---- 4 files changed, 117 insertions(+), 11 deletions(-) diff --git a/src/packages/excalidraw/CHANGELOG.md b/src/packages/excalidraw/CHANGELOG.md index ec8bd23bf..a949b1d63 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.md index 6cd8b652e..26474b520 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)_** + +
+Export utilities + +#### `exportToCanvas` + +**_Signature_** + +
exportToCanvas({
+  elements,
+  appState
+  getDimensions,
+}: ExportOpts
+
+ +| 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_** + +
+exportToBlob(
+  opts: ExportOpts & {
+  mimeType?: string,
+  quality?: number;
+})
+
+ +| 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_** + +
+exportToSvg({
+  elements: ExcalidrawElement[],
+  appState: AppState,
+  exportPadding?: number,
+  metadata?: string,
+}
+
+ +| 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 | + +
diff --git a/src/packages/excalidraw/index.tsx b/src/packages/excalidraw/index.tsx index 8c1e3b1f1..868cf47cf 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.ts index 25731ef66..0f4c1c402 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?: Partial>; 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, });