|
|
@@ -126,7 +126,7 @@ export default function App() {
|
|
|
<Excalidraw
|
|
|
ref={excalidrawRef}
|
|
|
initialData={InitialData}
|
|
|
- onChange={(elements, state) => {
|
|
|
+ onChange={(elements, state) =>
|
|
|
console.log("Elements :", elements, "State : ", state)
|
|
|
}
|
|
|
onPointerUpdate={(payload) => console.log(payload)}
|
|
|
@@ -173,7 +173,7 @@ For development use :point_down:
|
|
|
```js
|
|
|
<script
|
|
|
type="text/javascript"
|
|
|
- src="https://unpkg.com/@excalidraw/excalidraw@0.6.0/dist/excalidraw.development.js"
|
|
|
+ src="https://unpkg.com/@excalidraw/excalidraw@0.7.0/dist/excalidraw.development.js"
|
|
|
></script>
|
|
|
```
|
|
|
|
|
|
@@ -182,7 +182,7 @@ For production use :point_down:
|
|
|
```js
|
|
|
<script
|
|
|
type="text/javascript"
|
|
|
- src="https://unpkg.com/@excalidraw/excalidraw@0.6.0/dist/excalidraw.production.min.js"
|
|
|
+ src="https://unpkg.com/@excalidraw/excalidraw@0.7.0/dist/excalidraw.production.min.js"
|
|
|
></script>
|
|
|
```
|
|
|
|
|
|
@@ -201,7 +201,7 @@ You will need to make sure `react`, `react-dom` is available as shown in the bel
|
|
|
|
|
|
<script
|
|
|
type="text/javascript"
|
|
|
- src="https://unpkg.com/@excalidraw/excalidraw@0.6.0/dist/excalidraw.development.js"
|
|
|
+ src="https://unpkg.com/@excalidraw/excalidraw@0.7.0/dist/excalidraw.development.js"
|
|
|
></script>
|
|
|
</head>
|
|
|
|
|
|
@@ -364,6 +364,10 @@ To view the full example visit :point_down:
|
|
|
| [`theme`](#theme) | `light` or `dark` | | The theme of the Excalidraw component |
|
|
|
| [`name`](#name) | string | | Name of the drawing |
|
|
|
| [`UIOptions`](#UIOptions) | <pre>{ canvasActions: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L208"> CanvasActions<a/> }</pre> | [DEFAULT UI OPTIONS](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L129) | To customise UI options. Currently we support customising [`canvas actions`](#canvasActions) |
|
|
|
+| [`onPaste`](#onPaste) | <pre>(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L17">ClipboardData</a>, event: ClipboardEvent | null) => boolean</pre> | | Callback to be triggered if passed when the something is pasted in to the scene |
|
|
|
+| [`detectScroll`](#detectScroll) | boolean | true | Indicates whether to update the offsets when nearest ancestor is scrolled. |
|
|
|
+| [`handleKeyboardGlobally`](#handleKeyboardGlobally) | boolean | false | Indicates whether to bind the keyboard events to document. |
|
|
|
+| [`onLibraryChange`](#onLibraryChange) | <pre>(items: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200">LibraryItems</a>) => void | Promise<any> </pre> | | The callback if supplied is triggered when the library is updated and receives the library items. |
|
|
|
|
|
|
### Dimensions of Excalidraw
|
|
|
|
|
|
@@ -392,6 +396,7 @@ This helps to load Excalidraw with `initialData`. It must be an object or a [pro
|
|
|
| `elements` | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78) | The elements with which Excalidraw should be mounted. |
|
|
|
| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L37) | The App state with which Excalidraw should be mounted. |
|
|
|
| `scrollToContent` | boolean | This attribute implies whether to scroll to the nearest element to center once Excalidraw is mounted. By default, it will not scroll the nearest element to the center. Make sure you pass `initialData.appState.scrollX` and `initialData.appState.scrollY` when `scrollToContent` is false so that scroll positions are retained |
|
|
|
+| `libraryItems` | [LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L151) | This library items with which Excalidraw should be mounted. |
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
@@ -438,10 +443,11 @@ You can pass a `ref` when you want to access some excalidraw APIs. We expose the
|
|
|
| getSceneElements | <pre> () => <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a></pre> | Returns all the elements excluding the deleted in the scene |
|
|
|
| getAppState | <pre> () => <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L37">AppState</a></pre> | Returns current appState |
|
|
|
| history | `{ clear: () => void }` | This is the history API. `history.clear()` will clear the history |
|
|
|
-| setScrollToContent | <pre> (<a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>) => void </pre> | Scroll to the nearest element to center |
|
|
|
+| scrollToContent | <pre> (target?: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a> | <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a>[]) => void </pre> | Scroll the nearest element out of the elements supplied to the center. Defaults to the elements on the scene. |
|
|
|
| refresh | `() => void` | Updates the offsets for the Excalidraw component so that the coordinates are computed correctly (for example the cursor position). You don't have to call this when the position is changed on page scroll or when the excalidraw container resizes (we handle that ourselves). For any other cases if the position of excalidraw is updated (example due to scroll on parent container and not page scroll) you should call this API. |
|
|
|
| [importLibrary](#importlibrary) | `(url: string, token?: string) => void` | Imports library from given URL |
|
|
|
| setToastMessage | `(message: string) => void` | This API can be used to show the toast with custom message. |
|
|
|
+| [id](#id) | string | Unique ID for the excalidraw component. |
|
|
|
|
|
|
#### `readyPromise`
|
|
|
|
|
|
@@ -528,7 +534,7 @@ This prop controls Excalidraw's theme. When supplied, the value takes precedence
|
|
|
|
|
|
This prop sets the name of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence over `intialData.appState.name`, the `name` will be fully controlled by host app and the users won't be able to edit from within Excalidraw.
|
|
|
|
|
|
-### `UIOptions`
|
|
|
+#### `UIOptions`
|
|
|
|
|
|
This prop can be used to customise UI of Excalidraw. Currently we support customising only [`canvasActions`](#canvasActions). It accepts the below parameters
|
|
|
|
|
|
@@ -536,7 +542,7 @@ This prop can be used to customise UI of Excalidraw. Currently we support custom
|
|
|
{ canvasActions: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L208"> CanvasActions<a/> }
|
|
|
</pre>
|
|
|
|
|
|
-#### canvasActions
|
|
|
+##### canvasActions
|
|
|
|
|
|
| Attribute | Type | Default | Description |
|
|
|
| --- | --- | --- | --- |
|
|
|
@@ -548,6 +554,18 @@ This prop can be used to customise UI of Excalidraw. Currently we support custom
|
|
|
| `saveScene` | boolean | true | Implies whether to show `Save button` |
|
|
|
| `theme` | boolean | true | Implies whether to show `Theme toggle` |
|
|
|
|
|
|
+#### `onPaste`
|
|
|
+
|
|
|
+This callback is triggered if passed when something is pasted into the scene. You can use this callback in case you want to do something additional when the paste event occurs.
|
|
|
+
|
|
|
+<pre>
|
|
|
+(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L17">ClipboardData</a>, event: ClipboardEvent | null) => boolean
|
|
|
+</pre>
|
|
|
+
|
|
|
+This callback must return a `boolean` value or a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) which resolves to a boolean value.
|
|
|
+
|
|
|
+In case you want to prevent the excalidraw paste action you must return `true`, it will stop the native excalidraw clipboard management flow (nothing will be pasted into the scene).
|
|
|
+
|
|
|
### Does it support collaboration ?
|
|
|
|
|
|
No Excalidraw package doesn't come with collaboration, since this would have different implementations on the consumer so we expose the API's which you can use to communicate with Excalidraw as mentioned above. If you are interested in understanding how Excalidraw does it you can check it [here](https://github.com/excalidraw/excalidraw/blob/master/src/excalidraw-app/index.tsx).
|
|
|
@@ -574,6 +592,30 @@ useEffect(() => {
|
|
|
|
|
|
Try out the [Demo](#Demo) to see it in action.
|
|
|
|
|
|
+### detectScroll
|
|
|
+
|
|
|
+Indicates whether Excalidraw should listen for `scroll` event on the nearest scrollable container in the DOM tree and recompute the coordinates (e.g. to correctly handle the cursor) when the component's position changes. You can disable this when you either know this doesn't affect your app or you want to take care of it yourself (calling the [`refresh()`](#ref) method).
|
|
|
+
|
|
|
+### handleKeyboardGlobally
|
|
|
+
|
|
|
+Indicates whether to bind keyboard events to `document`. Disabled by default, meaning the keyboard events are bound to the Excalidraw component. This allows for multiple Excalidraw components to live on the same page, and ensures that Excalidraw keyboard handling doesn't collide with your app's (or the browser) when the component isn't focused.
|
|
|
+
|
|
|
+Enable this if you want Excalidraw to handle keyboard even if the component isn't focused (e.g. a user is interacting with the navbar, sidebar, or similar).
|
|
|
+
|
|
|
+### onLibraryChange
|
|
|
+
|
|
|
+Ths callback if supplied will get triggered when the library is updated and has the below signature.
|
|
|
+
|
|
|
+<pre>
|
|
|
+(items: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200">LibraryItems</a>) => void | Promise<any>
|
|
|
+</pre>
|
|
|
+
|
|
|
+It is invoked with empty items when user clears the library. You can use this callback when you want to do something additional when library is updated for example persisting it to local storage.
|
|
|
+
|
|
|
+### id
|
|
|
+
|
|
|
+The unique id of the excalidraw component. This can be used to identify the excalidraw component, for example importing the library items to the excalidraw component from where it was initiated when you have multiple excalidraw components rendered on the same page as shown in [multiple excalidraw demo](https://codesandbox.io/s/multiple-excalidraw-k1xx5).
|
|
|
+
|
|
|
### Extra API's
|
|
|
|
|
|
#### `getSceneVersion`
|
|
|
@@ -587,21 +629,21 @@ getSceneVersion(elements: <a href="https://github.com/excalidraw/excalidraw/blo
|
|
|
|
|
|
This function returns the current scene version.
|
|
|
|
|
|
-#### `getSyncableElements`
|
|
|
+#### `isInvisiblySmallElement`
|
|
|
|
|
|
**_Signature_**
|
|
|
|
|
|
<pre>
|
|
|
-getSyncableElements(elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>):<a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>
|
|
|
+isInvisiblySmallElement(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a>): boolean
|
|
|
</pre>
|
|
|
|
|
|
**How to use**
|
|
|
|
|
|
```js
|
|
|
-import { getSyncableElements } from "@excalidraw/excalidraw";
|
|
|
+import { isInvisiblySmallElement } from "@excalidraw/excalidraw";
|
|
|
```
|
|
|
|
|
|
-Returns all elements including deleted ones, excluding elements which are are invisibly small (e.g. width & height are zero). Useful when you want to sync elements during collaboration.
|
|
|
+Returns `true` if element is invisibly small (e.g. width & height are zero).
|
|
|
|
|
|
#### `getElementMap`
|
|
|
|
Aakansha Doshi