@arco-design/mobile-react 2.19.0

package/cjs/carousel/index.d.ts

@@ -0,0 +1,366 @@
+import React, { CSSProperties, ReactNode } from 'react';
+export interface CarouselListItem {
+    /**
+     * 图片链接
+     * @en image resource
+     */
+    src: string;
+    /**
+     * 图片底部固定的文字
+     * @en Fixed text at the bottom of the image
+     */
+    text?: ReactNode;
+    /**
+     * 点击图片回调
+     * @en Callback function for clicking the image
+     */
+    onClick?: (e: React.MouseEvent<HTMLImageElement, MouseEvent>) => void;
+}
+export interface CarouselProps {
+    /**
+     * 样式类名
+     * @en Custom classname
+     */
+    className?: string;
+    /**
+     * 最外层容器自定义样式
+     * @en Outermost container custom stylesheet
+     */
+    wrapStyle?: CSSProperties;
+    /**
+     * 内层轮播容器自定义样式
+     * @en Inner carousel container custom stylesheet
+     */
+    style?: CSSProperties;
+    /**
+     * 轮播内部内容
+     * @en Carousel internal content
+     */
+    children?: ReactNode;
+    /**
+     * 轮播图片列表，省略子元素的简写，传入图片url数组，也可通过`text`指定图片底部的蒙层文字内容
+     * @en Carousel image list, omit the shorthand of children elements, input the image url array, or specify the content of the masked text at the bottom of the image through `text`
+     */
+    list?: CarouselListItem[];
+    /**
+     * 自动切换轮播滑块时，动画的执行时间(ms)
+     * @en Animation duration(ms) when the carousel slider is automatically toggled,
+     * @default 500
+     */
+    animateDuration?: number;
+    /**
+     * 手动切换轮播滑块时，当手指释放后，动画的执行时间(ms)
+     * @en Animation duration(ms) after the finger is released When manually switching the carousel slider
+     * @default 300
+     */
+    animateDurationSlide?: number;
+    /**
+     * 是否开启循环轮播，当指定轮播滑块宽度时该属性不生效
+     * @en Whether to enable circular rotation, it does not take effect when the slider width is specified
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * 是否开启自动播放
+     * @en Whether to enable autoplay
+     * @default true
+     */
+    autoPlay?: boolean;
+    /**
+     * 是否响应手势滑动
+     * @en Whether to respond to gesture swipe
+     * @default true
+     */
+    swipeable?: boolean;
+    /**
+     * 开启自动播放时，每一个滑块的停留时间(ms)
+     * @en The stay duration of each slider when autoplay is turned on
+     * @default 4000
+     */
+    stayDuration?: number;
+    /**
+     * 指定容器宽度，默认为基于父容器100%
+     * @en Width of the box, the default value is 100% based on the parent container
+     */
+    boxWidth?: number | string;
+    /**
+     * 指定容器高度，默认为自适应高度；当设置`vertical=true`时，该属性为必填
+     * @en Height of the box. The property is required when vertical is true
+     */
+    boxHeight?: number | string;
+    /**
+     * 指定初始容器宽度，常用于ssr首屏初始化，水平轮播时可用
+     * @en Initial box width, commonly used for ssr first screen initialization, available when horizontal rotation
+     */
+    baseBoxWidth?: number;
+    /**
+     * 指定初始容器宽度，常用于ssr首屏初始化，垂直轮播时可用
+     * @en Initial box height, commonly used for ssr first screen initialization, available when vertical rotation
+     */
+    baseBoxHeight?: number;
+    /**
+     * 指定轮播滑块宽度，为0或不传时为默认的父容器宽度
+     * @en Width of the carousel slider, the default value is parent container width if it is 0 or not input
+     * @default 0
+     */
+    width?: number;
+    /**
+     * 指定轮播滑块高度，如不指定则为自适应高度
+     * @en Height of the carousel slider, it will be adaptive if not input
+     */
+    height?: number;
+    /**
+     * 默认选中的滑块索引
+     * @en Default selected slider index
+     * @default 0
+     */
+    initialIndex?: number;
+    /**
+     * 自定义轮播索引
+     * @en Custom indicator
+     */
+    renderIndicator?: (currentIndex: number, total: number, lastIndex: number) => ReactNode;
+    /**
+     * 轮播索引位置
+     * @en Position of the indicator
+     * @default "center"
+     */
+    indicatorPos?: 'start' | 'center' | 'end';
+    /**
+     * 垂直轮播索引横向位置
+     * @en Horizontal position of the vertical indicator
+     * @default "left"
+     */
+    indicatorVerticalPos?: 'left' | 'right';
+    /**
+     * 轮播索引是否放轮播图外面
+     * @en Whether the indicator is placed outside the carousel
+     */
+    indicatorOutside?: boolean;
+    /**
+     * 是否展示轮播索引
+     * @en Whether to show the indicator
+     * @default true
+     */
+    showIndicator?: boolean;
+    /**
+     * children 只有一个时隐藏轮播索引
+     * @en Whether to hide the indicator if just one child
+     * @default true
+     */
+    hideSingleIndicator?: boolean;
+    /**
+     * 轮播索引样式类型
+     * @en the style type of the indicator
+     * @default "square"
+     */
+    indicatorType?: 'square' | 'circle';
+    /**
+     * 轮播索引类名
+     * @en Indicator classname
+     */
+    indicatorClass?: string;
+    /**
+     * 轮播索引是否反色，默认根据索引是否放在外面决定
+     * @en Whether the carousel indicator is inverse color, the default is determined according to whether the indicator is placed outside
+     */
+    indicatorInverse?: boolean;
+    /**
+     * 子元素间距
+     * @en Children elements spacing
+     * @default 0
+     */
+    spaceBetween?: number;
+    /**
+     * 前后两端露出距离，设置值时不能循环轮播
+     * @en The exposed distance of the front and rear. When the value is set, the carousel cannot be rotated.
+     * @default 0
+     */
+    offsetBetween?: number | {
+        left?: number;
+        right?: number;
+    };
+    /**
+     * 手动控制当前展示元素
+     * @en Manually control the current display element
+     */
+    currentIndex?: number;
+    /**
+     * 容器高度自适应
+     * @en Whether the container height is adaptive
+     * @default false
+     */
+    autoHeight?: boolean;
+    /**
+     * 滑动切换距离阈值(宽度比例)，范围为[0, 1]，如果该属性和`distanceToChange`属性均设置，则实际计算结果更大的生效
+     * @en Sliding switching distance threshold (width ratio), the range is [0, 1]. If the property and the `distanceToChange` property are both set, the actual calculation result will take effect with a larger value.
+     * @default 0.3
+     */
+    percentToChange?: number;
+    /**
+     * 滑动切换距离阈值(固定px宽度)，如果该属性和`percentToChange`属性均设置，则实际计算结果更大的生效
+     * @en Sliding switching distance threshold (fixed px width), if both this property and the `percentToChange` property are set, the actual calculation result will take effect with a larger one
+     * @default 10
+     */
+    distanceToChange?: number;
+    /**
+     * 滑动切换速度阈值(手指从按下到抬起之间的滑动速度，单位为px/s)，与滑动切换距离阈值同时设置时，满足其中一个即生效
+     * @en The sliding switching speed threshold (the sliding speed of the finger from pressing to lifting, in px/s), when it is set at the same time as the sliding switching distance threshold, it will take effect if one of them is satisfied.
+     * @default 200
+     */
+    speedToChange?: number;
+    /**
+     * 是否垂直轮播，设置后`boxHeight`属性必填
+     * @en Whether to rotate vertically, the `boxHeight` property is required after setting
+     */
+    vertical?: boolean;
+    /**
+     * 只加载当前页相邻的n个内容，为0时会销毁所有相邻内容，不传则加载所有内容
+     * @en Only load the n sliders adjacent to the current slider. If it is 0, all adjacent content will be destroyed. If not input, all sliders will be loaded.
+     */
+    lazyloadCount?: number;
+    /**
+     * 触发onTouchStopped的最小阈值
+     * @en Minimum threshold to trigger onTouchStopped
+     * @default 0
+     */
+    stopTouchThreshold?: number;
+    /**
+     * 当不可循环时，是否开启滑动到最前或最后时的回弹效果
+     * @en When it is not loopable, whether to enable the rebound effect when sliding to the front or the end
+     * @default false
+     */
+    bounceWhenNoLoop?: boolean;
+    /**
+     * 当开启最前或最后时的回弹效果时的阻尼系数
+     * @en The damping coefficient when the front or rear rebound effect is turned on
+     * @default 3
+     */
+    bounceDampRate?: number;
+    /**
+     * 非active的滑块的大小比例，[0, 1]的小数，设置后切换时将有放大效果
+     * @en The size ratio of the inactive slider, the value range is [0, 1]. After setting, it will have a magnification effect when switching.
+     */
+    inactiveScale?: number;
+    /**
+     * 触摸事件是否需要 stopPropagation
+     * @en Whether the touch event requires stopPropagation
+     * @default true
+     */
+    stopPropagation?: boolean;
+    /**
+     * 是否需要fake首尾item，用于offsetBetween不等于0时循环轮播的衔接
+     * @en Whether to fake the first and last items, which is used for the connection of the circular rotation when the offsetBetween is not equal to 0
+     * @default false
+     */
+    fakeItem?: boolean;
+    /**
+     * 滑动到最后时是否允许留白，仅在loop=false且设置了width时有效
+     * @en Whether to allow white space when sliding to the end, only valid when loop=false and width is set
+     * @default false
+     */
+    allowEndBlank?: boolean;
+    /**
+     * 自定义手指滑动跟手的距离计算方式，posDis表示touchmove的距离，wrapSize表示容器在滑动方向的尺寸，childSize表示滑块在滑动方向的尺寸
+     * @en Customize the calculation method of the finger swipe distance. posDis - touchmove distance, wrapSize - container size in the sliding direction, childSize - slider size in the sliding direction
+     * @default (posDis, wrapSize, childSize) => childSize * (posDis / wrapSize)
+     */
+    distanceProcessor?: (posDis: number, wrapSize: number, childSize: number) => number;
+    /**
+     * 组件内部的滚动容器，用于豁免滑动事件响应
+     * @en The scroll container inside the component, used to exempt the sliding event response
+     */
+    getInnerScrollContainer?: () => (HTMLElement | null)[] | HTMLElement | null;
+    /**
+     * 当轮播不支持循环且滑到最前面或最后面，还想再滑动时触发
+     * @en Triggered when the carousel does not support looping and slides to the front or back, but want to slide again
+     */
+    onTouchStopped?: (direction: -1 | 1) => void;
+    /**
+     * 轮播滑块切换时触发
+     * @en  Triggered when the carousel slider is toggled
+     *  */
+    onChange?: (index: number) => void;
+    /**
+     * 轮播滑块切换，动画完成后触发
+     * @en Triggered after the carousel slider toggle animation is complete
+     * */
+    onAfterChange?: (index: number, oldIndex: number) => void;
+    /**
+     * 轮播内容touchstart事件
+     * @en Carousel content touchstart event
+     *  */
+    onTouchStart?: (e: TouchEvent, total: number, index: number) => void | boolean;
+    /**
+     * 轮播内容touchmove事件
+     * @en Carousel content touchmove event
+     *  */
+    onTouchMove?: (e: TouchEvent, total: number, index: number) => void | boolean;
+    /**
+     * 轮播内容touchend / touchcancel事件
+     * @en Carousel content touchend / touchcancel event
+     *  */
+    onTouchEnd?: (e: TouchEvent, total: number, index: number) => void | boolean;
+    /**
+     * 轮播切换动画开始时回调
+     * @en Callback when the carousel transition animation starts
+     *  */
+    onTransitionStart?: () => void;
+    /**
+     * 轮播切换动画结束时回调
+     * @en Callback when the carousel transition animation ends
+     *  */
+    onTransitionEnd?: () => void;
+    /**
+     * 轮播左右滑动时回调，用于监听滑动距离以做滑动同步交互
+     * @en Callback when the carousel slides left and right, used to monitor the sliding distance for sliding synchronization interaction
+     *  */
+    onDistanceChange?: (distance: number, wrapSize: number, activeIndex: number) => void;
+    /**
+     * 自定义页面展示隐藏监听，默认在document监听visibilitychange事件，返回function用于在组件卸载时移除监听
+     * @en Custom page visibility listener. By default, the visibilitychange event is monitored in the document. The return function is used to remove the listener when the component is unloaded.
+     *  */
+    onPageVisibleChange?: (updateWhenVisible: () => void, updateWhenInvisible: () => void) => () => void | undefined;
+}
+export interface CarouselRef {
+    /**
+     * 最外层元素 DOM
+     * @en The outermost element DOM
+     */
+    dom: HTMLDivElement | null;
+    /**
+     * 轮播图子项包裹容器 DOM，承载了 touch 相关事件
+     * @en Wrapper DOM of carousel slider items, carry touch related events
+     */
+    wrap: HTMLDivElement | null;
+    /**
+     * 轮播图每个子项的 DOM
+     * @en Carousel slider DOM
+     * */
+    items: (HTMLDivElement | null)[];
+    /**
+     * 在某些条件下内部会禁用循环轮播，这里表示循环是否被禁用
+     * @en The loop rotation is disabled internally under certain conditions, here indicates whether the loop is disabled
+     */
+    noLoop: boolean;
+    /**
+     * 手动重新计算布局
+     * @en Recalculate the layout manually
+     */
+    updateData: () => void;
+    /**
+     * 手动更新当前选中索引，rightNow 表示是否立刻跳转到目标索引，否则执行过渡动画到目标索引
+     * @en Manually update the currently selected index, rightNow indicates whether to jump to the target index immediately, otherwise perform a transition animation to the target index
+     * */
+    changeIndex: (newIndex: number, rightNow?: boolean) => void;
+}
+/**
+ * 轮播组件，支持自定义轮播索引样式及滑块宽度。**需要注意的是，如果正使用`fastclick`，需要为 touchstart 的 target 添加`needsclick`类**（<a href="https://github.com/ftlabs/fastclick#ignore-certain-elements-with-needsclick" target="_blank">详情戳这里</a>），以规避`fastclick`逻辑与组件内部的手势冲突。（如果使用了`list`属性则无需额外添加）
+ * @en Carousel component, supports custom carousel index style and slider width. **Note that if you are using `fastclick`, you need to add a `needsclick` class to the touchstart target ** (<a href="https://github.com/ftlabs/fastclick#ignore-certain-elements- with-needsclick" target="_blank">click here for details</a>) to avoid `fastclick` logic conflicts with gestures inside the component. (no need to add if `list` is set)
+ * @type 数据展示
+ * @type_en Data Display
+ * @name 轮播图
+ * @name_en Carousel
+ */
+declare const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<CarouselRef>>;
+export default Carousel;