README_JA.md

Fancy Carousel View

English Documents Available(英語ドキュメント)

Fancy Scroll Viewを使用した、UnityのuGUI用のカルーセルビューです。

目次

• 特徴
• デモ
• セットアップ
  • 要件
  • インストール
• 基本的な使い方
  • セルのためのデータを作成する
  • セルを作成する
  • カルーセルビューを作成する
  • カルーセルビューを初期化する
• 応用的な使い方
  • Carousel Viewの各プロパティを理解する
  • プログレスビューを使用する
  • セルの動きをカスタムする
  • スクロールビューと併せて使う
• ライセンス

特徴

• カルーセルビューを数ステップで簡単に作成可能
• 表示に不要なセルが使いまわされるため高パフォーマンス
• 縦/横スクロールに対応
• カルーセルの動き・各パラメータは細かくカスタム可能

デモ

1. リポジトリをクローンする
2. 以下のシーンを開いて再生する
   • https://github.com/Haruma-K/FancyCarouselView/blob/master/Assets/Demo/Scenes/CarouselDemo.unity

セットアップ

要件

Unity 2019.4 以上

インストール

Fancy Carousel Viewは低レイヤー実装としてFancy Scroll Viewを使用しています。
したがってこれら二つをインストールする必要があります。

1. Window > Package ManagerからPackage Managerを開く
2. 「+」ボタン > Add package from git URL
3. 以下を入力してFancy Scroll Viewをインストール
   • https://github.com/setchi/FancyScrollView.git#upm
4. 以下を入力してFancy Carousel Viewをインストール
   • https://github.com/Haruma-K/FancyCarouselView.git?path=/Assets/FancyCarouselView

あるいはPackages/manifest.jsonを開き、dependenciesブロックに以下を追記します。

{
    "dependencies": {
        "jp.setchi.fancyscrollview": "https://github.com/setchi/FancyScrollView.git#upm",
        "com.harumak.fancycarouselview": "https://github.com/Haruma-K/FancyCarouselView.git?path=/Assets/FancyCarouselView"
    }
}

バージョンを指定したい場合には以下のように記述します。

• https://github.com/Haruma-K/FancyCarouselView.git?path=/Assets/FancyCarouselView#1.0.0

基本的な使い方

セルのためのデータを作成する

まずカルーセルの要素であるセルごとのデータを作成します。
以下の例では、セルの背景テクスチャを読み込むためのキーとセルに表示する文字列を定義しています。

public class DemoData
{
    public string SpriteResourceKey { get; }
    public string Text { get; }

    public DemoData(string spriteResourceKey, string text)
    {
        SpriteResourceKey = spriteResourceKey;
        Text = text;
    }
}

セルを作成する

次にセルのビューを作成します。
CarouselCellクラスを継承し、Refreshメソッドにビューの更新処理を記述します。

using FancyCarouselView.Runtime.Scripts;
using UnityEngine;
using UnityEngine.UI;

public class DemoCarouselCell : CarouselCell<DemoData, DemoCarouselCell>
{
    [SerializeField] private Image _image = default;
    [SerializeField] private Text _text = default;

    protected override void Refresh(DemoData data)
    {
        _image.sprite = Resources.Load<Sprite>(data.SpriteResourceKey);
        _text.text = data.Text;
    }
}

これをGameObjectにアタッチし、セルのPrefabを作成しておきます。

カルーセルビューを作成する

次にカルーセルビューを作成します。
上述のデータとセルのクラスをジェネリックの型に指定したCarouselViewクラスを継承したクラスを作成します。

using FancyCarouselView.Runtime.Scripts;

public class DemoCarouselView : CarouselView<DemoData, DemoCarouselCell>
{
}

これをCanvas配下のGameObjectにアタッチします。
RectTransformの大きさでカルーセルビューの大きさを調整し、CarouselViewのCellSizeプロパティでセル一個あたりの大きさを調整します。
また、Cell Prefabプロパティには前節で作成したPrefabをアサインします。

カルーセルビューを初期化する

ここまでできたら、あとはCarouseView.Setupメソッドを用いてデータを渡せばカルーセルが表示されます。

using System.Linq;
using UnityEngine;

namespace Demo.Scripts
{
    public class Demo : MonoBehaviour
    {
        [SerializeField] private DemoCarouselView _carouselView = default;
        [SerializeField, Range(1, 3)] private int _bannerCount = 3;

        private void Start()
        {
            var items = Enumerable.Range(0, _bannerCount)
                .Select(i =>
                {
                    var spriteResourceKey = $"tex_demo_banner_{i:D2}";
                    var text = $"Demo Banner {i:D2}";
                    return new DemoData(spriteResourceKey, text);
                })
                .ToArray();
            _carouselView.Setup(items);
        }
    }
}

応用的な使い方

Carousel Viewの各プロパティを理解する

Carousel ViewのInspectorで設定できる各プロパティの説明は以下の通りです。

プロパティ名			説明
Cell Container			カルーセルビューの領域を表すRectTransform。 この領域から出たセルは非表示になり、再利用の対象になります。
Cell Prefab			セルのPrefab。
Cell Size			セルのサイズ。
Cell Spacing			セル同士の間隔。
Snap Animation Durataion			スナップアニメーションの秒数。
Snap Animation Type			スナップアニメーションのイージングタイプ。
Auto Scrolling			一定間隔で自動するクロールするか。
	Interval		自動スクロールの間隔（秒）。
	Inverse Direction		自動スクロールの方向を反対するかどうか。
Scroll Direction			スクロール方向。
Loop			両端でループするかどうか。
Draggable			ドラッグ可能かどうか。
Progress View			進捗を表すビュー。詳細は後述。
	Clickable		Progress Viewをクリックした時にそのインデックスにジャンプするか。

プログレスビューを使用する

Fancy Carousel Viewはカルーセルの進捗を表すプログレスビューをサポートしています。

シンプルなドット表示のプログレスビューは以下の手順で使用できます。

1. pfb_default_carousel_progress_view.prefabをシーンにインスタンス化
2. Carousel ViewのProgress Viewプロパティに1.をアサイン

上記のPrefabにはCarouselProgressViewを継承したDotCarouselProgressViewがアタッチされています。
CarouselProgressViewやClickableCarouselProgressViewを継承したクラスを独自で実装すれば、任意の挙動をするプログレスビューを作成できます。

また、DotCarouselProgressViewを使用しつつドットの色やサイズだけを変えたい場合には、
DotCarouselProgressViewのInspectorからProgress Element Prefabだけを差し替えることで実現できます。

セルの動きをカスタムする

CarouselCell.OnPositionUpdatedをオーバーライドするとセルの動きを独自実装できます。
以下はセルの動きを独自実装した例です。

protected override void OnPositionUpdated(float position)
{
    base.OnPositionUpdated(position);

    var trans = transform;
    var pos = position * 2.0f - 1.0f;
    var absPos = Mathf.Abs(pos);
    var cellPosZ = Mathf.Lerp(0.0f, 120.0f, absPos);
    trans.localPosition = new Vector3(trans.localPosition.x, trans.localPosition.y, cellPosZ);
    trans.rotation = Quaternion.AngleAxis(pos * -20.0f, Vector3.up);
}

スクロールビューと併せて使う

スクロールビューのコンテンツとしてカルーセルビューを使う場合、
Unityの仕様によりカルーセルビューがスクロールビューのドラッグをブロックします。
すなわち、カルーセルビューをドラッグしてもスクロールビューはスクロールしません。

このような場合にはカルーセルビューのGameObjectにScroll Event Propagatorコンポーネントをアタッチします。
このコンポーネントはドラッグイベントを適切に親のScrollRectに伝播します。
結果として以下のようにスクロールビューとカルーセルビューが適切に動作します。

ライセンス

本ソフトウェアはMITライセンスで公開しています。
ライセンスの範囲内で自由に使っていただいてかまいませんが、 使用の際は以下の著作権表示とライセンス表示が必須となります。

• https://github.com/Haruma-K/FancyCarouselView/blob/master/LICENSE.md

また、本ソフトウェアは以下のソフトウェアがインストールされていることを前提として実装されています（同梱はされていません）。

• FancyScrollView

このソフトウェアのライセンスの詳細については Third Party Notices.md を参照してください。