Console

Settings

Sign out

Notifications

Alexa

Amazonアプリストア

AWS

ドキュメント

Support

My Cases

Console

Vega開発者向けドキュメント

ホーム

開発

設計と開発

公開

リファレンス

サポート

Carousel

オープンベータ版ドキュメント：本テクニカルドキュメントは、リリース前のオープンベータ版の一部としてAmazonから提供されるものです。ここで説明されている機能は、Amazonがフィードバックを受け取り、機能の開発を繰り返す過程で変更される可能性があります。最新の機能の情報については、リリースノートを参照してください。

Carouselは、VegaアプリのUI画面に、単一行のコンテンツメタデータのタイルを実装するために使用されます。Carouselは通常、ホーム画面のグリッドで、関連商品や関連コンテンツなどを表示する行として使用されます。

注： Carouselバージョン1.0.6を使用している場合は、バージョン2.0.0をサポートするように実装を更新する必要があります。詳細については、最新バージョンへの移行を参照してください。

使用方法

このバージョンのCarouselは@amazon-devices/kepler-ui-components ^2.0.0に含まれています。package.jsonを調べて、バージョンが次のように設定されていることを確認してください。

クリップボードにコピーしました。

"dependencies": {
    // ...
    "@amazon-devices/kepler-ui-components": "^2.0.0"
}

インポート

クリップボードにコピーしました。

import { Carousel } from '@amazon-devices/kepler-ui-components';

例

水平カルーセル

クリップボードにコピーしました。

import React, {memo} from 'react';
import {Image, Pressable, View} from 'react-native';
import {
  Carousel,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/kepler-ui-components';
import {useState} from 'react';

import {ItemType, ScrollableProps} from '../../Types';
import {CAROUSEL_STYLE} from './Style';

export const HorizontalScrollable = ({data}: ScrollableProps) => {
  function ItemView({item}: CarouselRenderInfo<ItemType>) {
    const [focus, setFocus] = useState<boolean>(false);
    const onFocusHandler = () => {
      setFocus(true);
    };
    const onBlurHandler = () => {
      setFocus(false);
    };

    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemContainer,
          focus && CAROUSEL_STYLE.itemFocusContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image style={CAROUSEL_STYLE.imageContainer} source={{uri: item.url}} />
      </Pressable>
    );
  }

  const renderItemHandler = ({item, index}: CarouselRenderInfo<ItemType>) => {
    return <ItemView index={index} item={item} />;
  };

  const itemInfo: ItemInfo[] = [
    {
      view: ItemView,
      dimension: {
        width: 250,
        height: 420,
      },
    },
  ];

  const getItemForIndexHandler = (index: number) => ItemView;

  const keyProviderHandler = (item: ItemType, index: number) =>
    `${index}-${item.url}`;

  return (
    <View style={CAROUSEL_STYLE.container}>
      <Carousel
        data={data}
        orientation={'horizontal'}
        containerStyle={CAROUSEL_STYLE.horizontalCarouselContainerStyle}
        itemDimensions={itemInfo}
        itemPadding={20}
        renderItem={renderItemHandler}
        getItemForIndex={getItemForIndexHandler}
        keyProvider={keyProviderHandler}
        hasTVPreferredFocus
        hideItemsBeforeSelection={false}
        itemSelectionExpansion={{
          widthScale: 1.2,
          heightScale: 1.2,
        }}
        numOffsetItems={2}
        focusIndicatorType={'fixed'}
        maxToRenderPerBatch={10}
        firstItemOffset={100}
        dataStartIndex={0}
        initialStartIndex={0}
        shiftItemsOnSelection={true}
        trapFocusOnAxis={false}
        selectionBorder={{
          enabled: true,
          borderColor: '#FFFFFF',
          borderWidth: 2,
          borderRadius: 0,
          borderStrokeRadius: 0
        }}
      />
    </View>
  );
};

export const HorizontalMemoScrollable = memo(HorizontalScrollable);

垂直カルーセル

クリップボードにコピーしました。

import {Image, Pressable, View} from 'react-native';
import {
  Carousel,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/kepler-ui-components';
import {memo, useState} from 'react';
import React from 'react';
import {ItemType, ScrollableProps} from '../../Types';
import {CAROUSEL_STYLE} from './Style';

export const VerticalScrollable = ({data}: ScrollableProps) => {
  function ItemView({item}: CarouselRenderInfo<ItemType>) {
    const [focus, setFocus] = useState<boolean>(false);
    const onFocusHandler = () => {
      setFocus(true);
    };
    const onBlurHandler = () => {
      setFocus(false);
    };

    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemContainer,
          focus && CAROUSEL_STYLE.itemFocusContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image style={CAROUSEL_STYLE.imageContainer} source={{uri: item.url}} />
      </Pressable>
    );
  }

  const renderItemHandler = ({item, index}: CarouselRenderInfo<ItemType>) => {
    return <ItemView index={index} item={item} />;
  };

  const itemInfo: ItemInfo[] = [
    {
      view: ItemView,
      dimension: {
        width: 250,
        height: 420,
      },
    },
  ];
  
   const getItemForIndexHandler = (index: number) => ItemView;

  const keyProviderHandler = (item: ItemType, index: number) =>
    `${index}-${item.url}`;

  return (
    <View style={[CAROUSEL_STYLE.container]}>
      <Carousel
        containerStyle={CAROUSEL_STYLE.verticalCarouselContainerStyle}
        data={data}
        orientation={'vertical'}
        itemDimensions={itemInfo}
        itemPadding={10}
        renderItem={renderItemHandler}
        getItemForIndex={getItemForIndexHandler}
        keyProvider={keyProviderHandler}
        hasTVPreferredFocus
        hideItemsBeforeSelection={false}
        itemSelectionExpansion={{
          widthScale: 1.2,
          heightScale: 1.2,
        }}
        focusIndicatorType="fixed"
        numOffsetItems={2}
        maxToRenderPerBatch={11}
        itemScrollDelay={0.2}
      />
    </View>
  );
};

export const VerticalMemoScrollable = memo(VerticalScrollable);

異種カルーセル

クリップボードにコピーしました。

import {Image, Pressable} from 'react-native';
import {
  Carousel,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/kepler-ui-components';
import {useCallback, useState} from 'react';
import React from 'react';
import {ItemType, ScrollableProps} from '../../Types';
import {CAROUSEL_STYLE} from './Style';

export const HeterogeneousItemViewScrollable = ({data}: ScrollableProps) => {

  function ItemViewType1({item}: CarouselRenderInfo<ItemType>) {
    const [focus, setFocus] = useState<boolean>(false);

    const onFocusHandler = useCallback(() => setFocus(true), []);
    const onBlurHandler = useCallback(() => setFocus(false), []);

    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemContainerType1,
          focus && CAROUSEL_STYLE.itemFocusContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image style={CAROUSEL_STYLE.imageContainer} source={{uri: item.url}} />
      </Pressable>
    );
  }

  function ItemViewType2({item}: CarouselRenderInfo<ItemType>) {
    const [focus, setFocus] = useState<boolean>(false);

    const onFocusHandler = useCallback(() => setFocus(true), []);
    const onBlurHandler = useCallback(() => setFocus(false), []);
    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemContainerType2,
          focus && CAROUSEL_STYLE.itemFocusContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image
          style={CAROUSEL_STYLE.imageContainer}
          resizeMode="cover"
          source={{uri: item.url}}
        />
      </Pressable>
    );
  }

  const renderItemHandler = ({item, index}: CarouselRenderInfo<ItemType>) => {
    return index % 2 === 0 ? (
      <ItemViewType1 index={index} item={item} />
    ) : (
      <ItemViewType2 index={index} item={item} />
    );
  };

  const itemInfo: ItemInfo[] = [
    {
      view: ItemViewType1,
      dimension: {
        width: CAROUSEL_STYLE.itemContainerType1.width,
        height: CAROUSEL_STYLE.itemContainerType1.height,
      },
    },
    {
      view: ItemViewType2,
      dimension: {
        width: CAROUSEL_STYLE.itemContainerType2.width,
        height: CAROUSEL_STYLE.itemContainerType2.height,
      },
    },
  ];

  const getItemForIndexHandler = (index: number) => {
    return index % 2 === 0 ? ItemViewType1 : ItemViewType2;
  };

  const keyProviderHandler = (item: ItemType, index: number) =>
    `${index}-${item.url}`;

  return (
    <Carousel
      data={data}
      containerStyle={CAROUSEL_STYLE.horizontalCarouselContainerStyle}
      orientation={'horizontal'}
      itemDimensions={itemInfo}
      itemPadding={40}
      renderItem={renderItemHandler}
      getItemForIndex={getItemForIndexHandler}
      keyProvider={keyProviderHandler}
      hasTVPreferredFocus
      hideItemsBeforeSelection={false}
      itemSelectionExpansion={{
        widthScale: 1.1,
        heightScale: 1.1,
      }}
      focusIndicatorType="fixed"
      numOffsetItems={3}
      maxToRenderPerBatch={11}
      firstItemOffset={100}
    />
  );
};

機能

フォーカスインジケーター

フォーカスインジケーターのスタイルは、D-Padの左右キーが押されたときの応答として、アイテムのリスト内でフォーカスインジケーターがどのように動くかを指定するものです。

natural

naturalスタイルでは、フォーカスインジケーターはリストの先頭または末尾に到達するまでスクロール方向に移動します。

fixed

fixedスタイルでは、フォーカスインジケーターは最初のアイテムの位置に固定されます。スクロールすると、フォーカスの位置が変わらないようにアイテムが再配置されます。

ピン固定フォーカススタイル

ピン固定フォーカススタイルは、多数のアイテムがある場合に、スクロール中でもフォーカスされたアイテムを特定の位置に固定します。ユーザーがリストの最初または最後に近づくと、スクロール動作はスムーズに自然な流れに変わります。

オプションのプロパティpinnedFocusOffsetを使用すると、ユーザーは選択したアイテムのピン位置を定義できます。FocusIndicatorTypeにはフォーカススタイルPINNEDが含まれます。

pinnedFocusOffsetの範囲は0%から100%です。これはビューポートのサイズの割合です。高さは垂直カルーセルに使用され、幅は水平カルーセルに使用されます。選択したアイテムを固定する位置を、ビューポートの先頭（水平モードの場合、ただし右から左に書かれる言語を除く）または上端（垂直モードの場合）を基準にして定義します。

プロパティ	型	デフォルト	必須	詳細
focusIndicatorType	focusIndicatorType = `fixed \| natural \| pinned`	`fixed`	×	DPadの左右キーが押されたときの応答として、アイテムのリスト内でフォーカスインジケーターがどのように動くかを指定します。 fixed - フォーカスはアイテムの左端の位置に固定されます。 natural - フォーカスはスクロールの方向に移動します。 pinned - フォーカスはリストの最初と最後でスクロールの自然な動作を模倣します。ユーザーがアイテムをスクロールすると、フォーカスされたアイテムは、`pinnedFocusOffset`によって決定されるスクロール軸に沿った特定の位置に固定されます。
pinnedFocusOffset	`Percentage \| undefined`	`undefined`	×	`pinnedFocusOffset`の値は、選択または強調表示されたアイテムのフォーカスが固定されるカルーセルの前端からの相対位置（パーセンテージ）を決定します。この値は、「50%」などの文字列の`Percentage`タイプです。注： `focusIndicatorType`が`pinned`に設定され、`pinnedFocusOffset`が定義されていない場合、カルーセルはデフォルトで`focusIndicatorType`が「natural」の動作になります。

注： pinnedFocusOffsetの現在の実装では、0%と100%の値を正しく処理できません。0%にはfocusIndicatorTypeの「fixed」を、100%には「natural」を使用します。

デモビデオ

次のビデオでは、水平スクロールと垂直スクロールでのピン固定フォーカススタイルを示しています。

水平スクロール

垂直スクロール

リサイクル

リサイクル手法では、ユーザーのスクロールに応じて新しいデータを表示するときに、アイテムごとに新しいビューを作成するのではなく、既存のリストアイテムのビューを再利用します。これにより、メモリ使用量が削減され、レンダリングが最適化されます。

リサイクルビューでは、データソース内のすべてのアイテムにアイテムビューが割り当てられるわけではありません。代わりに、画面に収まる数のアイテムビューだけが割り当てられ、ユーザーのスクロールに応じてそれらのアイテムレイアウトが再利用されます。ビューがスクロールされて表示領域から外れると、そのビューはリサイクルプロセスに入ります。以下の図は、この工程を詳しく示したものです。

ビューが表示領域外にスクロールされて表示されなくなると、そのビューはスクラップビューになります。
リサイクラーには、これらのビューを保持するリサイクルビューヒープキャッシュシステムがあります。
1. 新しいアイテムを表示する必要が生じると、リサイクルプールからビューが取得され、再利用されます。このビューは表示前にアダプターで再バインドする必要があるため、ダーティビューと呼ばれます。
2. ダーティビューがリサイクルされます。アダプターは、次に表示されるアイテムのデータを特定し、そのアイテムのビューにデータをコピーします。これらのビューの参照が、リサイクラービューのビューホルダーから取得されます。
3. リサイクルされたビューが、画面に表示されようとしているCarouselのアイテムリストに追加されます。
ユーザーがCarouselをリスト内の次のアイテムまでスクロールすると、リサイクルされたビューが画面に表示されます。同時に、別のビューが表示領域外にスクロールされ、上記の手順に従って再利用されます。

可変スクロール速度

Carouselコンポーネントには、scrollDurationプロパティを通じてスクロール速度を制御する新しい機能が導入されています。FlatListやFlashListなどの既存のコンポーネントとは異なり、この機能によって柔軟性が強化され、エンドユーザーが好みに合わせてスクロールの動作を微調整できるようになっています。

scrollableFocusScaleDurationプロパティは、スクロール可能領域がフォーカスを受け取ったり失ったりしたときに、アイテムの選択状態の変更をアニメーションで表す時間を制御します。スムーズに遷移するように、必要に応じてこの値を調整してください。

itemScrollDelayは、タイルが移動するときなど、タイルが遷移しているときに有効です。フォーカスのみが移動している場合、itemScrollDelayは適用されません。

プロパティ

プロパティ	型	デフォルト	必須	詳細
testID	`string`	`kepler-shoveler`	×	エンドツーエンドのテストでこのスクロール可能領域を特定するために使用される一意の識別子。
Data	`Item[]`	-	○	所定の型のアイテムのプレーンな配列。
itemPadding	`number`	-	○	スクロール方向に隣接するアイテム間のスペース（ピクセル単位）。
orientation	`Orientation = Horizontal \| Vertical`	horizontal	×	スクロール可能なアイテムをレンダリングする方向。
itemDimensions	`ItemInfo[]`	-	○	このスクロール可能領域の子をレンダリングするために使用されるすべてのビューと、それらのサイズが含まれます。
maxToRenderPerBatch	`number`	8	×	スクロール可能領域でリサイクルするときに、一度にレンダリングするアイテムの最大数。
numOffsetItems	`number`	2	×	コンポーネントを末尾までリサイクルする前に、スクロール可能領域の上部／左側に保持するアイテムの数。
firstItemOffset	`number`	0	×	スクロール可能領域の上／左に適用されるパディングの量。
itemSelectionExpansion	`Dimension = { width: number; height: number }`	(0,0)	×	選択されているアイテムに、アイテムのサイズに応じて割り当てるスペース。
shiftItemsOnSelection	`boolean`	true	×	このフラグは、選択の移動に伴ってアイテムの列全体を動かすかどうかを決定します。
focusIndicatorType	`FocusStyle = fixed \| natural \| pinned`	`fixed`	×	DPadの左右キーが押されたときの応答として、アイテムのリスト内でフォーカスインジケーターがどのように動くかを指定します。 fixed - フォーカスはアイテムの左端の位置に固定されます。 natural - フォーカスはスクロールの方向に移動します。 pinned - フォーカスはリストの最初と最後でスクロールの自然な動作を模倣します。ユーザーがアイテムをスクロールすると、フォーカスされたアイテムは、`pinnedFocusOffset`によって決定されるスクロール軸に沿った特定の位置に固定されます。
pinnedFocusOffset	`Percentage \| undefined`	`undefined`	×	`pinnedFocusOffset`の値は、選択または強調表示されたアイテムのフォーカスが固定されるカルーセルの前端からの相対位置（パーセンテージ）を決定します。この値は、「50%」などの文字列の`Percentage`タイプです。注： `focusIndicatorType`が`pinned`に設定され、`pinnedFocusOffset`が定義されていない場合、カルーセルはデフォルトで`focusIndicatorType`が「natural」の動作になります。
hasTVPreferredFocus	`boolean`	false	×	スクロール可能領域が初期フォーカスを受け取ろうとするかどうか。
initialStartIndex	`number`	0	×	スクロール可能領域の初期フォーカスの選択インデックス。
dataStartIndex	`number`	0	×	スクロール可能領域で利用できる先頭データのインデックスを示します。
hideItemsBeforeSelection	`boolean`		×	trueに設定した場合、ピボット／選択アイテムより前にあるアイテムがすべて非表示になります。
itemScrollDelay	`number`	0.2	×	各アイテムのスクロールに費やす時間（秒単位）。
trapFocusOnAxis	`boolean`	false	×	このフラグは、スクロール可能領域にあるフォーカスが、その軸に沿った最も近い位置にあるほかのコンポーネントに進むことを防ぎます。たとえば、水平方向のスクロール可能領域で、ユーザーが先頭のアイテムを選択しているときに左を押すか、末尾のアイテムを選択しているときに右を押したとします。このフラグが設定されていると、スクロール可能領域からフォーカスが外れるのを防ぐことができます。
containerStyle	`StyleProp<ViewStyle>`	undefined	×	スライダーコンテナのビュースタイル。
selectionBorder	`SelectionBorderProps`	{ enabled: false, borderColor: 'white', borderWidth: 8, borderRadius: 8, borderStrokeRadius: 4, borderStrokeColor: 'black', borderStrokeWidth: 3, }	×	このフラグを`true`に設定すると、選択したアイテムを囲むスタイル設定可能な境界線が表示されます。
ref	`React.Ref<ShovelerRef<Key>>`	undefined	×	CarouselコンポーネントのScrollToメソッドとEnableDPadメソッドにアクセスするための参照。

プロパティ	関数シグネチャ	デフォルト	必須	詳細
renderItem	`(info: ShovlerRenderInfo) => React.ReactElement \| null`	-	○	スクロール可能なアイテムをレンダリングするメソッド。
getItemForIndex	`(index: number) => React.FC \| undefined</code>`	-	○	すべての要素に適用される一定のステップサイズ、またはアイテムのインデックスからステップサイズを返すメソッド。
keyProvider	`(data: ItemT, index: number) => keyT`	-	○	オブジェクトからキーを抽出するために使用されるプロバイダー。

Carouselは、ShovelerRef<KeyT>を通じて以下のメソッドをサポートしています。

プロパティ	関数シグネチャ	デフォルト	詳細
scrollTo	`(index: number, animated : boolean) : void;`	-	Carouselで、指定されたインデックスのアイテムにスクロールするメソッドです。
enableDpad	`(enable: boolean) : void;`	-	Carouselで、HWキーイベントをサポートします。

type Dimension = {  width: number; height: number }
type ItemInfo<Prop = any> = {
    view: React.FC<Prop>;
    dimension: Dimension
}

カスタマイズ

可変スクロール速度 - Carouselの各アイテム間のスクロール速度は、itemScrollDelayプロパティを使用して変更できます。デフォルトは0.2秒です。
フォーカスインジケーターのスタイル - カーセルでは、次の2種類のフォーカスインジケーターがサポートされます。
- natural - フォーカスインジケーターは、リストの先頭または末尾に到達するまでスクロール方向に移動します。
- fixed - フォーカスインジケーターは、最初のアイテムの位置に固定されます。スクロール時には、フォーカスのあるアイテムの位置が変わらないようにアイテムが再配置されます。
選択時のアイテムの拡大 - Carousel上で選択またはフォーカスされているアイテムは、元のサイズを基準として、指定された倍率で高さと幅を拡大できます。
選択アイテムの前にあるアイテムの表示／非表示 - 固定スクロール中に、選択されているアイテムの前にあるアイテムを表示または非表示にすることができます。選択アイテムの前のアイテムを表示すると、左側にさらにアイテムがあることがユーザーに視覚的に伝わります。
コンテナのスタイル - Carouselビュー全体のスタイルを設定できます。一般的なスタイルとして、背景色、不透明度、幅、高さがあります。
選択境界線 - カルーセルコンポーネントは、フォーカスされたときにUI項目の周囲に境界線を表示できるようになりました。この変更により、ボーダースタイルを設定するための新しいプロパティと、ネイティブボーダーを使用するかカスタムボーダーを提供するかを選択できるブール値が導入されました。選択境界線の一般的な使用例は次のとおりです。
- selctionBorder.enabledをtrueに設定したデフォルトのボーダースタイル。
```
        
  selectionBorder={{
    enabled: true
  }}
        
```
- selectionBorder.enabledをfalseに設定したデフォルトのボーダースタイル。
```
        
  selectionBorder={{
    enabled: false
  }}
        
```
- borderPropsとborderStrokePropsを使用したボーダースタイル。
```
        
 selectionBorder={{
     enabled: true,
     borderColor: 'white',
     borderWidth: 4,
     borderRadius: 4,
     borderStrokeRadius: 0,
     borderStrokeColor: 'transparent',
     borderStrokeWidth: 0
 }}
        
```

トラブルシューティング

getItemForIndexは関数ではない

次の例のようなエラーが発生する場合があります。

TypeError: getItemForIndex is not a function (it is undefined)
This error is located at:
    in ItemRenderer
    in KeplerScrollable
    in KeplerScrollableWithRef
    in Scrollable (created by App)
    in RCTView (created by View)
    in View (created by App)
    ...

このエラーは、VUICバージョン2.0.0でのCarouselの変更が原因で発生します。機能強化に伴い、コンポーネントの入力プロパティと動作を変更する必要がありました。

使用しているパッケージのバージョンを確認してください。アプリのpackage.jsonファイルを開き、"@amazon-devices/kepler-ui-components"の依存関係を探します。

パッケージバージョンが2.0.0以降であれば、最新バージョンのCarouselが使用されています。このエラーを解決するには2つの方法があり、新しいバージョンを使用して実装を更新するか、または以前のバージョンに戻します。

オプション1：実装を更新する

VUICバージョン2.0.0を使用する場合は、Carouselコンポーネントの実装を更新する必要があります。詳細については、最新バージョンへの移行を参照してください。

オプション2：以前のバージョンのCarouselに戻す

以前のバージョンのCarouselを引き続き使用する場合は、package.jsonファイルで"@amazon-devices/kepler-ui-components"のバージョンを^1.0.0に変更します。

注： VUICのバージョンを戻すと、最新リリースの新機能や機能改善は利用できなくなります。

垂直スクロールは設定された高さでのみ機能する

垂直スクロール（特にナチュラルスクロール）の場合、containerStyleを高さの固定値で設定する必要があります。

shiftItemsOnSelectionをfalseに設定すると、意図しない重複動作が発生することがある

shiftItemsOnSelectionをfalseに設定し、高さと幅を正しく設定していない場合、Carouselで重複動作が発生する可能性があります。この問題を解決するには、正しい高さと幅を設定する必要があります。shiftItemsOnSelectionプロップを使用すると、Carouselコンポーネントが選択されて展開しているときに、Carouselコンポーネントに追加のスペースが挿入されます。これをfalseに設定すると、Carouselは展開しません。

ItemDimensionはカードのサイズと同じかそれ以上にする必要がある

itemDimensionをカードのサイズと同じかそれ以上に設定しないと、正しく配置されないことがあります。

Carousel 2.0.0への移行

このページでは、Vega SDKバージョン0.8以前でサポートされるKUICバージョン1.0.6のCarouselコンポーネントについて説明しています。

Carouselバージョン2.0.0に移行すると、パフォーマンスが強化され、リサイクル、可変スクロール速度、フォーカスインジケーターなどの新機能を利用できます。

サマリー

Carouselは、ユーザーが選択できるアイテムの一覧を目立つ形で表示するためのデザイン要素です。動画アプリや音楽アプリのホームページで、利用できるすべての再生可能なコンテンツを表示するためによく使用されます。また、デバイスのシステムUIで、さまざまな機能に注意を引くために使用されることもあります。Carouselコンポーネントを使用すると、そのようなアイテムの一覧を画面上に簡単に作成でき、カスタマイズ性も提供されます。

従来のFlatListコンポーネントと比較して、Carouselではアイテムが自動的にフォーカス可能になります。さらに、現在フォーカスされているアイテムを示す視覚的なインジケーターも表示されます。デフォルトの視覚インジケーターをオーバーライドすることも、カスタム表示を提供することもできます。Carouselは、内部でRecyclerListView（英語のみ）を使用します。RecyclerListViewはガベージコレクションとメモリ使用の効率が高いため、大きいリストでのパフォーマンスがFlatListよりも優れています。

使用方法

Carouselコンポーネントは、React NativeのFlatListと同様の入力を受け取ります。FlatListと同じように、このコンポーネントにはデータの配列と、そのデータを受け取ってCarouselアイテムを生成するレンダリング関数を指定する必要があります。これらのアイテムはCarousel内にレンダリングされ、リモコンでもタッチでもスクロールできます。

Carouselに固有の要件として、Carouselアイテムのサイズを指定する必要があります。すべてのCarouselアイテムには固定サイズのレンダリング領域が割り当てられ、オーバーフローした部分は切り詰められます。

インポート

クリップボードにコピーしました。

import { Carousel } from '@amazon-devices/kepler-ui-components';

例

クリップボードにコピーしました。

const data = [{imageUrl: "...", title: "...."}, ...]
const renderItem = ({ index, item }) =>
    {
        return <VideoTile title={item.title} image={item.imageUrl}>
    }

<Carousel
    data={data}
    renderItem={renderItem}
    itemDimensions={{ height: 280, width: 200 }}
    testID="Carousel"
    accessibilityLabel="Carousel"
/>

プロパティ

プロパティ	型	デフォルト値	必須	説明
`data`	any[]	該当なし	○	Carouselに表示するアイテムのデータ。この配列の各要素は、Carousel内のアイテムに対応します。たとえば、最初のアイテムをレンダリングするために必要なデータはすべて、データ配列の最初の要素に格納されている必要があります。renderItem()は、このデータを使用して各コンポーネントをレンダリングします。
`renderItem`	`({index: number, item: any}) => JSX.Element`	該当なし	○	この関数は、指定されたデータを使用してCarousel内のアイテムをレンダリングします。renderItem()はデータ配列の要素ごとに呼び出され、Carouselのその位置に表示されるコンポーネントを返す必要があります。デフォルトでは、Carouselにレンダリングされる各アイテムはTouchableOpacityコンポーネントでラップされます。これにより、Carouselアイテムがデフォルトでフォーカス可能になります。デフォルトのフォーカススタイルでは、アイテムの周りに白い境界線が表示されます。このデフォルトの動作を無効にするには、focusDisabledプロパティを使用します。
`itemDimensions`	`{ height: number; width: number; }`	該当なし	○	Carousel内の各アイテムには、Carouselによって固定サイズの表示領域が与えられます。アイテムは、割り当てられた領域全体を使用しなくても構いません。たとえば、Carouselアイテムにフォーカスがあるときに、そのアイテムを大きく表示するとします。このようなシナリオでは、拡大時のアイテムのサイズをitemDimensionsに指定します。itemDimensionsで指定された領域を超えるコンテンツは切り詰められます。
`customFocusedStyle`	ViewStyle	undefined	×	Carouselアイテムにフォーカスがあるときの独自のカスタムスタイルを指定できます。このスタイルは、Carouselアイテムを囲むラッパーに適用されます。このプロパティは、デフォルトのフォーカススタイルをオーバーライドします。
`focusDisabled`	ブール型	false	×	Carouselによって提供されるフォーカス効果を無効にします。これは、アイテムにフォーカスがあるときに、（FireTVランチャーのような）複雑な効果を適用する場合に使用します。customFocusedStyleでは複雑なアニメーションは適用できません。このようなシナリオでは、focusDisabledをtrueに設定する必要があります。これにより、Carouselアイテムとして使用するコンポーネントに独自にフォーカス効果を実装できます。
`orientation`	horizontal \| vertical	horizontal	×	Carouselの向きとレイアウトを設定します。 vertical： Carouselの向きは垂直になります。すべてのアイテムが1列に配置され、最初のアイテムが列の一番上に表示されます。 horizontal： Carouselの向きは水平になります。すべてのアイテムが1行に配置され、最初のアイテムが行の一番左に表示されます。
`gap`	数値	0	×	Carouselアイテム間の間隔をピクセル単位で指定します。0に設定しても、Carouselアイテムの周りには隙間が表示されます。この隙間はデフォルトのフォーカススタイルに由来します。アイテムがフォーカスを受け取ったときに不要なレイアウト変更が行われないようにするため、フォーカスのない要素には透明な境界線が追加されます。これをオーバーライドするには、customFocusedStyleを使用してborderWidthを0に設定します。
`itemContainerStyle`	ViewStyle	undefined	×	すべてのCarouselアイテムを含む、Carouselの内部コンテナのスタイルを設定します。
`style`	ViewStyle	undefined	×	Carousel全体のスタイルを設定します。Carouselのサイズと画面上の位置を指定するには、このプロパティを使用します。

カスタマイズ

カスタマイズには、スタイルプロパティ（itemContainerStyle）とgapプロパティを使用できます。また、customFocusedStyleプロパティを使用して、Carouselアイテムにフォーカスがあるときの表示をカスタマイズすることもできます。

例

const data = [{imageUrl: "...", title: "...."}, ...]

const renderItem = ({ index, item }) =>
{
    return <VideoTile title={item.title} image={item.imageUrl}>
}
const customFocusStyle = {
    borderColor: 'yellow',
    borderRadius: 20,
}
<Carousel
    data={data}
    renderItem={renderItem}
    itemDimensions={{ height: 280, width: 200 }}
    orientation={"horizontal"}
    customFocusedStyle={customFocusStyle}
    gap={30}
    testID="Carousel"
    accessibilityLabel="Carousel"
/>

対話操作

モダリティ	利用可能
D-Pad	○
タッチ	○
音声	×

アクセシビリティ

プロパティ	利用可能
`accessible`	○
`accessibilityRole`	×
`accessibilityLabel`	○
`accessibilityValue`	×
`accessibilityActions`	×
`accessibilityState`	×

UIエクスペリエンス

デフォルトでは、Carouselは水平方向に配置され、フォーカスのある要素の周りに白い境界線が表示されます。Carouselのビジュアルは、ユーザーがレンダリング関数で何を使用するかによって大きく変わる可能性があります。以下のデモからわかるように、Carousel内に配置するアイテムやアイテムの形状に制限はありません。アニメーションが必要な場合は、アイテムのデータに直接追加して渡すことができます。

Carousel

使用方法

インポート

例

機能

フォーカスインジケーター

ピン固定フォーカススタイル

デモビデオ

水平スクロール

リサイクル

可変スクロール速度

プロパティ

カスタマイズ

トラブルシューティング

getItemForIndexは関数ではない

垂直スクロールは設定された高さでのみ機能する

shiftItemsOnSelectionをfalseに設定すると、意図しない重複動作が発生することがある

ItemDimensionはカードのサイズと同じかそれ以上にする必要がある

サマリー

使用方法

インポート

例

プロパティ

カスタマイズ

対話操作

アクセシビリティ

UIエクスペリエンス

デモ

最新バージョンへの移行

プロパティの移行

例