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 <luzar.david@gmail.com> * Apply suggestions from code review Co-authored-by: David Luzar <luzar.david@gmail.com> * update * Apply suggestions from code review Co-authored-by: David Luzar <luzar.david@gmail.com>
2021-03-16 22:21:56 +05:30
parent 84a1863233
commit edc62c550a
4 changed files with 117 additions and 11 deletions
@@ -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>