From 501b2b060c0a096b2dad9b25f55d3a5b5404c44f Mon Sep 17 00:00:00 2001 From: Jinny You Date: Mon, 18 Dec 2023 18:32:35 +0900 Subject: [PATCH] web: Add a readme --- web/README.md | 295 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 web/README.md diff --git a/web/README.md b/web/README.md new file mode 100644 index 00000000..1b18bd85 --- /dev/null +++ b/web/README.md @@ -0,0 +1,295 @@ +# @thorvg/lottie-player + +A Lottie Player which uses [ThorVG](https://github.com/thorvg/thorvg) as a renderer, provides a web component for easily embedding and playing [Lottie](https://airbnb.io/lottie) animations. + +# Installation + +- Import from CDN +```html + +``` + +- Install from NPM +```sh +npm install @thorvg/lottie-player +``` + +# Usage +### With HTML (Basic Usage) + +Once you import from CDN, you can access `` + +```html + + +``` + +### With NPM (JS/TS) + +Import the library and please follow Basic Usage, you can use library on any NPM-based project such as React, Vue and Svelte. + +```ts +import '@thorvg/lottie-player'; +``` + +### With ReactJS + TypeScript + +Add `declarations.d.ts` on the root of project and make sure following declaration. + +```js +declare namespace JSX { + interface IntrinsicElements { + "lottie-player": any; + } +} +``` + +Then you will be able to use this as same as above +```js +import '@thorvg/lottie-player'; + + + +``` + +### With SSR Framework +We should be careful when using on SSR frameworks such as NextJS, NuxtJS and Svelte, as it means the library must to be rendered on browser/client side. + +- NextJS +```ts +import { useEffect } from "react"; + +export default function Home() { + // ... + + useEffect(() => { + import("@thorvg/lottie-player"); + }); + + // ... +} +``` + +- NuxtJS +```html + + + +``` + +- Svelte +```html + +``` + +# API +## Properties + +| Property | Description | Type | Default Value | Required | +| --- | --- | --- | --- | --- | +| src | A graphic resource to play. It could be an internal/external URL or JSON string for Lottie. | string | undefined | Y | +| speed | Animation speed (for Lottie) | number | 1 | N | +| autoplay | When set to true, automatically plays the animation on loading it (for Lottie) | boolean | false | N | +| count | Number of times to loop the animation | number | undefined | N | +| loop | When set to true, loops the animation. The count property defines the number of times to loop the animation. Setting the count property to 0 and setting the loop to true, loops the animation indefinitely. | boolean | false | N | +| direction | Direction of the animation. Set to 1 to play the animation forward or set to -1 to play it backward. | number (1 or -1) | 1 | N | +| mode | Play mode. Setting the mode to PlayMode.Bounce plays the animation in an indefinite cycle, forwards and then backwards. | PlayMode | PlayMode.Normal | N | +| intermission | Duration (in milliseconds) to pause before playing each cycle in a looped animation. Set this parameter to 0 (no pause) or any positive number. | number | 1 | N | + +## Events + +You can adapt the event with the following code example + +```jsx +const player = document.querySelector('lottie-player'); + +player.addEventListener('load', () => { + // TODO: implements +}); +``` + +| Name | Description | +| --- | --- | +| load | A graphic resource is loaded | +| error | An animation data can’t be parsed. | +| ready | Animation data is loaded and player is ready | +| play | Animation starts playing | +| pause | Animation is paused | +| stop | Animation is stopped | +| freeze | Animation is paused due to player being invisible | +| loop | An animation loop is completed | +| complete | Animation is complete (all loops completed) | +| frame | A new frame is entered | + + +## Methods + +**Method** : `load(src: string | object)` + +**Purpose** : Load and play Lottie animation + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| src | `string` or `object` | URL, or a JSON string or object representing a Lottie animation to play. + +**Return Type** : `Promise` + +--- + +**Method** : `play()` + +**Purpose** : Play loaded animation + +**Return Type** : `void` + +--- + +**Method** : `pause()` + +**Purpose** : Pause playing animation + +**Return Type** : `void` + +--- + +**Method** : `stop()` + +**Purpose** : Stop current animation + +**Return Type** : `void` + +--- + +**Method** : `seek(frame: number)` + +**Purpose** : Move to a given frame + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| src | `number` | The frame number to move, shouldn't be less than 0 and greater than `totalFrame` + +**Return Type** : `void` + +> [!TIP] +> You can easily check total frame of animation, use `player.totalFrame` + +--- + +**Method** : `destory()` + +**Purpose** : Destroy animation and lottie-player element + +**Return Type** : `void` + +--- + +**Method** : `setLooping(value: boolean)` + +**Purpose** : Enable animation loop + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| value | `boolean` | `true` enables looping, while `false` disables looping. + +**Return Type** : `void` + +--- + +**Method** : `setDirection(value: number)` + +**Purpose** : Set animation direction + + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| value | `number` | Direction values. `1` to play the animation forward, `-1` to play it backward. + +**Return Type** : `void` + +--- + +**Method** : `setSpeed(value: number)` + +**Purpose** : Set speed of animation + + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| value | `number` | Playback speed. The value must be any positive integer. + +**Return Type** : `void` + +--- + +**Method** : `setBgColor(value: string)` + +**Purpose** : Set a backgroud color + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| value | `string` | Color values. Hex(#fff) or string('red') to set background color + +**Return Type** : `void` + +--- + +**Method** : `save(target: ExportableType)` + +**Purpose** : Export current animation to other file type + +**Parameters** +| Name | Type | Description +| --- | --- | --- | +| value | `ExportableType` | File type to export + +**Return Type** : `void` + + +--- + +**Method** : `getVersion()` + +**Purpose** : Return current ThorVG version + +**Return Type** : `LibraryVersion` + +# Examples + +Please check these examples in various environments. + +- [VanillaJS Usage](https://codesandbox.io/p/sandbox/thorvg-lottieplayer-vanillajs-t737qm) +- [React Usage](https://codesandbox.io/p/devbox/thorvg-lottieplayer-react-hkkrq3) +- [VueJS Usage](https://codesandbox.io/p/devbox/thorvg-lottieplayer-vue-758h3l) +- [Svelte Usage](https://codesandbox.io/p/devbox/thorvg-lottieplayer-svelte-xd4zp6)