lottie-react-native

@amazon-devices/lottie-react-nativeライブラリはLottie React Nativeを拡張して、Vega向けReact Native（RNV）アプリにおけるLottieアニメーションをサポートします。このライブラリをTypeScriptプロジェクトとJavaScript RNVプロジェクトの両方で使用して、Lottieアニメーションを実行できます。このライブラリはRNVアプリにあらかじめインストールされているため、別途インストールする必要はありません。自動リンクライブラリとして機能し、実行時にアプリに接続します。互換性はライブラリとそれに対応するRNVバージョン間でのみ保証されることに注意してください。 Amazonでは、RNVバージョンをアップグレードする際にライブラリのバージョンを更新することを推奨しています。これによって一貫性が維持され、最新の機能や改善点を利用できるようになります。

インストール

パッケージを使用するには、次の手順に従います。

package.jsonファイルにJavaScriptライブラリの依存関係を追加します。該当するReact Nativeバージョンのタブを選択してください。

React Native 0.72
React Native 0.83

"dependencies": {
     ...
     "@amazon-devices/lottie-react-native": "~2.0.0"
}

"dependencies": {
     ...
     "@amazon-devices/lottie-react-native": "~3.0.0"
}

npm installコマンドを使用して、package-lock.jsonファイルを再インストールします。
Lottieアニメーションを<アプリパッケージのルート>/src/js/resources/に追加します。Lottieアニメーションの画像を<アプリパッケージのルート>/assets/image/に追加します。

Vegaでは、Lottieアニメーション（画像アセットではなく）を、<アプリパッケージのルート>/assets/raw/に配置することもできます。

例

Lottieは、次の例のように宣言的に使用できます。

import React from "react";
import LottieView from "@amazon-devices/lottie-react-native";

export default function Animation() {
  return (
    <LottieView source={require("../path/to/animation.json")} autoPlay loop />
  );
}

または、次の例のように命令型APIを使用することもできます。

import React, { useEffect, useRef } from "react";
import LottieView from "@amazon-devices/lottie-react-native";

export default function AnimationWithImperativeApi() {
  const animationRef = useRef<LottieView>(null);

  useEffect(() => {
    animationRef.current?.play();

    // または、特定のstartFrameとendFrameを設定します。
    animationRef.current?.play(30, 120);
  }, []);

  return (
    <LottieView
      ref={animationRef}
      source={require("../path/to/animation.json")}
    />
  );
}

API

RNVでは、lottie-react-native（英語のみ）を使用してLottieアニメーションのサポートを追加しているため、lottie-react-native APIと同じAPIがサポートされます。 @amazon-devices/lottie-react-nativeライブラリでは、iOS、Android、Windowsに固有のプロパティはサポートされません。

コンポーネントAPI

プロパティ	説明	デフォルト
`source`	必須 - アニメーションのソース。`source`を文字列でローカルアセットとして参照することも、`uri`プロパティを持つオブジェクトを使用してリモートで参照することもできます。`require('../path/to/animation.json')`などの実際のアニメーションオブジェクトを使用することもできます。	（なし）
`progress`	0～1の数値、または0～1の`Animated`数値。この数値は、アニメーションの正規化された進行状況を表します。このプロパティを更新すると、アニメーションはその進行状況の値のフレームに更新されます。このプロパティは、リファレンスを通じてコンポーネントを制御する命令型APIを使用している場合はオプションです。	`0`
`speed`	アニメーションの進行速度を表す-1から1までの数値。負の値を送信すると、アニメーションが逆に再生されます。	`1`
`duration`	アニメーションの長さ（ミリ秒）。設定した場合、`speed`よりも優先されます。`duration`を使用するには、アニメーションの実際のJSオブジェクトを`source`として使用します。	`undefined`
`loop`	アニメーションをループさせるかどうかを示すブール値のフラグ。	`true`
`autoPlay`	マウント時にアニメーションを自動的に開始するかどうかを示すブール値のフラグ。`autoplay`は、リファレンスを通じてコンポーネントを制御する命令型APIでのみ使用してください。	`false`
`autoSize`	アニメーションのJSONで定義されている幅に従って、自動的にアニメーションのサイズを調整するかどうかを示すブール値のフラグ。`autoSize`を使用するには、アニメーションの実際のJSオブジェクトを`source`として使用します。	`false`
`resizeMode`	フレームと元の画像サイズが一致しない場合に、アニメーションビューのサイズを変更する方法を決定します。`cover`、`contain`、`center`がサポートされます。	`contain`
`style`	ビューのスタイル属性。境界線のスタイル以外は標準の`View`（英語のみ）と同様です。	（なし）
`imageAssetsFolder`	Vegaでアセットを適切に処理するのに必要とされます。一部のアニメーションは他の画像アセットに依存しています。このフォルダパスを使用して、Lottieアニメーションに必要な画像アセットを格納してください。	（なし）
`onAnimationFinish`	アニメーションが終了したときに呼び出されるコールバック関数。ブール値の`isCancelled`引数を指定して呼び出され、アニメーションが終了したかキャンセルされたかを示します。`loop`をfalseに設定した場合にのみ呼び出されます。	（なし）
`onAnimationLoad`	アニメーションが読み込まれるときに呼び出されるコールバック関数。アニメーションアセットが読み込まれるときに1回だけ呼び出されます。	（なし）
`onAnimationJsonLoad`	サポートは終了しました。`onAnimationLoad`を使用します。	（なし）
`onAnimationPlay`	アニメーションの再生時に呼び出されるコールバック関数。`play()`を呼び出すたびに呼び出されます。	（なし）
`onAnimationPause`	アニメーションが一時停止したときに呼び出されるコールバック関数。`pause()`を呼び出すたびに呼び出されます。	（なし）
`onAnimationResume`	アニメーションが再開したときに呼び出されるコールバック関数。`resume()`を呼び出すたびに呼び出されます。	（なし）

メソッド（命令型API）

例に示されているように、Lottieコンポーネントは、React.useRef（英語のみ）でコンポーネントをキャプチャすることで命令的に制御できます。参照を通じて、アニメーションの動作をより細かく制御できる以下のメソッドへのアクセスが提供されます。アニメーションが同じ状態の場合、これらのメソッドはいずれも呼び出せません。たとえば、アニメーションの再生中はplay()を呼び出すことはできません。アニメーションの再生中に異なるパラメーターでplay()を呼び出すと、ライブラリは最新の呼び出しで渡されたパラメーターを使用します。

メソッド	説明
`play`	プロパティとして指定された速度でアニメーションを最後まで再生します。`play(startFrame, endFrame)`として呼び出すと、アニメーションの一部を再生できます。
`reset`	アニメーションの進行状況を`0`にリセットします。
`pause`	アニメーションを一時停止します。
`resume`	一時停止したアニメーションを再開します。

Vegaでの例外

以下のアクションとAPIはVegaではサポートされていません。

URIを使用してリモートアセットを ‘source’ に渡す
.lottie形式のアセット
ColorFilters
テストフィルター - VegaにはTestFilterIosやTestFilterAndroidに相当するものはありません。

imageAssetsFolderの使用方法

RNVのimageAssetsFolderプロパティを使用するには、次の手順に従います。

画像アセットを[プロジェクトフォルダ]/assets/imageにコピーします。
Lottieサブフォルダを作成します。必要に応じてアニメーションごとにサブフォルダを作成します。
imageAssetsFolderプロパティでは、相対パスを使用してフォルダを参照します。例：imageAssetsFolder={‘lottie/animation_1’}

デフォルトでは、RNVでは[プロジェクトフォルダ]/assets/imageになっています。このフォルダに直接追加された画像については、imageAssetsFolderを更新する必要はありません。たとえば、[プロジェクトフォルダ]/assets/image/images/img_0.pngというパスではimageAssetsFolderを更新する必要はありません。参考としてJSON構造の例を以下に示します。

{
  "assets": [
    {
      "id": "image_0",
      "w": 737,
      "h": 1215,
      "u": "images/",
      "p": "img_0.png"
    }
  ]
}

サポートされているバージョン

NPMパッケージのバージョン	Vega SDKバージョン	Vega OSバージョン	React Nativeバージョン
~2.0.x+6.0.0-rc.1	0.23以前	`OS 1.1 (1401010009820)`以前	0.72
~3.0.x+6.0.0-rc.1	0.24	`OS 1.2 (2101020054720)`	0.72、0.83

Vegaライブラリとサービス

インストール

例

API

コンポーネントAPI

メソッド（命令型API）

Vegaでの例外

imageAssetsFolderの使用方法

サポートされているバージョン

関連トピック

​インストール

​例

​API

​コンポーネントAPI

​メソッド（命令型API）

​Vegaでの例外

​imageAssetsFolderの使用方法

​サポートされているバージョン

​関連トピック

インストール

例

API

コンポーネントAPI

メソッド（命令型API）

Vegaでの例外

imageAssetsFolderの使用方法

サポートされているバージョン

関連トピック