Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases

Console

as

開発
設計と開発
公開
リファレンス
サポート

VUIC Carousel

VUIC Carousel

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

使用方法

このバージョンの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スタイルでは、フォーカスインジケーターはリストの先頭または末尾に到達するまでスクロール方向に移動します。

クラウドストリーミングのnaturalスタイルのフォーカスインジケーターを示す図

fixed

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

クラウドストリーミングのfixedスタイルのフォーカスインジケーターを示す図

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

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

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

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

プロパティ 型 デフォルト 詳細
focusIndicatorType focusIndicatorType = fixed | natural | pinned fixed D-padの左方向キーと右方向キーが押されたときに、アイテムのリスト内でフォーカスインジケーターがどのように動くかを指定します。

fixed - フォーカスはアイテムの左端の位置に固定されます。

natural - フォーカスはスクロールの方向に移動します。

pinned - フォーカスはリストの最初と最後でスクロールの自然な動作を模倣します。ユーザーがアイテムをスクロールすると、フォーカスのあるアイテムはスクロール軸に沿った位置に固定されます。この位置はpinnedFocusOffsetによって決定されます。
pinnedFocusOffset Percentage | undefined undefined 選択アイテムのフォーカスが固定される位置を、カルーセルの先頭の端からの相対位置としてパーセンテージで決定します。この値は、「50%」などの文字列のPercentageタイプです。

注： focusIndicatorTypeがpinnedに設定され、pinnedFocusOffsetが定義されていない場合、カルーセルはデフォルトでfocusIndicatorTypeが「natural」の動作になります。

リサイクル

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

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

クラウドストリーミングのアーキテクチャを示すスクリーンショット
  1. ビューが表示領域外にスクロールされて表示されなくなると、そのビューはスクラップビューになります。

  2. リサイクラーには、これらのビューを保持するリサイクルビューヒープキャッシュシステムがあります。

    a. 新しいアイテムを表示する必要が生じると、リサイクルプールからビューが取得され、再利用されます。このビューは表示前にアダプターで再バインドする必要があるため、ダーティビューと呼ばれます。

    b. ダーティビューがリサイクルされます。アダプターは、次に表示されるアイテムのデータを特定し、そのアイテムのビューにデータをコピーします。これらのビューの参照が、リサイクラービューのビューホルダーから取得されます。

    c. リサイクルされたビューが、画面に表示されようとしているCarouselのアイテムリストに追加されます。

  3. ユーザーがCarouselをリスト内の次のアイテムまでスクロールすると、リサイクルされたビューが画面に表示されます。同時に、別のビューが表示領域外にスクロールされ、上記の手順に従って再利用されます。

可変スクロール速度

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

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

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

プロパティ

プロパティ 型 デフォルト 必須 詳細
testID string kepler-shoveler FALSE エンドツーエンドのテストでこのスクロール可能領域を特定するために使用される一意の識別子。
データ Item[] - ○ 所定の型のアイテムのプレーンな配列。
itemPadding number - ○ スクロール方向に隣接するアイテム間のスペース（ピクセル単位）。
orientation Orientation = Horizontal | Vertical horizontal × スクロール可能なアイテムをレンダリングする方向。
itemDimensions ItemInfo[] - TRUE このスクロール可能領域の子をレンダリングするために使用されるすべてのビューと、それらのサイズが含まれます。
maxToRenderPerBatch number 8 FALSE スクロール可能領域でリサイクルするときに、一度にレンダリングするアイテムの最大数。
numOffsetItems number 2 × コンポーネントを末尾までリサイクルする前に、スクロール可能領域の上部／左側に保持するアイテムの数。
firstItemOffset number 0 × スクロール可能領域の上／左に適用されるパディングの量。
itemSelectionExpansion Dimension = { width: number; height: number } (0,0) × 選択されているアイテムに、アイテムのサイズに応じて割り当てるスペース。
shiftItemsOnSelection boolean true FALSE 選択の移動に伴ってアイテムの列全体を動かすかどうかを決定します。
focusIndicatorType FocusStyle = fixed | natural | pinned fixed FALSE D-padの左方向キーと右方向キーが押されたときに、アイテムのリスト内でフォーカスインジケーターがどのように動くかを指定します。

fixed - フォーカスはアイテムの左端の位置に固定されます。

natural - フォーカスはスクロールの方向に移動します。

pinned - フォーカスはリストの最初と最後でスクロールの自然な動作を模倣します。ユーザーがアイテムをスクロールすると、フォーカスのあるアイテムはスクロール軸に沿った位置に固定されます。この位置はpinnedFocusOffsetによって決定されます。
pinnedFocusOffset Percentage | undefined undefined FALSE 選択アイテムのフォーカスが固定される位置を、カルーセルの先頭の端からの相対位置としてパーセンテージで決定します。この値は、「50%」などの文字列のPercentageタイプです。

注： focusIndicatorTypeがpinnedに設定され、pinnedFocusOffsetが定義されていない場合、カルーセルはデフォルトでfocusIndicatorTypeが「natural」の動作になります。
hasTVPreferredFocus boolean false × スクロール可能領域が初期フォーカスを受け取ろうとするかどうか。
initialStartIndex number 0 FALSE スクロール可能領域の初期フォーカスの選択インデックス。
dataStartIndex number 0 × スクロール可能領域で利用できる先頭データのインデックスを示します。
hideItemsBeforeSelection boolean   FALSE trueに設定した場合、ピボット／選択アイテムより前にあるアイテムがすべて非表示になります。
itemScrollDelay number 0.2 FALSE 各アイテムをスクロールするときに使用される時間（秒単位）。
trapFocusOnAxis boolean false FALSE フォーカスが移動するときに、スクロール軸に沿ってスクロール可能領域の外にある最も近いコンポーネントに進むことを防ぎます。たとえば、水平方向のスクロール可能領域で、ユーザーが先頭のアイテムを選択しているときに左を押すか、末尾のアイテムを選択しているときに右を押したとします。このフラグが設定されていると、スクロール可能領域からフォーカスが外れるのを防ぐことができます。
containerStyle StyleProp<ViewStyle> undefined FALSE スライダーコンテナのビュースタイル。
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 - TRUE スクロール可能なアイテムをレンダリングします。
getItemForIndex (index: number) => React.FC | undefined</code> - ○ すべての要素に適用される一定のステップサイズ、またはアイテムのインデックスからステップサイズを返すメソッド。
keyProvider (data: ItemT, index: number) => keyT - TRUE オブジェクトからキーを抽出します。

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
}

カスタマイズ

可変スクロール速度

カルーセルの各アイテム間のスクロール速度は、itemScrollDelayプロパティを使用して変更できます。デフォルトは0.2秒です。

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

カルーセルは2種類のフォーカスインジケーターをサポートしています。

natural

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

fixed

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

選択時のアイテムの拡大

カルーセル上で選択またはフォーカスされているアイテムは、元のサイズを基準として、指定された倍率で高さと幅を拡大できます。

選択アイテムの前にあるアイテムの表示／非表示

固定スクロール中に、選択されているアイテムの前にあるアイテムを表示または非表示にすることができます。選択アイテムの前のアイテムを表示すると、左側にさらにアイテムがあることがユーザーに視覚的に伝わります。

コンテナのスタイル

カルーセルのビュー全体のスタイルを設定できます。一般的なスタイルとして、背景色、不透明度、幅、高さがあります。

選択境界線

Carouselコンポーネントは、フォーカスされたときにUIアイテムの周囲に境界線を表示できるようになりました。この変更により、境界線スタイルを設定するための新しいプロパティと、ネイティブの境界線を使用するかカスタムの境界線を提供するかを選択できるブール値が導入されました。選択境界線の一般的な使用例は次のとおりです。

selctionBorder.enabledをtrueに設定した場合のデフォルトの境界線スタイル


selectionBorder={{
  enabled: true
}}
選択境界線をtrueに設定した場合

selectionBorder.enabledをfalseに設定した場合のデフォルトの境界線スタイル


selectionBorder={{
  enabled: false
}}
選択境界線を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に変更します。

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

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

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

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

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

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

Carouselの最新バージョンへの移行

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

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

Lunaの概要

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内に配置するアイテムやアイテムの形状に制限はありません。アニメーションが必要な場合は、アイテムのデータに直接追加して渡すことができます。

Last updated: 2026年2月4日

フォローする

サポート対象デバイス

amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved. 無断複写·転載を禁じます。

利用規約

Amazon開発者ブログ

お問い合わせ