迁移到最新的Carousel版本

本文向您展示如何迁移到Vega Carousel。如果您愿意，可以使用用于AI驱动式开发的Amazon Devices Builder Tools，并搭配兼容的AI代理进行迁移。

从VUIC Carousel迁移到Vega Carousel

以下部分介绍如何从Vega用户界面组件库中包含的Carousel迁移到作为单独程序包提供的Vega Carousel。

迁移属性

要使用新版本的Carousel，您需要对下面列出的属性进行更改。

以前的属性	更新后的属性	详情
`data`和`dataStartIndex`	-	这些属性已不复存在。取而代之的是新的`dataAdapter`属性中4个提供相同功能的属性。有关更多信息，请查看Vega Carousel示例。
`rowId`	`uniqueId`	之所以重命名`rowId`，是因为它不是特定于行的。`rowId`也是一个字符串而不是一个数字，这增加了灵活性。
`maxToRenderPerBatch`	`renderedItemsCount`	之所以重命名`maxToRenderPerBatch`，是因为它是渲染的项目的实际数量，而不是渲染的最大数量。
`firstItemOffset`	`navigableScrollAreaMargin`	之所以重命名`firstItemOffset`，是因为它定义了轮播可导航内容区域任一侧沿轮播方向的边距空间。
`hasTVPreferredFocus`	`hasPreferredFocus`	之所以重命名`hasTVPreferredFocus`，是因为此功能并非电视专用。
`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; // Don't retry
};

<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用户界面组件库中包含的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：安装Amazon Devices Builder Tools MCP服务器

在您的项目目录中运行以下命令：

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

按照交互式提示进行操作：

选择您的AI代理（例如，Cline为7）。
输入Y以自动更新代理的MCP设置。
选择默认的上下文文档安装路径。
查看并合并/更新已安装的上下文文档。

步骤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更新快照）。
没有lint错误。

示例：Cline迁移会话

要求代理：

Upgrade my MovieCarousel.tsx from Carousel V1 to V2

Cline如下响应。

从MCP读取carousel.md工作流。
创建备份文件。
逐步提出更改建议。
每次修改前都需要获得批准。
自动完成迁移。

批准每个步骤后，运行以下命令。

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.”（将itemStyle提取为常量。）

快照测试失败

原因：组件结构已更改。解决方案：运行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` (in `dataAdapter`)	包装在dataAdapter对象中。
`maxToRenderPerBatch`	`renderedItemsCount`	仅名称更改。
`itemPadding`	`itemStyle.itemPadding`	嵌套在`itemStyle`对象中。
`itemSelectionExpansion`	`itemStyle.selectedItemScaleFactor`	嵌套 + 名称更改。
`focusIndicatorType`	`selectionStrategy`	名称更改：fixed→anchored。
`pinnedFocusOffset`	`pinnedSelectedItemOffset`	名称更改 + 支持开始/中心/结束。
`hasTVPreferredFocus`	`hasPreferredFocus`	名称更改（与平台无关）。
`trapFocusOnAxis`	`trapSelectionOnOrientation`	名称更改。
`itemScrollDelay`	`animationDuration.itemScrollDuration`	Nested in `animationDuration`.
无	`onSelectionChanged`	新：直接选择回调。
无	`itemStyle.itemPaddingOnSelection`	新：聚焦时的动态间距。
无	`itemStyle.pressedItemScaleFactor`	新：按下反馈。
无	`navigableScrollAreaMargin`	新：滚动区域边距。

如何使用MCP设置支持的AI代理

以下支持的AI代理链接到相应的MCP设置说明。

成功标准

所有Carousel文件均已迁移。
构建通过并且没有错误。
测试通过（如果需要则更新快照）。
没有引入新的lint错误。
创建备份文件以进行回滚。

支持

设置用于AI驱动式开发的Amazon Devices Builder Tools
NPM程序包（仅提供英文版）
MCP协议（仅提供英文版）

​从VUIC Carousel迁移到Vega Carousel

​迁移属性

​导入Vega Carousel程序包

​示例

​使用Amazon Devices Builder Tools MCP服务器并搭配AI代理迁移到Vega Carousel

​先决条件

​步骤1：安装Amazon Devices Builder Tools MCP服务器

​步骤2：验证MCP安装

​步骤3：运行Carousel迁移（自然语言）

​AI代理自动执行的步骤概述

​您的AI引导式迁移过程的详细信息

​步骤4：安装依赖项

​步骤5：构建和测试

​示例：Cline迁移会话

​常见问题和解决方案

​移除未使用的变量

​内联样式警告

​快照测试失败

​迁移验证

​关键迁移更改

​如何使用MCP设置支持的AI代理

​成功标准

​支持