模板版本：v0.4.0

`react-native-snap-carousel`

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-snap-carousel 版本所属关系如下：

三方库名称	三方库版本	发布信息	支持RN版本	Autolink	编译API版本	社区基线版本	npm地址
@react-native-ohos/react-native-snap-carousel	~3.10.0	Gitcode Releases	0.77.* / 0.82.*	否	API12+	3.9.1	Npm Address
@react-native-ohos/react-native-snap-carousel	~3.9.2	Gitcode Releases	0.72.*	否	API12+	3.9.1	Npm Address
@react-native-oh-tpl/react-native-snap-carousel	<= 3.9.1-0.1.3@deprecated	Github Releases(deprecated)	0.72.*	否	API12+	3.9.1	Npm Address

1. 安装与使用

进入到工程目录并输入以下命令：

npm


npm install @react-native-ohos/react-native-snap-carousel

yarn


yarn add @react-native-ohos/react-native-snap-carousel

下面的代码展示了这个库的基本使用场景：

使用时 import 的库名不变。

import React, { useState } from "react";
import { View, Text, Image, StyleSheet } from "react-native";
import Carousel from "react-native-snap-carousel";

export default function SnapCarouselExample(): JSX.Element {
  const ENTRIES1 = [
    {
      title: "Beautiful and dramatic Antelope Canyon",
      subtitle: "Lorem ipsum dolor sit amet et nuncat mergitur",
      url: "https://www-file.huawei.com/-/media/corp2020/images/tech4all/cases1/12/white-headed-langur-en-1.png?la=zh",
    },
    {
      title: "Earlier this morning, NYC",
      subtitle: "Lorem ipsum dolor sit amet",
      url: "https://www-file.huawei.com/-/media/corp2020/images/tech4all/cases1/12/white-headed-langur-en-2.jpg?la=zh",
    },
    {
      title: "White Pocket Sunset",
      subtitle: "Lorem ipsum dolor sit amet et nuncat ",
      url: "https://www-file.huawei.com/-/media/corp2020/images/tech4all/cases1/12/white-headed-langur-en-1.png?la=zh",
    },
    {
      title: "Acrocorinth, Greece",
      subtitle: "Lorem ipsum dolor sit amet et nuncat mergitur",
      url: "https://www-file.huawei.com/-/media/corp2020/images/tech4all/cases1/12/white-headed-langur-en-2.jpg?la=zh",
    },
    {
      title: "The lone tree, majestic landscape of New Zealand",
      subtitle: "Lorem ipsum dolor sit amet",
      url: "https://www-file.huawei.com/-/media/corp2020/images/tech4all/cases1/12/white-headed-langur-en-1.png?la=zh",
    },
    {
      title: "Middle Earth, Germany",
      subtitle: "Lorem ipsum dolor sit amet",
      url: "https://www-file.huawei.com/-/media/corp2020/images/tech4all/cases1/12/white-headed-langur-en-2.jpg?la=zh",
    },
  ];

  const _renderItem = ({ item, index }: any) => {
    return (
      <View>
        <Image source={{ uri: item.url }} style={styles.image} />
      </View>
    );
  };

  return (
    <View>
      <Carousel
        data={ENTRIES1}
        renderItem={_renderItem}
        sliderWidth={300}
        itemWidth={250}
        containerCustomStyle={styles.carouselContainer}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  carouselContainer: {
    height: 200,
    width: "100%",
    marginBottom: 20,
  },
  image: {
    resizeMode: 'cover',
    borderTopLeftRadius: 8,
    borderTopRightRadius: 8,
    width: 250,
    height: 300
  }
});

2. 约束与限制

2.1 兼容性

本文档内容基于以下版本验证通过：

RNOH: 0.72.20; SDK: HarmonyOS NEXT Developer Beta1; IDE: DevEco Studio 5.0.3.200; ROM: 3.0.0.18;
RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;
RNOH: 0.82.7; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM: 6.0.0.328 SP26;

3. 属性

"Platform"列表示该属性在原三方库上支持的平台。

"HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

Carousel

Name	Description	Type	Required	Platform	HarmonyOS Support
data	要循环播放的项目数组	Array	yes	iOS/Android	yes
renderItem	从数据中获取一个项目并将其渲染到列表中。该函数接收一个参数 `{item, index}` (参见用法)并且必须返回一个 React 元素	Function	yes	iOS/Android	yes
itemWidth	轮播图项目的宽度（以像素为单位），所有项目必须相同	Number	yes	iOS/Android	yes
sliderWidth	轮播图本身的宽度（以像素为单位）	Number	yes	iOS/Android	yes
itemHeight	轮播图项目的高度（以像素为单位），所有项目必须相同	Number	yes	iOS/Android	yes
sliderHeight	轮播图本身的高度（以像素为单位）	Number	yes	iOS/Android	yes
loop	启用无限循环模式。⚠️ 如果 `enableSnap` 设置为 `false`，则此功能将不起作用。	Boolean	no	iOS/Android	yes
loopClonesPerSide	在原始项目每侧附加的克隆数量。当快速滑动时，用户最终需要暂停片刻，然后才能重新定位滚动（当到达项目集末尾时会发生这种情况）。通过增加此数值，用户将能够在停止之前滚动更多幻灯片；但您也会在内存中加载更多项目。这是在最佳用户体验和性能之间的权衡	Number	no	iOS/Android	yes
autoplay	在挂载时触发自动播放。如果您启用自动播放，我们建议您将 `enableMomentum` 设置为 `false`（默认值）并将 `lockScrollWhileSnapping` 设置为 `true`；这将稍微提升用户体验	Boolean	no	iOS/Android	yes
autoplayDelay	启动自动播放前和释放触摸后的延迟时间	Number	no	iOS/Android	yes
autoplayInterval	导航到下一个项目之前的延迟时间（毫秒）	Number	no	iOS/Android	yes
layout	定义项目的渲染和动画方式。可能的值为 `'default'`、`'stack'` 和 `'tinder'`。⚠️ 将此属性设置为 `'stack'` 或 `'tinder'` 将激活 `useScrollView` 以防止 `FlatList` 出现渲染错误。因此，如果您有大型数据集，这些布局将不适用，因为所有项目都将提前渲染。	String	no	iOS/Android	yes
containerCustomStyle	ScrollView 全局包装器的可选样式	View Style Object	no	iOS/Android	yes
contentContainerCustomStyle	ScrollView 项目容器的可选样式	View Style Object	no	iOS/Android	yes
inactiveSlideOpacity	应用于非活动幻灯片的透明度效果值	Number	no	iOS/Android	yes
inactiveSlideScale	应用于非活动幻灯片的"缩放"变换值	Number	no	iOS/Android	yes
inactiveSlideShift	应用于非活动幻灯片的"平移"变换值（参见 #204 或"自定义插值"文档获取使用示例）。此属性在默认布局以外的布局中将不起作用	Number	no	iOS/Android	yes
layoutCardOffset	用于增加或减少"堆叠"和"探戈"布局中的默认卡片偏移量	Number	no	iOS/Android	yes
slideStyle	每个项目容器的可选样式（即缩放和透明度被动画化的那个容器）	Animated View Style Object	no	iOS/Android	yes
scrollInterpolator	用于定义自定义插值。请参阅专门文档	Function	no	iOS/Android	yes
slideInterpolatedStyle	用于定义自定义插值。请参阅专门文档	Function	no	iOS/Android	yes
activeAnimationOptions	自定义动画选项。请注意，默认情况下将启用 `useNativeDriver`，并且透明度的缓动将始终保持线性。将此属性设置为 `null` 以外的值将触发自定义动画，并完全改变项目的动画方式：与其基于滚动值插值透明度和缩放（默认行为），不如在项目变为活动状态时立即播放您提供的自定义动画。这意味着您不能将 `layout`、`scrollInterpolator` 或 `slideInterpolatedStyle` 属性与 `activeAnimationOptions` 一起使用。	Object	no	iOS/Android	yes
activeAnimationType	自定义动画类型：`'decay'`、`'spring'` 或 `'timing'`。请注意，这只会应用于缩放动画，因为透明度的动画类型将始终设置为 timing（没有人希望透明度"弹跳"）	String	no	iOS/Android	yes
activeSlideAlignment	确定活动幻灯片相对于轮播图的对齐方式。可能的值为：`'start'`、`'center'` 和 `'end'`。不建议将此属性与 `layout` 属性一起使用。	String	no	iOS/Android	yes
activeSlideOffset	从滑块中心开始，滚动到活动状态之前的最小幻灯片距离	Number	no	iOS/Android	yes
apparitionDelay	`FlatList` 的初始化非常混乱，会出现许多不必要的闪烁和幻灯片移动。此属性控制在挂载时隐藏轮播图的延迟时间。警告：在 Android 上使用它可能导致渲染问题 (即图像不显示)。如果您决定使用它，请务必彻底测试	Number	no	iOS/Android	yes
callbackOffsetMargin	滚动事件可能触发得不够频繁，无法获得精确的测量值，因此无法提供可靠的回调。这通常是Android问题，可能与您使用的React Native版本有关（参见“不可靠的回调”）。为了解决这个问题，您可以定义一个小的边距来增加"最佳位置"的宽度。默认值应该能覆盖大多数情况，但是如果您遇到回调丢失的情况，您可能需要增加这个值。	Number	no	iOS/Android	yes
enableMomentum	参见 momentum	Boolean	no	iOS/Android	yes
enableSnap	如果启用，释放触摸后将滚动到最近/活动项的中心	Boolean	no	iOS/Android	yes
firstItem	要显示的第一个项目的索引。⚠️ 如果该属性似乎不起作用，请确保使用继承的属性`[getItemLayout](https://reactnative.dev/docs/flatlist#getitemlayout)` 和 `[initialScrollIndex](https://reactnative.dev/docs/flatlist#initialscrollindex)`。	Number	no	iOS/Android	yes
hasParallaxImages	轮播图是否包含组件。需要传递特定数据给子组件时使用。	Boolean	no	iOS/Android	yes
lockScrollTimeoutDuration^3.10.0+	此属性与 `lockScrollWhileSnapping` 配合使用。当滚动被锁定时，会创建一个计时器，以便在常规回调处理出现问题时释放滚动。通常情况下，您不需要使用此属性。	Number	no	iOS/Android	yes
lockScrollWhileSnapping	在轮播图切换到某个位置时，防止用户再次滑动。这样可以防止一些次要问题（如滚动时意外点击项目、在切换过程中点击轮播图导致滚动动画停止、在Android上快速反向短距离滑动时的卡顿行为）。唯一的缺点是启用此属性会妨碍用户在项目之间快速滑动，因为滑动之间需要短暂的停顿。请注意，如果 `enableMomentum` 设置为 `true`，此属性将不会产生任何效果，因为它会阻碍自然和预期的行为。	Boolean	no	iOS/Android	yes
scrollEnabled	当设置为 `false` 时，视图无法通过触摸交互进行滚动(继承属性)	Boolean	no	iOS/Android	yes
shouldOptimizeUpdates	是否实现 `shouldComponentUpdate` 策略以最小化更新	Boolean	no	iOS/Android	yes
swipeThreshold	触发快照的滑动 deltaX 值	Number	no	iOS/Android	yes
useScrollView	是否使用 `ScrollView` 组件而不是默认的 `FlatList` 组件。优点是可以避免 `FlatList` 可能引起的渲染问题，并提供与 React Native 0.43 之前版本的兼容性。主要缺点是您将无法从 `FlatList` 的高级优化中获益，也无法使用 `VirtualizedList` 或 `FlatList` 的特定属性。我们建议仅在幻灯片数量较少的情况下启用此选项，并在生产模式下彻底测试性能. 从 `3.7.6` 版本开始，此属性还接受自定义滚动组件(更多信息参见 #498)	Boolean	no	iOS/Android	yes
vertical	垂直布局幻灯片而不是水平布局	Boolean	no	iOS/Android	yes
inverted	是否反转滚动方向（通过 scale transform 为 -1 实现）	Boolean	no	iOS/Android	yes
realIndex	获取当前实际索引	Number	no	iOS/Android	yes
currentIndex	获取当前数据索引	Number	no	iOS/Android	yes
currentScrollPosition	获取当前滚动位置	Number	no	iOS/Android	yes

Pagination

Name	Description	Type	Required	Platform	HarmonyOS Support
activeDotIndex	当前激活圆点的索引	Number	no	iOS/Android	yes
dotsLength	圆点总数	Number	yes	iOS/Android	yes
dotStyle	激活圆点的样式	ViewStyle	no	iOS/Android	yes
inactiveDotStyle	非激活圆点的样式	ViewStyle	no	iOS/Android	yes
dotColor	激活圆点背景色	string	no	iOS/Android	yes
inactiveDotColor	非激活圆点背景色	string	no	iOS/Android	yes
inactiveDotOpacity	非激活圆点不透明度（0~1）	Number	no	iOS/Android	yes
inactiveDotScale	非激活圆点缩放比例	Number	no	iOS/Android	yes
containerStyle	圆点外层容器样式	ViewStyle	no	iOS/Android	yes
dotContainerStyle	每个圆点外层包裹容器样式（用于 flex 布局等）	ViewStyle	no	iOS/Android	yes
vertical	是否垂直排列圆点	Boolean	no	iOS/Android	yes
accessibilityLabel	无障碍标签	string	no	iOS/Android	yes
animatedDuration	动画持续时间（毫秒）	Number	no	iOS/Android	yes
animatedFriction	缩放弹性/过冲程度	Number	no	iOS/Android	yes
animatedTension	缩放动画速度	Number	no	iOS/Android	yes
tappableDots	是否允许点击圆点跳转。需配合 `carouselRef`	Boolean	no	iOS/Android	yes
carouselRef	Carousel 组件的 ref。`tappableDots` 模式下用于调用 `carouselRef.snapToItem(index)`	Carousel	no	iOS/Android	yes
activeOpacity	圆点被按下时的透明度反馈。仅 `tappableDots={true}` 生效	Number	no	iOS/Android	yes
delayPressInDot^3.10.0+	点击圆点延迟触发时间（毫秒）	Number	no	iOS/Android	yes
dotElement	自定义激活圆点元素	ReactElement	no	iOS/Android	yes
inactiveDotElement	自定义非激活圆点元素	ReactElement	no	iOS/Android	yes

ParallaxImage

Name	Description	Type	Required	Platform	HarmonyOS Support
source	图片源	ImageSourcePropType	yes	iOS/Android	yes
containerStyle	图片外层容器样式	ViewStyle	no	iOS/Android	yes
dimensions	图片在屏幕上的实际尺寸	number	no	iOS/Android	yes
fadeDuration	图片加载完成后的淡入动画时长（毫秒）	number	no	iOS/Android	yes
parallaxFactor	视差效果速度。值越大，"放大/拉近"感越强	number	no	iOS/Android	yes
showSpinner	图片加载时是否显示加载指示器	boolean	no	iOS/Android	yes
spinnerColor	加载指示器颜色	string	no	iOS/Android	yes
AnimatedImageComponent	自定义的动画图片组件	Component	no	iOS/Android	yes

4. 静态方法

"Platform"列表示该属性在原三方库上支持的平台。

"HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

Prop	Description	Type	Required	Platform	HarmonyOS Support
onLayout(event)	暴露的 `View` 回调函数；在组件挂载和布局变化时调用	Function	no	iOS/Android	yes
onScroll(event)	暴露的 `ScrollView` 回调函数；在滚动过程中触发	Function	no	iOS/Android	yes
onBeforeSnapToItem(slideIndex)	在确定新激活项之后、跳转之前触发的回调函数	Function	no	iOS/Android	yes
onSnapToItem(slideIndex)	在跳转到某个项之后触发的回调函数	Function	no	iOS/Android	yes
snapToItem (slideIndex)	滚动到指定索引的 item	Function	no	iOS/Android	yes
snapToNext()	滚动到下一个 item	Function	no	iOS/Android	yes
snapToPrev()	滚动到上一个 item	Function	no	iOS/Android	yes
startAutoplay()	启动自动播放	Function	no	iOS/Android	yes
stopAutoplay()	停止自动播放	Function	no	iOS/Android	yes
pauseAutoPlay()	暂停自动播放	Function	no	iOS/Android	yes
triggerRenderingHack()	FlatList 内容隐藏 bug 的 workaround	Function	no	iOS/Android	yes
getInputRangeFromIndexes(indexes)	自定义滚动插值动画的辅助函数	Function	no	iOS/Android	yes

5. 遗留问题

enableMomentum属性在ios设备上效果不明显，Harmony上效果使用正常: issue#1

6. 开源协议

本项目基于 The BSD 3-Clause License (BSD 3-Clause) ，请自由地享受和参与开源。