Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

Ring

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

步骤5： Carousel迁移

→

→

→

→

→

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅最新的发布说明。

只有使用Carousel组件的应用才需要执行这一步。如果您的应用未使用Carousel，请跳转到步骤6：测试更新。

在RN 0.83版本中，Carousel组件从kepler-ui-components程序包迁移到@amazon-devices中的单独程序包。如果使用Carousel，则需要将组件迁移到新程序包中。

5.1 检测Carousel的使用情况

grep -rn "import.*Carousel.*from.*kepler-ui-components" src/ --include="*.tsx" --include="*.ts" --include="*.jsx" --include="*.js"

如果没有结果，则继续执行步骤6：测试更新。

5.2 更新依赖项

{
  "dependencies": {
    "@amazon-devices/vega-carousel": "~1.0.0"
  }
}

如果Carousel是从kepler-ui-components中唯一导入的组件，则替换整个依赖项。
如果还导入了其他组件，则保留kepler-ui-components，并添加vega-carousel。

5.3 更新导入声明

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

// ✅ 之后
import { Carousel, CarouselRenderInfo } from '@amazon-devices/vega-carousel';

5.4 迁移数据访问模式

Carousel V2将简单的数据数组属性替换为dataAdapter模式，以提升性能。

//❌ 之前 (V1) — 简单的数据数组
<Carousel
  data={items}
  keyProvider={(item, index) => `item-${item.id}`}
  renderItem={({ item, index }) => <ItemCard item={item} />}
/> 

//✅ 之后 (V2) — dataAdapter模式
const getItem = useCallback((index: number) => {
  if (index >= 0 && index < items.length) {
    return items[index];
  }
  return undefined;
}, [items]);

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

const getItemKey = useCallback((info: CarouselRenderInfo) => {
  return `item-${info.item.id}`;
}, []);

const notifyDataError = useCallback((error: CarouselDataError) => {
  return false;
}, []);

<Carousel
  dataAdapter={{
    getItem,
    getItemCount,
    getItemKey,
    notifyDataError,
  }}
  renderItem={({ item, index }) => <ItemCard item={item} />}
/> 

警告： 将回调逻辑中引用的所有变量包含在依赖项数组中，以免引入过时闭包。

5.5 迁移属性

请按下表将属性名称更新为V2属性名称。

V1属性	V2属性	说明
`data`	`dataAdapter`	请参阅步骤5.4
`keyProvider`	`dataAdapter.getItemKey`	目前使用`CarouselRenderInfo`替代`(item, index)`
`rowId`（数字）	`uniqueId`（字符串）	将数字转换为字符串
`maxToRenderPerBatch`	`renderedItemsCount`	功能相同，名称更新
`hasTVPreferredFocus`	`hasPreferredFocus`	现已支持所有设备
`trapFocusOnAxis`	`trapSelectionOnOrientation`	功能相同，名称更新
`itemPadding`	`itemStyle.itemPadding`	已移入`itemStyle`对象
`itemSelectionExpansion`	`itemStyle.selectedItemScaleFactor`	单一统一比例系数。V1使用单独的`widthScale`和`heightScale`值，而V2使用统一的比例系数。如果V1实现中的宽度/高度比例不同，请以`heightScale`为起点，并通过视觉测试验证结果。
`itemScrollDelay`	`animationDuration.itemScrollDuration`	已移入`animationDuration`对象
`focusIndicatorType`	`selectionStrategy`	值映射：`fixed`→`anchored`、`natural`→`natural`、`pinned`→`pinned`
`pinnedFocusOffset`	`pinnedSelectedItemOffset`	同时接受`"start"`、`"center"`、`"end"`
`selectionBorderStrategy`	`selectionBorder.borderStrategy`	已移入`selectionBorder`对象

移除这些已弃用的V1属性（无V2等效属性）

itemDimensions
getItemForIndex
firstItemOffset
selectionBorder.enabled

5.6 迁移事件处理程序

如果您已使用onFocus或onFocusUpdate来追踪所选的轮播项，请迁移至onSelectionChanged。

// ❌ 之前 (V1) — 使用onFocus追踪所选项目
const [selectedIndex, setSelectedIndex] = useState(0);

<Carousel
  onFocus={(index) => setSelectedIndex(index)}
/> 

// ✅ 之后 (V2) — 使用onSelectionChanged
const onSelectionChanged = useCallback((event: CarouselSelectionChangeEvent) => {
  const item = items[event.index];
  // 点击此处查看您的逻辑
}, [items]);

<Carousel
  onSelectionChanged={onSelectionChanged}
/> 

5.7 完整迁移示例

// ✅ 完成V2 Carousel实现
import React, { useCallback } from 'react';
import { Carousel, CarouselRenderInfo, CarouselSelectionChangeEvent } from '@amazon-devices/vega-carousel';

interface MovieItem {
  id: string;
  title: string;
  thumbnail: string;
}

function MovieCarousel({ movies }: { movies: MovieItem[] }) {
  const getItem = useCallback((index: number) => {
    return index >= 0 && index < movies.length ? movies[index] : undefined;
  }, [movies]);

  const getItemCount = useCallback(() => movies.length, [movies]);

  const getItemKey = useCallback((info: CarouselRenderInfo) => {
    return `movie-${info.item.id}`;
  }, []);

  const notifyDataError = useCallback(() => false, []);

  const onSelectionChanged = useCallback((event: CarouselSelectionChangeEvent) => {
    console.log('Selected movie:', movies[event.index]?.title);
  }, [movies]);

  return (
    <Carousel
      dataAdapter={{ getItem, getItemCount, getItemKey, notifyDataError }}
      renderItem={({ item }) => <MovieCard movie={item} />}
      uniqueId="movie-carousel"
      renderedItemsCount={7}
      hasPreferredFocus={true}
      selectionStrategy="anchored"
      onSelectionChanged={onSelectionChanged}
      itemStyle={{
        itemPadding: 16,
        selectedItemScaleFactor: 1.1,
      }}
      animationDuration={{
        itemScrollDuration: 0.3,
      }}
    /> 
  );
}

有关完整的属性映射参考，请参阅Vega Carousel文档。

Last updated: 2026年7月9日