as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases
開発
設計と開発
公開
リファレンス
サポート

Vega Carouselについて

Vega Carouselについて

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

  • ビューのリサイクルを修正しました。
  • Carouselがレイアウトを自動的に決定するようになったため、getItemLayoutlayoutIdなどのレイアウトプロパティを削除しました。
  • プロパティのリストを拡張して、Carouselをさらにカスタマイズできるようにしました。
  • Carouselで現在選択されているアイテムが変更されるたびに通知する新しいコールバックプロパティを追加しました。
  • ライブラリが、システムバンドルではなくアプリバンドルになりました(詳細については以下のセクションを参照してください)。

アプリバンドル

このバージョンのCarouselはアプリにバンドルされているため、リリース前にnpmを更新して、最新バージョンを使用していることを確認する必要があります。アプリにバンドルされていることで、新しいCarouselの変更をいつアプリに取り込むかを、より詳細に制御できるようになります。

プロパティのグループ化

itemStyleプロパティとanimationDurationプロパティを他のプロパティとグループ化できるようになりました。

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


 <View style={[CAROUSEL_STYLE.container]}>
      <Carousel
        containerStyle={CAROUSEL_STYLE.verticalCarouselContainerStyle}
        orientation={'vertical'}
        itemStyle=
        animationDuration=
        renderItem={renderItemHandler}
        getItemKey={getItemKeyHandler}
        getItem={getItem}
        getItemCount={getItemCount}
        notifyDataError={notifyDataError}
        hasPreferredFocus
        hideItemsBeforeSelection={false}
        selectionStrategy={'anchored'}
        numOffsetItems={2}
        renderedItemsCount={11}
        itemScrollDelay={0.2}
      />
    </View>
    

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

import { Carousel } from '@amazon-devices/vega-carousel';

この例は、フォーカス状態と画像のレンダリングを含む、基本的な水平カルーセルの実装を示しています。このコンポーネントは、アイテムの取得を管理するためにdataAdapterパターンを使用しており、押下して選択した際のアイテムに対するスケールアニメーションも含まれています。

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


import React, { useCallback } from 'react';
import { Image, Pressable, View } from 'react-native';
import {
  Carousel,
  CarouselRef,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/vega-carousel';
import { Ref, forwardRef, useImperativeHandle, useRef, useState } from 'react';

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

/**
 * HorizontalScrollableはCarouselコンポーネントのラッパーです。これは、
 * Carouselと同じ機能を維持しながら、アイテムを横方向に
 * 表示するように配置します。
 * @param data - データソース
 * @param ref - Imperativeハンドラーメソッドにアクセスするための参照
 * @returns HorizontalScrollable
 */
export const HorizontalScrollable = forwardRef(
  ({ data }: ScrollableProps, ref?: Ref<CarouselRef<any>>) => {
    const scrollableRef = useRef<CarouselRef<any>>(null);

    function ItemView({
      item,
      index,
    }: CarouselRenderInfo<ItemType>): JSX.Element {
      const [focus, setFocus] = useState<boolean>(false);
      const onFocusHandler = () => {
        setFocus(true);
      };
      const onBlurHandler = () => {
        setFocus(false);
      };

      return (
        <Pressable
          style={[
            CAROUSEL_STYLE.itemHorizontalContainer,
          ]}
          onFocus={onFocusHandler}
          onBlur={onBlurHandler}>
          <Image
            style={CAROUSEL_STYLE.imageContainer}
            source=
          />
        </Pressable>
      );
    }

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

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

    useImperativeHandle(ref, () => scrollableRef.current!, []);

    const keyProviderHandler = (info: CarouselRenderInfo) =>
      `${info.index}-${info.item.url}`;

    const getItem = useCallback((index: number) => {
      console.info('getItem called for index:', index);
      if (index >= 0 && index < data.length) {
        return data[index];
      }
      return undefined;
    }, [data]);

    const getItemCount = useCallback(() => {
      const count = data.length;
      console.info('getItemCount called, returning:', count);
      return count;
    }, [data]);

    const notifyDataError = (error: any) => {
      return false; // 再試行しないでください
    };

    const onSelectionChanged = (event: any) => {
      console.info('Selection changed:', event);
    };

    const focusedItemScaleFactor = 1.1;
    const getSelectedItemOffset = (info: any) => {
      return {
        width: focusedItemScaleFactor,
        height: focusedItemScaleFactor
      };
    };

    return (
      <View style={CAROUSEL_STYLE.container}>
        <Carousel
          ref={scrollableRef}
          dataAdapter=
          renderItem={renderItemhandler}
          testID="horizontal-carousel"
          uniqueId="horizontal-carousel-unique"
          orientation={'horizontal'}
          renderedItemsCount={12}
          numOffsetItems={2}
          navigableScrollAreaMargin={100}
          hasPreferredFocus={true}
          initialStartIndex={0}
          hideItemsBeforeSelection={false}
          trapSelectionOnOrientation={false}
          containerStyle={CAROUSEL_STYLE.horizontalCarouselContainerStyle}
          itemStyle=
          animationDuration=
          selectionStrategy="natural"
          pinnedSelectedItemOffset="start"
          onSelectionChanged={onSelectionChanged}
          selectionBorder=
        />
      </View>
    );
  },
);

この例は、カスタム選択枠を使用して縦スクロールするカルーセルを構成する方法を示しています。この実装には、黄色のストローク効果を持つ赤いボーダースタイルが含まれており、ナビゲーション中にアイテムを固定するためにアンカー選択戦略を使用しています。

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


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

/**
 * VerticalScrollableは、縦スクロールを可能にするCarouselコンポーネントの
 * ラッパーです。Carouselと同じ機能を維持しながら、
 * アイテムを縦方向に表示するように配置します。
 * @param data - データソース
 * @returns VerticalScrollable
 */
export const VerticalScrollable = ({ data }: ScrollableProps) => {
  function ItemView({ item, index }: CarouselRenderInfo<ItemType>): JSX.Element {
    const [focus, setFocus] = useState<boolean>(false);
    const onFocusHandler = () => {
      setFocus(true);
    };
    const onBlurHandler = () => {
      setFocus(false);
    };
    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemVerticalContainer,
        ]}
        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 keyProviderHandler = (info: CarouselRenderInfo) =>
    `${info.index}-${info.item.url}`;

  const getItem = useCallback((index: number) => {
    console.info('getItem called for index:', index);
    if (index >= 0 && index < data.length) {
      return data[index];
    }
    return undefined;
  }, [data]);

  const getItemCount = useCallback(() => {
    const count = data.length;
    console.info('getItemCount called, returning:', count);
    return count;
  }, [data]);

  const notifyDataError = (error: any) => {
    return false; // 再試行しないでください
  };

  const onSelectionChanged = (event: any) => {
    console.info('Selection changed:', event);
  };

  const getSelectedItemOffset = (info: any) => {
    // 何もしません
    return undefined;
  };

  return (
    <Carousel
      dataAdapter=
      renderItem={renderItemhandler}
      testID="vertical-carousel"
      uniqueId="vertical-carousel-unique"
      orientation={'vertical'}
      renderedItemsCount={11}
      numOffsetItems={2}
      navigableScrollAreaMargin={0}
      hasPreferredFocus={false}
      initialStartIndex={0}
      hideItemsBeforeSelection={false}
      trapSelectionOnOrientation={false}
      containerStyle={CAROUSEL_STYLE.verticalCarouselContainerStyle}
      itemStyle=
      animationDuration=
      selectionStrategy="anchored"
      pinnedSelectedItemOffset="start"
      onSelectionChanged={onSelectionChanged}
      selectionBorder=
    />
  );
};

この例は、インデックスに応じて2つの異なるレイアウトを交互に切り替えることで、1行内に異なる種類のアイテムを表示できるCarouselの機能を示しています。偶数インデックスのアイテムは幅200ピクセルのレイアウトを使用し、奇数インデックスのアイテムは幅500ピクセルのレイアウトを使用します。これにより、柔軟なコンテンツ表示が可能であることを示しています。

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


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

/**
 * HetrogeneousItemViewScrollableは、1つのスクロール可能な行の中で異なるUIアイテムを
 * 表示できるCarouselの機能を示しています。
 * @param data - データソース
 * @returns HetrogeneousItemViewScrollable
 */
export const HetrogeneousItemViewScrollable = ({ data }: ScrollableProps) => {
  function ItemViewType1({
    item,
    index,
  }: CarouselRenderInfo<ItemType>): JSX.Element {
    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,
    index,
  }: CarouselRenderInfo<ItemType>): JSX.Element {
    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=
        />
      </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 keyProviderHandler = (info: CarouselRenderInfo) =>
    `${info.index}-${info.item.url}`;

  const getItem = useCallback((index: number) => {
    console.info('getItem called for index:', index);
    if (index >= 0 && index < data.length) {
      return data[index];
    }
    return undefined;
  }, [data]);

  const getItemCount = useCallback(() => {
    const count = data.length;
    console.info('getItemCount called, returning:', count);
    return count;
  }, [data]);

  const notifyDataError = (error: any) => {
    return false; // 再試行しないでください
  };

  const onSelectionChanged = (event: any) => {
    console.info('Selection changed:', event);
  };

  const selectedItemScaleFactor = 1.1;
  const getSelectedItemOffset = (info: any) => {
    return {
      width: selectedItemScaleFactor,
      height: selectedItemScaleFactor
    };
  };

  return (
    <View style={CAROUSEL_STYLE.container}>
      <Carousel
        dataAdapter=
        renderItem={renderItemhandler}
        testID="heterogeneous-carousel"
        uniqueId="heterogeneous-carousel-unique"
        orientation={'horizontal'}
        renderedItemsCount={12}
        numOffsetItems={2}
        navigableScrollAreaMargin={100}
        hasPreferredFocus={false}
        initialStartIndex={0}
        hideItemsBeforeSelection={false}
        trapSelectionOnOrientation={false}
        containerStyle={CAROUSEL_STYLE.horizontalCarouselContainerStyle}
        itemStyle=
        animationDuration=
        selectionStrategy="anchored"
        pinnedSelectedItemOffset="start"
        onSelectionChanged={onSelectionChanged}
        selectionBorder=
      />
    </View>
  );
};

Style

このスタイルシートの例では、横スクロールと縦スクロールの両方の向きに対応したCarouselコンポーネントのスタイル定数を定義しています。これには、メインのカルーセル用コンテナスタイル(黒い背景のフルスクリーン)、2種類のサイズ(幅200ピクセルと500ピクセル)のアイテムコンテナ、および固定サイズの向きごとのレイアウト(横向きは高さ420ピクセル、縦向きは幅250ピクセル)が含まれています。

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


import { StyleSheet } from 'react-native';

export const CAROUSEL_STYLE = StyleSheet.create({
  container: {
    backgroundColor: '#000000',
    width: '100%',
    height: '100%',
    justifyContent: 'center',
    alignItems: 'center',
  },
  imageContainer: {
    width: '100%',
    height: '100%',
    resizeMode: 'cover',
  },
  itemHorizontalContainer: {
    width: 250,
    height: '100%',
  },
  itemVerticalContainer: {
    width: '100%',
    height: 420,
  },
  itemContainerType1: {
    height: 420,
    width: 200,
    justifyContent: 'center',
    alignContent: 'center',
  },
  itemContainerType2: {
    height: 420,
    width: 500,
    justifyContent: 'center',
    alignContent: 'center',
  },
  horizontalCarouselContainerStyle: {
    width: '100%',
    height: 420,
  },
  verticalCarouselContainerStyle: {
    height: '100%',
    width: 250,
    justifyContent: 'center',
  },
});

カスタム型

次の例では、カルーセルのアイテムやスクロール可能なラッパーコンポーネントのプロパティを定義するために使用できるカスタム型を示しています。

  • ItemType: 個々のカルーセルアイテムの構造を表すカスタムデータ型。

    プロパティ: url (string)プロパティは、カルーセルアイテムに表示される画像のURLです。url (string)プロパティは、カルーセルに渡されるアイテム、CarouselRenderInfo<ItemType>、およびScrollablePropsを定義します。

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

    export type ItemType = {
      url: string;
    };
    
  • ScrollableProps: スクロール可能なカルーセルラッパーコンポーネントのプロパティインターフェイス。

    プロパティ: data (ItemType[])プロパティは、カルーセルにレンダリングされるアイテムオブジェクトの配列です。data (ItemType[])プロパティは、Horizontal、Vertical、Heterogeneousのスクロール可能なラッパーコンポーネントにおいて、プロパティの型安全性を確保するために使用されます。これにより、これらのコンポーネントに渡されるデータが想定される構造と一致することが保証されます。

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

    export type ScrollableProps = {
      data: ItemType[];
    };
    

機能

データアダプター

Vega Carouselは、さまざまなコールバック関数を含むdataAdapterを提供できるようにすることで、より柔軟なカスタマイズをサポートしています。詳細については、Carouselアイテムデータアダプターのコールバック関数のセクションを参照してください。

Carouselアイテム情報を含むdataという配列があると仮定すると、次の例に示すようにdataAdapter関数を実装できます。

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


const getItem = useCallback((index: number) => {
    if (index >= 0 && index < data.length) {
        return data[index];
    }
    return undefined;
}, [data]);

const getItemCount = useCallback(() => {
    return data.length;
}, [data]);

const getItemKey = (info: CarouselRenderInfo) =>
   `${info.url} ${info.item.index}`

const notifyDataError = (error: any) => {
    return false; // 再試行しないでください
};

<Carousel
  dataAdapter=
  itemStyle=
 />

選択戦略

SelectionStrategyプロパティは、D-padを使用してリスト内を移動したときに、リストがどのようにスクロールし、アイテムを再配置するかを制御します。

Anchored

anchoredスタイルでは、選択したアイテムは最初のアイテムの位置に固定されたままになります。スクロールすると、選択したアイテムがその位置に固定されたままになるように、アイテムが再配置されます。

anchoredスタイル選択
anchoredスタイル選択

Natural

naturalスタイルでは、選択したアイテムはリストの最初または最後に達するまでカルーセルの向きの方向に移動します。

固定スタイル選択
固定スタイル選択

Pinned

pinnedスタイルでは、スクロール中に選択したアイテムを指定の位置にピン留めして、アイテムが大きくなるようにスクロールします。ユーザーがリストの最初または最後に近づくと、スクロール動作はスムーズにnaturalな流れに変わります。

オプションのpinnedSelectedItemOffsetプロパティを使用すると、SelectionStrategypinnedの場合の、選択したアイテムのピンの位置を定義できます。

pinnedSelectedItemOffsetプロパティは、選択したアイテムがCarouselのビューポートのどこに固定(ピン留め)されるかを決定します。この位置は次の2つの方法で指定できます。

  • ビューポートのサイズのパーセンテージ(0~100%):
    • 垂直カルーセルの場合:高さのパーセンテージ
    • 水平カルーセルの場合:幅のパーセンテージ
  • プリセット値:
    • 開始(0%と等しい)
    • 中央(50%と等しい)
    • 終了(100%と等しい)

水平モードでは、右から左に記述する言語を除き、左端から測定されます。

可変スクロール速度

Carouselコンポーネントには、複数のAnimationDurationPropsを通じてスクロール速度を制御する新しい機能が導入されています。FlatlistFlashlistなどの既存のコンポーネントとは異なり、この機能は柔軟性に優れているため、スクロール操作を細かく調整できます。

itemPressedDurationプロパティは、Carouselアイテムを押したときのアニメーション時間を制御します。itemScrollDurationプロパティは、Carouselの各アイテムにスクロールする際に使用されるアニメーション時間を制御します。containerSelectionChangeDurationプロパティは、選択したCarouselコンテナを変更するときのアニメーション時間を制御します。

選択範囲の境界線

Carouselコンポーネントは、選択時にUIアイテムの周囲に境界線を表示することをサポートしています。境界線のスタイルを設定したり、選択したアイテムのコンテンツと境界線の描画方法を選択したりできます。selectionBorderプロパティを定義することで境界線を有効にできます。選択範囲の境界線のデフォルトのプロパティを次の例に示します。

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


{
   borderStrategy: 'outset',
   borderColor: 'white',
   borderWidth: 8,
   borderRadius: 8,
   borderStrokeWidth: 3,
   borderStrokeRadius: 4,
   borderStrokeColor: 'black',
}

Vega Carouselは、borderStrategyプロパティをサポートしています。このプロパティは次の2種類の戦略をサポートしています。

  • outset - アイテムの元の境界の外側に境界線が描画されるため、アイテムのコンテンツサイズは同一のままですが、アイテム全体のサイズは大きくなります。
  • inset - アイテムの境界内にアイテムのコンテンツ上に境界線が描画されるため、アイテムのコンテンツサイズは同一のままですが、アイテムのコンテンツの一部は境界線によってトリミングされます。アイテム全体のサイズは変わりません。

プロパティ

プロパティ デフォルト 必須 詳細
dataAdapter CarouselItemDataAdapter<ItemT, KeyT> - TRUE dataAdapterプロパティには、Carouselがアイテムにアクセスするために呼び出す4つのユーザー定義コールバック関数(getItemgetItemCountgetItemKeynotifyDataError)への参照が含まれています。コールバックの詳細については、Carouselアイテムデータアダプターのコールバック関数を参照してください。
renderItem (info: CarouselRenderInfo) => React.ReactElement null TRUE カルーセルアイテムをレンダリングするユーザー定義メソッドへの参照。
testID string undefined FALSE エンドツーエンドのテストでこのカルーセルを特定するために使用される一意の識別子。
uniqueId string undefined FALSE カルーセルとそのアイテムをいつリサイクルするかを決定するために使用される、このカルーセルの任意かつ一意の識別子。通常、垂直カルーセル内の水平カルーセル(入れ子のカルーセルなど)で使用されます。
orientation horizontal、vertical horizontal FALSE カルーセルでアイテムをレンダリングする方向とレイアウトを指定します。
renderedItemsCount number 8 FALSE パフォーマンスを最適化するためにカルーセルからリサイクルするときに、特定の時間にレンダリングされるアイテムの数。
numOffsetItems number 2 FALSE アイテムコンポーネントを末尾までリサイクルする前に、カルーセルの上部または左側に保持するアイテムの数。
navigableScrollAreaMargin number 0 FALSE カルーセルの向きに沿った方向で、ナビゲーション可能なコンテンツ領域の両側に設けられるマージンのスペース(解像度に依存しないピクセル単位)(例:横向きのカルーセルでは左右、縦向きのカルーセルでは上下)。
hasPreferredFocus boolean FALSE FALSE このコンポーネントがレンダリング時に自動的にフォーカスを受け取るかどうかを決定します。
initialStartIndex number 0 FALSE 選択するカルーセル内の最初のアイテムのインデックスを指定します。
hideItemsBeforeSelection boolean FALSE FALSE 選択したアイテムの前にあるアイテムを非表示にするかどうかを決定します。
trapSelectionOnOrientation boolean FALSE FALSE このフラグにより、方向に沿ってカルーセルの外側にある最も近いコンポーネントに選択が進まないようになります。カルーセルが横向きで、ユーザーが先頭のアイテムにいる状態で後方へ移動しようとした場合、または最後のアイテムにいる状態で前方へ移動しようとした場合、このフラグは選択がカルーセル外へ移動するのを防ぎます。
containerStyle StyleProp<ViewStyle> undefined FALSE カルーセルコンテナに適用されるスタイル。
itemStyle CarouselItemStyleProps - FALSE カルーセルアイテムに適用されるスタイル。
animationDuration AnimationDurationProps - FALSE カルーセルとそのアイテムに関連するさまざまなアニメーションの所要時間。詳細については、アニメーション時間のプロパティのセクションを参照してください。
selectionStrategy anchored, natural, pinned anchored FALSE D-padキーが押されたときに、選択したアイテムがカルーセル内でどのように移動するかを指定します。
anchored - 向きに沿ってどちらの方向にスクロールしても、選択されたアイテムが初期アイテムの位置に固定されたままになるようにします。
natural - 選択されたアイテムが、リストのいずれかの端に到達するまで、カルーセルの向きに沿って移動するようにします。
pinned - リストの先頭および末尾では、選択されたアイテムが自然なスクロール挙動に従うようにし、それ以外のスクロール中はpinnedSelectedItemOffsetプロパティで定義された特定の位置に固定されるようにします。
pinnedSelectedItemOffset パーセンテージ開始、中央、終了 0% FALSE この値は、カルーセルの先端からの相対位置として、選択されたアイテムが固定される位置を決定します。
onSelectionChanged (event: CarouselSelectionChangeEvent) => void undefined FALSE リスト内の現在の選択アイテムが変更されるたびに呼び出される関数(カルーセル自体が選択または非選択になった場合には呼び出されません)。
selectionBorder SelectionBorderProps undefined FALSE 設定すると、選択されたアイテムの周囲にスタイル設定可能な境界線が表示されます。selectionBorderプロパティのすべてのスタイル関連のプロパティは、この機能が有効な場合に、選択されたアイテムを囲む境界線の見た目を定義します。
ref React.Ref<ShovelerRef<Key>> undefined FALSE 設定すると、ScrollToEnableDPadなどのコンポーネントのメソッドへの参照が提供され、参照のcurrentプロパティを使用してそれらを呼び出すことができます。

選択範囲の境界線のプロパティ

プロパティ デフォルト 必須 詳細
borderStrategy inset、outset outset FALSE 選択したアイテムの内容と境界線の描画方法を指定します。
borderWidth number 8 FALSE 選択したアイテムの周囲の境界線の太さを指定します。
borderColor string white FALSE 選択したアイテムの周囲の境界線の色を指定します。
borderRadius number 8 FALSE 角を丸くするためのボーダーの角の半径を決定します。
borderStrokeWidth number 3 FALSE 境界線とアイテムの内容を区切るアウトラインストロークの太さを指定します。
borderStrokeRadius number 4 FALSE 境界線とアイテムの内容を区切るアウトラインストロークの角の半径を定義します。
borderStrokeColor string black FALSE 選択範囲の境界線のアウトラインの色を指定します。

アニメーション時間のプロパティ

プロパティ デフォルト 必須 詳細
itemPressedDuration number 0.15 FALSE アイテムを押したときに使用される時間(秒単位)。
itemScrollDuration number 0.2 FALSE 各アイテムをスクロールするときに使用される時間(秒単位)。
containerSelectionChangeDuration number itemPressedDuration FALSE 選択されたコンテナを変更するときに使用される時間(秒単位)。
プロパティ デフォルト 必須 詳細
itemPadding number 20 FALSE カルーセルの向きに沿った隣接するアイテム間の間隔(ピクセル単位)。
itemPaddingOnSelection number itemPadding FALSE カルーセルが選択されているときの、カルーセルの向きに沿った隣接するアイテム間の間隔(ピクセル単位)。
pressedItemScaleFactor number 0.8 FALSE ユーザーがアイテムを押したときに適用されるスケール倍率。
selectedItemScaleFactor number 1 FALSE アイテムが選択されたときに適用されるスケール倍率。この値が1.0の場合、ユーザーがリストをスクロールしている間、選択されたアイテムにはスケーリングが行われないことを意味します。
getSelectedItemOffset (info: CarouselRenderInfo) => ShiftFactor undefined FALSE アイテムの現在の位置を基準として適用されるオフセット値を取得するための関数。
プロパティ デフォルト 必須 詳細
getItem (index: number) => ItemT undefined TRUE インデックスを受け取り、アイテムのデータオブジェクトを返す関数。返されたオブジェクトは、他のデータアクセス関数を呼び出して特定のアイテムに関する情報を取得するために使用されます。
getItemCount () => number; - TRUE リストのアイテム数を返す関数。
getItemKey (info: CarouselRenderInfo) => KeyT undefined TRUE データとインデックスに基づいて各アイテムに一意のキーを提供する関数。
notifyDataError (error: CarouselDataError) => boolean; - TRUE この関数は、リストでアイテムを使用できない場合にリストコンポーネントによって呼び出されます。

Carouselコンポーネントは、ナビゲーション体験をプログラムで制御するためのメソッドを提供します。以下のメソッドには、現在のコンポーネントのインスタンスをrefプロパティに渡すことでアクセスできます。

プロパティ デフォルト 必須 詳細
scrollTo (index: number, animated : boolean) : void; - FALSE Carouselで、指定されたインデックスのアイテムにスクロールするメソッド。
scrollToKey (key: Key, animated: boolean) : void; - FALSE Carousel内で、特定の一意のキーに対応するアイテムまでスクロールするためのメソッド。
enableDpad (enable: boolean) : void; - FALSE Carouselで、HWキーイベントをサポートします。
notifyDataChange (changes: Array<CarouselDataChange>, animated?: boolean): void - -  

トラブルシューティング

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

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


Last updated: 2026年2月9日