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

この記事では、Vega Carouselに移行する方法を説明します。好みに応じて、AI活用開発に向けたAmazon Devices Builder Toolsとその互換AIエージェントを使用して移行することもできます。

VUIC CarouselからVega Carouselへの移行

以下のセクションでは、Vega UIコンポーネントライブラリに含まれているCarouselから、個別のパッケージとして提供されているVega Carouselに移行する方法について説明します。

プロパティの移行

新しいバージョンのCarouselを使用するには、以下に示すプロパティに変更を加える必要があります。

以前のプロパティ	更新後のプロパティ	詳細
`data`および`dataStartIndex`	-	これらのプロパティは削除されました。代わりに、新しい`dataAdapter`プロパティ内に、同じ機能を提供する4つのプロパティが用意されています。詳細については、Vega Carouselの例を参照してください。
`rowId`	`uniqueId`	`rowId`は行に固有ではないため、名前が変更されました。また、`rowId`は数値でしたが、より柔軟な文字列に変更されました。
`maxToRenderPerBatch`	`renderedItemsCount`	`maxToRenderPerBatch`は、レンダリングされる最大数ではなく、実際にレンダリングされたアイテムの数を表すため、名前が変更されました。
`firstItemOffset`	`navigableScrollAreaMargin`	`firstItemOffset`は、カルーセルのナビゲーション可能なコンテンツ領域における、カルーセルの向きに応じた方向の両端の余白スペースを定義するため、名前が変更されました。
`hasTVPreferredFocus`	`hasPreferredFocus`	`hasTVPreferredFocus`はTV固有の機能ではないため、名前が変更されました。
`trapFocusOnAxis`	`trapSelectionOnOrientation`	`trapFocusOnAxis`は、`orientation`ではなく`selection/selected`を使用するように名前が変更されました。これは`focus/focused`プロパティに合わせるためで、どちらの用語も同じ意味で使用されます。
`itemPadding`	`itemStyle`	`itemPadding`は、`itemStyle`というプロパティ内に入れ子にされました。
`itemSelectionExpansion`	`selectedItemScaleFactor`	`selectedItemScaleFactor`プロパティは`itemStyle`プロパティ内に入れ子になっています。`selectedItemScaleFactor`は、アイテムの選択時に適用される、アイテムサイズに対する倍率を表す数値を受け取ります。
`shiftItemsOnSelection`	`getSelectedItemOffset`関数	`getSelectedItemOffset`は`itemStyle`プロパティ内に入れ子になっています。この関数は、オフセットの幅と高さを倍率で（たとえば、アイテムのサイズに対する比率として）返します。
`focusIndicatorType`	`selectionStrategy`	`anchored`では、`selectionStrategy`に相当する値が`fixed`に変更され、より説明的な名前になりました。
`pinnedFocusOffset`	`pinnedSelectedItemOffset`	`pinnedSelectedItemOffset`に指定できる値が拡張され、`start`、`center`、`end`がサポートされるようになりました。これらの値は、それぞれ`0%`、`50%`、`100%`に相当します。
`selectionBorder`	-	`selectionBorder`プロパティから、入れ子になっていた`enabled`プロパティが削除されました。境界線は、`selectionBorder`プロパティの値が定義されていれば有効になります。`selectionBorder`プロパティには、`borderStrategy`という新しいプロパティも入れ子として追加されています。このプロパティは、選択されたアイテムのコンテンツと境界線の描画方法を指定します。
`getItemForIndex`および`itemDimensions`	-	ユーザーに表示するレイアウトをカルーセルが自動的に決定するようになったため、`getItemForIndex`プロパティと`itemDimensions`プロパティは削除されました。

Vega Carouselとサポートされるプロパティの詳細については、こちらを参照してください。

Vega Carouselパッケージのインポート

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

例

次の例は、Vega Carouselとそのプロパティの使用方法を示しています。

export function ItemView({ item, index }: CarouselRenderInfo<any>): JSX.Element {
    const [state, setState] = useState(false);
    return (
        <Pressable
            onFocus={() => {
                setState(true)
            }}
            onBlur={() => {
                setState(false)
            }}
            style={[styles.card, state && styles.focus]}
        >
            <View style={[{ flexDirection: 'column' }]}>
                <Image style={styles.image} source={{ uri: item.poster_path }} />
            </View>
        </Pressable>
    );
}

export const renderItem =
    useCallback(({ item, index }: CarouselRenderInfo<any>) => {
        return (
            <ItemView index={index} item={item} />
        );
    }, []);

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
   orientation={'horizontal'}
   dataAdapter={{
        getItem,
        getItemCount,
        getItemKey,
        notifyDataError
   }}
   renderItem={renderItem}
   selectionStrategy='anchored'
   testID='Carousel'
   `itemStyle={{
        itemPadding: 0,
        selectedItemScaleFactor: 1.1
   }}`
 />

Amazon Devices Builder Tools MCPサーバーとAIエージェントを使用してVega Carouselに移行する方法

Amazon Devices Builder Tools MCPサーバーは、Vega UIコンポーネントライブラリに含まれているCarouselから、個別のパッケージとして提供されているVega Carouselへの移行を支援することができます。Amazon Devices Builder Tools MCPサーバーのパッケージは@amazon-devices/amazon-devices-buildertools-mcpです。詳細については、AI活用開発に向けたAmazon Devices Builder Toolsのセットアップを参照してください。

前提条件

MCPをサポートするAIエージェント。
- Kiro CLI
- Cursor
- VSCode Copilot
- Claude Code CLI
- Amazon Q IDE
- Amazon Q CLI
- Cline
VUIC Carouselが実装されているVegaアプリプロジェクト。

手順1：Install Amazon Devices Builder Tools MCPサーバーをインストールする

プロジェクトディレクトリで次のコマンドを実行します。

npx @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context

対話プロンプトに従って次の操作を行います。

AIエージェントを選択します（たとえば、Clineの場合は7と入力します）。
エージェントのMCP設定を自動更新するかどうかを選択するプロンプトで、Yと入力します。
コンテキストドキュメントのインストールパスとして、デフォルトのパスを選択します。
インストールされたコンテキストドキュメントを確認し、マージ／更新します。

手順2：MCPのインストールを検証する

AIエージェントのチャットインターフェイスで、エージェントに次のように指示します。

List the tools provided by Amazon Devices Builder Tools for AI

次のメッセージが表示されます。

 - read_document - Read Vega documentation - list_documents - List available documents - analyze_perfetto_traces - Analyze performance traces

手順3：Carouselの移行を実行する（自然言語）

AIエージェントのチャットインターフェイスで、次のように指示します。

Upgrade my MovieCarousel.tsx from Carousel V1 to V2

または、より具体的に次のように指示します。

Help me migrate /Volumes/workplace/vega-video-sample/src/components/MovieCarousel.tsx from Carousel V1 to V2

AIエージェントが自動的に実行する手順の概要

MCPドキュメントからカルーセルの移行ワークフローを読み取ります。
ステップバイステップの移行手順に従います。
手順ごとに開発者に承認を求めます。

AIガイドによる移行プロセスの詳細

AIエージェントにより、次の手順が案内されます。

バックアップの作成：YourCarousel_ORIGINAL.tsx
インポートの更新：@amazon-devices/kepler-ui-components → @amazon-devices/vega-carousel
package.jsonの更新：@amazon-devices/vega-carousel: ~0.1.0の追加
データアクセスの移行：データプロパティ → dataAdapterと関数
すべてのプロパティの移行：VUICL Vegaのプロパティ → Vega Carouselの同等のプロパティ
ロジックの更新：onFocus → onSelectionChanged（該当する場合）
クリーンアップ：使用されないVUIC Carouselコードの削除

手順4：依存関係をインストールする

移行が完了したら、次のコマンドを実行して@amazon-devices/vega-carouselパッケージをダウンロードします。

npm install

手順5：ビルドとテストを実行する

ビルドするには、次のコマンドを使用します。
npm run build
実行するには、次のコマンドを使用します。
npm test

期待される結果

ビルドが成功する。
テストに合格する（npm test -- -uによるスナップショットの更新が必要な場合があります）。
リンティングエラーがない。

例：Clineでの移行セッション

エージェントに次のように指示します。

Upgrade my MovieCarousel.tsx from Carousel V1 to V2

Clineは次の動作で応答します。

MCPからcarousel.mdワークフローを読み取ります。
バックアップファイルを作成します。
変更を1つずつ提案します。
変更を行う前に、毎回承認を求めます。
移行を自動的に完了します。

各手順を承認したら、次のコマンドを実行します。

npm install

npm run build

結果：VUIC Carouselが正常にVega Carouselに移行されます。

よくある問題と解決策

使用されない変数を削除する

原因：VUIC Carouselの変数（viewInfos、getViewForIndex）は不要になりました。 解決策：AIに「Remove unused variables from the migration」と指示します。

インラインスタイルの警告が発生する

原因：itemStyleオブジェクトがインラインで渡されています。 解決策：AIに「Extract itemStyle to constants」と指示します。

スナップショットテストが失敗する

原因：コンポーネント構造が変更されています。解決策：npm test -- -uを実行して、スナップショットを更新します。

移行の検証

移行が完了したら、次の点を確認してください。

インポートが更新されていること。インポートに@amazon-devices/vega-carouselが含まれていることを確認します。
package.jsonが更新されていること。両方のパッケージ（vega-carousel＋ほかのコンポーネント用のkepler-ui-components）が存在することを確認します。
バックアップが作成されていること。*_ORIGINAL.tsxファイルが存在することを確認します。
ビルドが成功すること。npm run buildが正常に完了することを確認します。
テストに合格すること。npm testが成功することを確認します。

移行による主な変更点

VUIC Carouselのプロパティ	Vega Carouselのプロパティ	変更点
`data`	`dataAdapter`	関数を使用：`getItem`、`getItemCount`、`getItemKey`、`notifyDataError`
`keyProvider`	`getItemKey`（`dataAdapter`内）	dataAdapterオブジェクト内にラップ
`maxToRenderPerBatch`	`renderedItemsCount`	名前の変更のみ
`itemPadding`	`itemStyle.itemPadding`	`itemStyle`オブジェクト内に入れ子
`itemSelectionExpansion`	`itemStyle.selectedItemScaleFactor`	入れ子＋名前の変更
`focusIndicatorType`	`selectionStrategy`	名前の変更：fixed→anchored
`pinnedFocusOffset`	`pinnedSelectedItemOffset`	名前の変更＋start/center/endのサポート
`hasTVPreferredFocus`	`hasPreferredFocus`	名前の変更（プラットフォームに依存しない）
`trapFocusOnAxis`	`trapSelectionOnOrientation`	名前の変更
`itemScrollDelay`	`animationDuration.itemScrollDuration`	`animationDuration`内に入れ子
なし	`onSelectionChanged`	新規：選択時の直接のコールバック
なし	`itemStyle.itemPaddingOnSelection`	新規：フォーカス時の動的なスペース
なし	`itemStyle.pressedItemScaleFactor`	新規：押下時のフィードバック
なし	`navigableScrollAreaMargin`	新規：スクロール領域の余白

MCPを使用してサポートされているAIエージェントをセットアップする方法

以下に、サポートされている各AIエージェントをMCPでセットアップする手順へのリンクを示します。

成功基準

Carouselのすべてのファイルが移行される。
ビルドがエラーなしで完了する。
テストに合格する（必要に応じてスナップショットが更新される）。
リンティングエラーが新たに発生しない。
ロールバック用にバックアップファイルが作成される。

サポート

AI活用開発に向けたAmazon Devices Builder Toolsのセットアップ
NPMパッケージ（英語のみ）
MCPプロトコル（英語のみ）

​VUIC CarouselからVega Carouselへの移行

​プロパティの移行

​Vega Carouselパッケージのインポート

​例

​Amazon Devices Builder Tools MCPサーバーとAIエージェントを使用してVega Carouselに移行する方法

​前提条件

​手順1：Install Amazon Devices Builder Tools MCPサーバーをインストールする

​手順2：MCPのインストールを検証する

​手順3：Carouselの移行を実行する（自然言語）

​AIエージェントが自動的に実行する手順の概要

​AIガイドによる移行プロセスの詳細

​手順4：依存関係をインストールする

​手順5：ビルドとテストを実行する

​例：Clineでの移行セッション

​よくある問題と解決策

​使用されない変数を削除する

​インラインスタイルの警告が発生する

​スナップショットテストが失敗する

​移行の検証

​移行による主な変更点

​MCPを使用してサポートされているAIエージェントをセットアップする方法

​成功基準

​サポート