Vega Carousel入门 - Amazon Vega Docs

Carousel用于在Vega应用的用户界面屏幕中实现单行内容元数据图块。Carousel通常出现在主屏幕网格布局、与此类似用户界面或Related Content（相关内容）推荐行中等多种场景中。

Vega Carousel更新

修复了视图循环滚动方面的问题。
移除了像getItemLayout和layoutId这样的布局属性，因为Carousel现在会自动确定布局。
扩展了属性列表，允许对Carousel进行更多自定义设置。
添加了一个新的回调属性，每当Carousel上的当前选定项目发生变化时都会通知您。
这个库目前是随应用打包，而不是随系统打包（有关更多详细信息，请参阅下一节）。

随应用打包

此版本的Carousel是随应用打包的，需要在发布之前执行npm更新操作，以确保您拥有最新版本。随应用打包使您可以更灵活地决定何时在应用中推出新的Carousel更新。

属性组合

itemStyle和animationDuration属性现在可以与其他属性组合在一起。示例：

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

导入Vega Carousel

import { Carousel } from '@amazon-devices/keplerscript-native-ui-components';

示例

水平Carousel

本示例展示了一种基础的水平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';

/**
 * 水平滚动组件是一种包裹Carousel组件的包装器。它
 * 保留了Carousel的全部功能，只是将
 * 项目的展示方向改为水平方向。
 * @param data - 数据源
 * @param ref - 一个引用，用于访问命令式处理程序方法
 * @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={{ 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,
        },
      },
    ];

    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; // Don't retry
    };

    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={{
            getItem,
            getItemCount,
            getItemKey: keyProviderHandler,
            notifyDataError
          }}
          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={{
            itemPadding: 20,
            itemPaddingOnSelection: 20,
            pressedItemScaleFactor: 0.9,
            selectedItemScaleFactor: focusedItemScaleFactor,
            getSelectedItemOffset: getSelectedItemOffset,
          }}
          animationDuration={{
            itemPressedDuration: 0.15,
            itemScrollDuration: 0.2,
            containerSelectionChangeDuration: 0.25
          }}
          selectionStrategy="natural"
          pinnedSelectedItemOffset="start"
          onSelectionChanged={onSelectionChanged}
          selectionBorder={{
            borderStrategy: 'outset',
          }}
        />
      </View>
    );
  },
);

垂直Carousel

本示例演示了如何配置一个垂直滚动的Carousel组件，并为其添加自定义的选中项边框。这一实现采用了红色边框搭配黄色描边效果，并运用锚定选择策略，确保用户在浏览时，选定项目保持锁定状态。

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';

/**
 * 垂直滚动组件是一种包裹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={{
        getItem,
        getItemCount,
        getItemKey: keyProviderHandler,
        notifyDataError
      }}
      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={{
        itemPadding: 10,
        itemPaddingOnSelection: 20,
        pressedItemScaleFactor: 0.8,
        selectedItemScaleFactor: 1,
        getSelectedItemOffset: getSelectedItemOffset,
      }}
      animationDuration={{
        itemPressedDuration: 0.18,
        itemScrollDuration: 0.2,
        containerSelectionChangeDuration: 0.22
      }}
      selectionStrategy="anchored"
      pinnedSelectedItemOffset="start"
      onSelectionChanged={onSelectionChanged}
      selectionBorder={{
        borderStrategy: 'outset',
        borderColor: 'red',
        borderWidth: 5,
        borderRadius: 10,
        borderStrokeRadius: 5,
        borderStrokeColor: 'yellow',
        borderStrokeWidth: 2,
      }}
    />
  );
};

异构Carousel

本示例演示了Carousel如何根据索引在两种不同布局之间交替切换，从而在同一行中渲染不同项目类型的项目。在索引中位于偶数位的项目使用200像素的宽度布局，位于奇数位的项目使用500像素的宽度布局，这展示了Carousel灵活的内容呈现方式。

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展示了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={{ 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 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; // Don't retry
  };

  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={{
          getItem,
          getItemCount,
          getItemKey: keyProviderHandler,
          notifyDataError
        }}
        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={{
          itemPadding: 40,
          itemPaddingOnSelection: 40,
          pressedItemScaleFactor: 0.9,
          selectedItemScaleFactor: selectedItemScaleFactor,
          getSelectedItemOffset: getSelectedItemOffset,
        }}
        animationDuration={{
          itemPressedDuration: 0.15,
          itemScrollDuration: 0.2,
          containerSelectionChangeDuration: 0.25
        }}
        selectionStrategy="anchored"
        pinnedSelectedItemOffset="start"
        onSelectionChanged={onSelectionChanged}
        selectionBorder={{
          borderStrategy: 'inset',
          borderColor: 'white',
          borderWidth: 4,
          borderRadius: 8,
          borderStrokeRadius: 4,
          borderStrokeColor: 'black',
          borderStrokeWidth: 2,
        }}
      />
    </View>
  );
};

样式

这个样式表示例为一个同时支持水平和垂直滚动方向的Carousel组件定义了样式常量。其中包括主Carousel的容器样式（全屏显示，黑色背景）、两种规格变体的项目容器（宽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',
  },
});

自定义类型

以下示例展示了一系列自定义类型，可用于为可滚动包装器组件定义Carousel项目和属性。

ItemType: 一种自定义数据类型，用于表示单个Carousel项目的结构。属性：url (string) 属性是显示在Carousel项目中的图像的URL。url (string) 属性定义传递给Carousel、和ScrollableProps的项目。
export type ItemType = { url: string; };
ScrollableProps: 可滚动Carousel包装器组件的属性接口。属性：data (ItemType[]) 属性是一个项目对象数组，存储要在Carousel中呈现的项目。data (ItemType[]) 属性为水平、垂直和异构可滚动包装器组件中的组件属性提供类型安全保障。这样可以确保传递给这些组件的数据符合预先设定结构要求。
export type ScrollableProps = { data: ItemType[]; };

功能

数据适配器

Vega Carousel允许您提供包含各种回调函数的dataAdapter，从而实现更灵活的自定义功能。有关更多信息，请参阅Carousel项目数据适配器回调函数部分。假设您有一个data数组，存储有Carousel项目信息，则可以实现一组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={{
    getItem,
    getItemCount,
    getItemKey: getItemKeyHandler,
    notifyDataError
  }}
  itemStyle={{itemPadding: 20}}
 />

选择策略

当您使用方向键浏览列表时，SelectionStrategy属性控制列表中项目滚动和重新定位的方式。

Anchored

anchored样式会将选定项目保持锁定在初始项目的位置。滚动时，列表中的项目会重新定位，使选定项目保持锚定在初始位置。屏幕截图显示了数个排成一行的方块，其中一个方块带有黑色边框。图片上标有滚动方向及水平方向的箭头。

Natural

natural样式会将选定项目沿着Carousel的滚动方向移动，直到到达列表的开头或结尾。屏幕截图显示了类似的滚动方向图示，但有三行，每行有一个不同的方块，带有黑色边框。图片显示了每行中滚动方向的递进，示意向右滚动。

Pinned

在滚动一大组项目时，pinned样式会将选定项目固定在指定位置。当用户浏览到列表的开头或结尾时，滚动行为会平滑过渡到natural的移动样式。借助可选属性pinnedSelectedItemOffset，当SelectionStrategy为pinned时，您可以定义选定项目的固定位置。 pinnedSelectedItemOffset属性决定选定项目在Carousel视口中固定 (‘pinned’) 的位置。您可以通过两种方式指定此位置：

以视口大小的百分比 (0-100%) 表示：
- 对于垂直Carousel：高度百分比
- 对于水平Carousel：宽度百分比
使用预设值：
- start（等于0%）
- center（等于50%）
- end（等于100%）

在水平模式下，从左边缘开始测量（书写顺序为从右到左的语言除外）。

可变滚动速度

Carousel组件引入了一个控制滚动速度的新功能，此功能是通过一组AnimationDurationProps来实现的。与Flatlist或Flashlist等现有组件不同，此功能增强了灵活性，让您可以微调滚动体验。 itemPressedDuration属性控制用户按下某个Carousel项目时，相应动画的持续时间。itemScrollDuration属性控制滚动到每个Carousel项目的动画持续时间。containerSelectionChangeDuration属性控制在更改选定的Carousel容器时，相应动画的持续时间。

选择边框

该Carousel组件支持在选定的用户界面项目周围显示边框。您可以设置边框样式，并选择如何绘制选定项目的内容和边框。您可以通过定义selectionBorder属性来启用这个边框。选择边框的默认属性如下所示。

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

Vega Carousel支持borderStrategy属性。该属性支持两种策略类型：

outset - 边框在项目的原始边界外侧绘制，因此项目内容尺寸保持不变，但项目整体尺寸变大。
inset - 边框在项目边界内侧绘制，覆盖项目内容，因此，虽然项目内容尺寸保持不变，但有一部分内容会被边框遮挡。项目整体尺寸保持不变。

属性

属性	类型	默认值	是否必需	详情
`dataAdapter`	-	`TRUE`	包含对四个用户定义回调函数的引用，Carousel会调用这些函数来访问您的项目：`getItem`、`getItemCount`、`getItemKey`和`notifyDataError`。有关这些回调的更多信息，请参阅Carousel项目数据适配器回调函数。
`renderItem`	`(info: CarouselRenderInfo) => React.ReactElement`	null	`TRUE`	对渲染Carousel项目的用户定义方法的引用。
`testID`	字符串	undefined	`FALSE`	用于在端到端测试中定位此Carousel的唯一标识符。
`uniqueId`	字符串	undefined	`FALSE`	此Carousel的随机唯一标识符，用于确定何时回收Carousel及其项目。通常用于垂直Carousel中的水平Carousel（例如，嵌套Carousel）。
`orientation`	horizontal、vertical	horizontal	`FALSE`	指定Carousel中项目的渲染方向和布局。
`renderedItemsCount`	number	8	`FALSE`	为了优化性能，在Carousel中项目循环滚动时，某一时刻需要渲染的项目数量。
`numOffsetItems`	number	2	`FALSE`	在将项目组件循环滚动到末尾之前，要保留在Carousel顶部/左侧的项目数量。
`navigableScrollAreaMargin`	number	0	`FALSE`	Carousel可导航内容区域在其朝向两侧所留出的边距空间（例如，水平Carousel为左和右，垂直Carousel为上和下），单位为密度无关像素。
`hasPreferredFocus`	布尔值	`FALSE`	`FALSE`	确定此组件在渲染时是否应自动获得焦点。
`initialStartIndex`	number	0	`FALSE`	指定Carousel中要选择的初始项目索引。
`hideItemsBeforeSelection`	布尔值	`FALSE`	`FALSE`	确定是否应隐藏选定项目之前的项目。
`trapSelectionOnOrientation`	布尔值	`FALSE`	`FALSE`	此标记可防止选择操作沿Carousel滚动方向移动到Carousel外部与其相邻的最近组件上。如果是水平Carousel，并且用户在起始项目处按下向后移动，或者在末尾项目处按下向前移动，此标记可防止选择操作脱离该Carousel。
`containerStyle`	undefined	`FALSE`	应用于Carousel容器的样式。
`itemStyle`	`CarouselItemStyleProps`	-	`FALSE`	应用于Carousel项目的样式。
`animationDuration`	`AnimationDurationProps`	-	`FALSE`	与Carousel及其项目相关的各种动画的持续时间。有关更多信息，请参阅动画时长属性部分。
`selectionStrategy`	`anchored`, `natural`, `pinned`	`anchored`	`FALSE`	指定选定项目如何根据方向键的按键操作在Carousel中移动。`anchored` - 当沿滚动方向向任一方向滚动时，使选定项目保持锚定在初始项目的位置。`natural` - 使选定项目沿着Carousel的滚动方向滑动，直到到达列表的开头或末尾。`pinned` - 使所选项目在列表开头和结尾遵循自然滚动行为。在其余滚动过程中，项目将固定到由`pinnedSelectedItemOffset`属性定义的特定位置。
`pinnedSelectedItemOffset`	百分比、start、center、end	0%	`FALSE`	该值决定了选定项目固定的位置，这是一个以Carousel前端边缘为基点的相对位置。
`onSelectionChanged`	`(event: CarouselSelectionChangeEvent) => void`	undefined	`FALSE`	每当列表中的当前选定项目发生变化时会调用（选择或取消选择Carousel时不会调用）。
`selectionBorder`	`SelectionBorderProps`	undefined	`FALSE`	设置后，选定项目具有绕其一圈的边框，可以设置样式。当启用选定项目的边框时，rgw的所有与样式相关的属性中，`selectionBorder`属性定义了边框的外观和效果。
`ref`	undefined	`FALSE`	设置后，提供对组件方法的引用，例如`ScrollTo`和`EnableDPad`，您可以使用引用的当前属性调用这些方法。

选择边框属性

属性	类型	默认值	是否必需	详情
`borderStrategy`	inset、outset	outset	`FALSE`	如何绘制选定项目的内容和边框。
`borderWidth`	number	8	`FALSE`	选定项目外围边框的粗细。
`borderColor`	字符串	white	`FALSE`	选定项目外围边框的颜色。
`borderRadius`	number	8	`FALSE`	确定圆角边框的圆角半径。
`borderStrokeWidth`	number	3	`FALSE`	将边框与项目内容分隔开的描边线条的粗细。
`borderStrokeRadius`	number	4	`FALSE`	定义将边框与项目内容分隔开的描边线条的圆角半径。
`borderStrokeColor`	字符串	black	`FALSE`	选择边框的描边线条的颜色。

动画时长属性

属性	类型	默认值	是否必需	详情
`itemPressedDuration`	number	0.15	`FALSE`	按下项目时，动画时间（以秒为单位）。
`itemScrollDuration`	number	0.2	`FALSE`	滚动每个项目时，动画时间（以秒为单位）。
`containerSelectionChangeDuration`	number	`itemPressedDuration`	`FALSE`	更改选定容器时，动画时间（以秒为单位）。

Carousel项目样式属性

属性	类型	默认值	是否必需	详情
`itemPadding`	number	20	`FALSE`	沿Carousel滚动方向，相邻项目之间的间隔（以像素为单位）。
`itemPaddingOnSelection`	number	itemPadding	`FALSE`	Carousel被选中时，沿Carousel滚动方向，相邻项目之间的间隔（以像素为单位）。
`pressedItemScaleFactor`	number	0.8	`FALSE`	当用户按下某个项目时，将应用于该项目的缩放比例倍数。
`selectedItemScaleFactor`	number	1	`FALSE`	某个项目选定时，应用于该项目的缩放比例倍数。当此值为`1.0`时，表示当用户滚动浏览列表时，选定项目没有缩放变化。
`getSelectedItemOffset`	`(info: CarouselRenderInfo) => ShiftFactor`	undefined	`FALSE`	检索某个项目相对于其当前位置的偏移值。

Carousel项目数据适配器回调函数

属性	类型	默认值	是否必需	详情
`getItem`	`(index: number) => ItemT`	undefined	`TRUE`	接收索引并返回项目数据对象。返回的对象调用其他数据访问函数来检索项目的信息。
`getItemCount`	`() => number;`	-	`TRUE`	返回列表的项目数。
`getItemKey`	`(info: CarouselRenderInfo) => KeyT`	undefined	`TRUE`	根据数据和索引为每个项目提供一个唯一键值。
`notifyDataError`	`(error: CarouselDataError) => boolean;`	-	`TRUE`	当列表中存在无法使用的项目时，列表组件会调用此函数。

Carousel方法

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`	-	-

故障排除

垂直滚动功能仅在高度已设定的情况下适用

对于垂直滚动（具体指自然滚动），您需要将containerStyle设置为固定的高度值。

​Vega Carousel更新

​随应用打包

​属性组合

​导入Vega Carousel

​示例

​水平Carousel

​垂直Carousel

​异构Carousel

​样式

​自定义类型

​功能

​数据适配器

​选择策略

​Anchored

​Natural

​Pinned

​可变滚动速度

​选择边框

​属性

​选择边框属性

​动画时长属性

​Carousel项目样式属性

​Carousel项目数据适配器回调函数

​Carousel方法

​故障排除

​垂直滚动功能仅在高度已设定的情况下适用