@ehmetlabs/webf-react-carousel-slider 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,626 @@
+import React from 'react';
+import { WebFElementWithMethods } from '@openwebf/react-core-ui';
+
+declare enum CenterPageEnlargeStrategy$1 {
+    scale = "scale",
+    height = "height",
+    zoom = "zoom"
+}
+declare enum Axis$1 {
+    horizontal = "Axis.horizontal",
+    vertical = "Axis.vertical"
+}
+declare enum Curve$1 {
+    ease = "Curves.ease",
+    easeIn = "Curves.easeIn",
+    easeOut = "Curves.easeOut",
+    easeInOut = "Curves.easeInOut",
+    fastOutSlowIn = "Curves.fastOutSlowIn",
+    linear = "Curves.linear"
+}
+interface CarouselSliderProps {
+    /**
+     * 当前页面索引（0-based）
+     *
+     * - 设置此值会触发页面跳转
+     * - 页面变化时会自动更新此值
+     * - 读取此值可获取当前页索引
+     *
+     * @default 0
+     * @attribute current-index
+     */
+    currentIndex?: number;
+    /**
+     * JSON 格式的批量配置
+     *
+     * 一次设置多个属性，使用 JSON 格式
+     *
+     * @example
+     * carousel.options = JSON.stringify({
+     *   autoplay: true,
+     *   autoplayInterval: 4.0,
+     *   viewportFraction: 0.8,
+     *   enlargeCenterPage: true,
+     *   enlargeFactor: 0.3
+     * });
+     *
+     * @attribute options
+     */
+    options?: string;
+    /**
+     * 轮播高度（字符串形式）
+     *
+     * - 如果设置了 height，将覆盖 aspectRatio
+     * - 支持 "400", "400px", "400.0" 等格式
+     * - 单位为逻辑像素
+     *
+     * @default null
+     * @attribute height
+     */
+    height?: string;
+    /**
+     * 宽高比
+     *
+     * - 如果未设置 height，则根据此比例计算高度
+     * - 常见比例: 16/9, 4/3, 1/1
+     *
+     * @default 16/9
+     * @attribute aspect-ratio
+     */
+    aspectRatio?: number;
+    /**
+     * 视口占比
+     *
+     * - 每个页面占据视口的宽度比例
+     * - 范围: 0.0 - 1.0
+     * - 小于 1.0 时可看到相邻页面的一部分
+     *
+     * @default 0.8
+     * @attribute viewport-fraction
+     */
+    viewportFraction?: number;
+    /**
+     * 初始页面索引
+     *
+     * - 组件首次加载时显示的页面
+     * - 仅在初始化时生效
+     *
+     * @default 0
+     * @attribute initial-page
+     */
+    initialPage?: number;
+    /**
+     * 两端添加填充
+     *
+     * - viewportFraction < 1.0 时生效
+     * - 为首尾页面添加填充，使其可以居中显示
+     *
+     * @default true
+     * @attribute pad-ends
+     */
+    padEnds: boolean;
+    /**
+     * 禁用 Center widget
+     *
+     * - 为每个页面禁用 Center widget
+     * - 可能会影响布局对齐
+     *
+     * @default false
+     * @experimental 暂未实现，将在未来版本中添加
+     * @attribute disable-center
+     */
+    disableCenter?: boolean;
+    /**
+     * 启用无限循环滚动
+     *
+     * - true: 可以无限向前/向后滚动
+     * - false: 到达首尾时停止
+     *
+     * @default true
+     * @attribute enable-infinite-scroll
+     */
+    enableInfiniteScroll: boolean;
+    /**
+     * 循环到最近的页面
+     *
+     * - enableInfiniteScroll = true 时生效
+     * - 跳转时选择最近的循环路径
+     * - 减少跳转动画的距离
+     *
+     * @default true
+     * @experimental 暂未实现，将在未来版本中添加
+     * @attribute animate-to-closest
+     */
+    animateToClosest?: boolean;
+    /**
+     * 反向滚动
+     *
+     * - 翻转轮播的滚动方向
+     * - 水平模式下从右到左
+     * - 垂直模式下从下到上
+     *
+     * @default false
+     * @attribute reverse
+     */
+    reverse: boolean;
+    /**
+     * 滚动方向
+     *
+     * - Axis.horizontal: 水平滚动（默认）
+     * - Axis.vertical: 垂直滚动
+     *
+     * @default 'Axis.horizontal'
+     * @attribute scroll-direction
+     */
+    scrollDirection?: Axis$1;
+    /**
+     * 页面吸附效果
+     *
+     * - true: 滚动停止时自动吸附到页面边界
+     * - false: 可以停留在任意位置
+     *
+     * @default true
+     * @attribute page-snapping
+     */
+    pageSnapping: boolean;
+    /**
+     * 滚动物理效果
+     *
+     * - 高级配置，控制滚动行为
+     * - 通常不需要手动设置
+     *
+     * @experimental 暂未实现，未来版本可能添加
+     * @attribute scroll-physics
+     */
+    scrollPhysics?: string;
+    /**
+     * 启用自动播放
+     *
+     * - 开启后会按间隔自动切换页面
+     * - 可通过 pause() 方法或用户交互暂停
+     * - 可通过 resume() 方法恢复
+     *
+     * @default false
+     * @attribute autoplay
+     */
+    autoplay: boolean;
+    /**
+     * 自动播放间隔（秒）
+     *
+     * - 两次自动播放之间的时间间隔
+     * - 单位为秒（不是毫秒）
+     * - 建议最小值: 0.5 秒
+     *
+     * @default 4.0
+     * @attribute autoplay-interval
+     */
+    autoplayInterval?: number;
+    /**
+     * 自动播放动画持续时间（毫秒）
+     *
+     * - 页面切换动画的持续时间
+     * - 单位为毫秒
+     * - 建议范围: 100 - 5000
+     *
+     * @default 800
+     * @attribute auto-play-animation-duration
+     */
+    autoPlayAnimationDuration?: number;
+    /**
+     * 自动播放动画曲线
+     *
+     * - 控制动画的时间-速度曲线
+     * - 常用值: Curves.fastOutSlowIn（默认）、Curves.ease
+     *
+     * @default 'Curves.fastOutSlowIn'
+     * @attribute auto-play-curve
+     */
+    autoPlayCurve?: Curve$1;
+    /**
+     * 触摸时暂停自动播放
+     *
+     * - 用户触摸轮播时自动暂停
+     * - 松手后自动恢复播放
+     * - 提供更好的交互体验
+     *
+     * @default true
+     * @attribute pause-auto-play-on-touch
+     */
+    pauseAutoPlayOnTouch: boolean;
+    /**
+     * 手动导航时暂停自动播放
+     *
+     * - 调用 next()/previous()/jumpToPage() 时暂停
+     * - 动画完成后自动恢复播放
+     * - 防止自动播放干扰用户操作
+     *
+     * @default true
+     * @attribute pause-auto-play-on-manual-navigate
+     */
+    pauseAutoPlayOnManualNavigate: boolean;
+    /**
+     * 非无限循环时到达末尾暂停自动播放
+     *
+     * - enableInfiniteScroll = false 时生效
+     * - 到达最后一页时是否暂停自动播放
+     * - false 则会循环到第一页
+     *
+     * @default false
+     * @experimental 暂未实现，将在未来版本中添加
+     * @attribute pause-auto-play-in-finite-scroll
+     */
+    pauseAutoPlayInFiniteScroll?: boolean;
+    /**
+     * 放大中心页
+     *
+     * - 当前页面显示得比相邻页面大
+     * - 创造出一种深度感
+     * - 需要 enlargeFactor 配合使用
+     *
+     * @default false
+     * @attribute enlarge-center-page
+     */
+    enlargeCenterPage: boolean;
+    /**
+     * 中心页放大策略
+     *
+     * - scale: 通过缩放放大（默认）
+     * - height: 通过高度放大
+     * - zoom: 通过缩放放大（与 scale 类似但有细微差别）
+     *
+     * @default 'scale'
+     * @experimental 暂未实现，将在未来版本中添加
+     * @attribute enlarge-strategy
+     */
+    enlargeStrategy?: CenterPageEnlargeStrategy$1;
+    /**
+     * 中心页放大因子
+     *
+     * - 相邻页面相对于中心页的缩小比例
+     * - 范围: 0.0 - 1.0
+     * - 值越大，相邻页缩小越多
+     *
+     * @default 0.3
+     * @attribute enlarge-factor
+     */
+    enlargeFactor?: number;
+    /**
+     * 页面变化事件
+     *
+     * 当轮播切换到新页面时触发
+     *
+     * @event change
+     * @property {number} detail.index - 新页面索引（0-based）
+     * @property {CarouselPageChangedReason} detail.reason - 触发原因
+     *
+     * @example
+     * carousel.addEventListener('change', (event) => {
+     *   console.log('New page:', event.detail.index);
+     *   console.log('Reason:', event.detail.reason);
+     *   // Reason: 'timed' | 'manual' | 'controller'
+     * });
+     */
+    onChange?: (event: CustomEvent<any>) => void;
+    /**
+     * 滑动开始事件
+     *
+     * 用户开始拖动轮播时触发
+     *
+     * @event slidestart
+     *
+     * @example
+     * carousel.addEventListener('slidestart', () => {
+     *   console.log('User started sliding');
+     * });
+     */
+    onSlidestart?: (event: Event) => void;
+    /**
+     * 滑动结束事件
+     *
+     * 用户停止拖动轮播时触发
+     *
+     * @event slideend
+     *
+     * @example
+     * carousel.addEventListener('slideend', () => {
+     *   console.log('User stopped sliding');
+     * });
+     */
+    onSlideend?: (event: Event) => void;
+    /**
+     * 页面动画开始事件
+     *
+     * 页面切换动画开始时触发
+     *
+     * @event pageanimationstart
+     * @property {number} detail.from - 起始页面索引
+     * @property {number} detail.to - 目标页面索引
+     *
+     * @example
+     * carousel.addEventListener('pageanimationstart', (event) => {
+     *   console.log(`Animating from ${event.detail.from} to ${event.detail.to}`);
+     * });
+     */
+    onPageanimationstart?: (event: CustomEvent<any>) => void;
+    /**
+     * 页面动画结束事件
+     *
+     * 页面切换动画完成时触发
+     *
+     * @event pageanimationend
+     * @property {number} detail.index - 当前页面索引
+     *
+     * @example
+     * carousel.addEventListener('pageanimationend', (event) => {
+     *   console.log(`Animation ended at page ${event.detail.index}`);
+     * });
+     */
+    onPageanimationend?: (event: CustomEvent<any>) => void;
+    /**
+     * 自动播放暂停事件
+     *
+     * 自动播放被暂停时触发
+     *
+     * @event autoplaypause
+     *
+     * @example
+     * carousel.addEventListener('autoplaypause', () => {
+     *   console.log('Autoplay paused');
+     * });
+     */
+    onAutoplaypause?: (event: Event) => void;
+    /**
+     * 自动播放恢复事件
+     *
+     * 自动播放恢复时触发
+     *
+     * @event autoplayresume
+     *
+     * @example
+     * carousel.addEventListener('autoplayresume', () => {
+     *   console.log('Autoplay resumed');
+     * });
+     */
+    onAutoplayresume?: (event: Event) => void;
+    /**
+     * 滚动事件
+     *
+     * 轮播滚动时持续触发
+     *
+     * @event scrolled
+     * @property {number | null} detail - 当前滚动位置（像素），null 表示无法确定
+     *
+     * @example
+     * carousel.addEventListener('scrolled', (event) => {
+     *   console.log('Scrolled to:', event.detail);
+     * });
+     *
+     * @experimental 暂未实现，将在未来版本中添加
+     */
+    onScrolled?: (event: CustomEvent<number | null>) => void;
+    /**
+     * 单项点击事件
+     *
+     * 点击轮播图片项时触发
+     *
+     * @event itemclick
+     * @property {string | number} detail.id - 图片项 ID
+     *
+     * @example
+     * carousel.addEventListener('itemclick', (event) => {
+     *   console.log('Clicked item id:', event.detail.id);
+     * });
+     */
+    onItemclick?: (event: CustomEvent<any>) => void;
+    /**
+     * HTML id attribute
+     */
+    id?: string;
+    /**
+     * Additional CSS styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Children elements
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * Element interface with methods accessible via ref
+ * @example
+ * ```tsx
+ * const ref = useRef<CarouselSliderElement>(null);
+ * // Call methods on the element
+ * ref.current?.finishRefresh('success');
+ * ```
+ */
+interface CarouselSliderElement extends WebFElementWithMethods<{
+    /**
+     * 下一页（带动画）
+     *
+     * 切换到下一页，使用动画
+     *
+     * @param duration - 动画持续时间（毫秒），默认 300ms
+     * @param curve - 动画曲线，默认 'Curves.linear'
+     *
+     * @throws 如果已到达最后一页且 enableInfiniteScroll = false
+     *
+     * @example
+     * carousel.next();
+     *
+     * @example
+     * // 自定义动画
+     * carousel.next(500, 'Curves.easeInOut');
+     */
+    next(duration: number, curve: Curve$1): void;
+    /**
+     * 上一页（带动画）
+     *
+     * 切换到上一页，使用动画
+     *
+     * @param duration - 动画持续时间（毫秒），默认 300ms
+     * @param curve - 动画曲线，默认 'Curves.linear'
+     *
+     * @throws 如果已在第一页且 enableInfiniteScroll = false
+     *
+     * @example
+     * carousel.previous();
+     */
+    previous(duration: number, curve: Curve$1): void;
+    /**
+     * 跳转到指定页（无动画）
+     *
+     * 立即跳转到目标页面，不显示动画
+     *
+     * @param page - 目标页面索引（0-based）
+     * @throws 如果 page < 0 或 page >= 页面总数
+     *
+     * @example
+     * carousel.jumpToPage(0);  // 跳转到第一页
+     * carousel.jumpToPage(2);  // 跳转到第三页
+     */
+    jumpToPage(page: number): void;
+    /**
+     * 动画到指定页（带动画）
+     *
+     * 带动画切换到目标页面
+     *
+     * @param page - 目标页面索引（0-based）
+     * @param duration - 动画持续时间（毫秒），默认 300ms
+     * @param curve - 动画曲线，默认 'Curves.linear'
+     * @throws 如果 page < 0 或 page >= 页面总数
+     *
+     * @example
+     * // 使用默认动画
+     * carousel.animateToPage(2);
+     *
+     * @example
+     * // 自定义动画
+     * carousel.animateToPage(2, 500, 'Curves.easeInOut');
+     *
+     * @experimental 暂未实现，将在未来版本中添加
+     */
+    animateToPage(page: number, duration: number, curve: Curve$1): void;
+    /**
+     * 暂停自动播放
+     *
+     * 立即暂停自动播放
+     * - 触发 autoplaypause 事件
+     * - 不会修改 autoplay 属性
+     *
+     * @example
+     * carousel.pause();
+     *
+     * @see resume
+     * @see stopAutoPlay
+     */
+    pause(): void;
+    /**
+     * 恢复自动播放
+     *
+     * 恢复之前暂停的自动播放
+     * - 触发 autoplayresume 事件
+     * - 如果 autoplay = false，此方法无效
+     *
+     * @example
+     * carousel.resume();
+     *
+     * @see pause
+     * @see startAutoPlay
+     */
+    resume(): void;
+    /**
+     * 启动自动播放
+     *
+     * 强制启动自动播放计时器
+     * - 比 resume() 更明确
+     * - 即使 autoplay = false 也能启动
+     *
+     * @example
+     * carousel.startAutoPlay();
+     *
+     * @see resume
+     * @see stopAutoPlay
+     *
+     * @experimental 暂未实现，将在未来版本中添加
+     */
+    startAutoPlay(): void;
+    /**
+     * 停止自动播放
+     *
+     * 强制停止自动播放计时器
+     * - 比 pause() 更明确
+     * - 会暂停直到调用 startAutoPlay() 或 resume()
+     *
+     * @example
+     * carousel.stopAutoPlay();
+     *
+     * @see pause
+     * @see startAutoPlay
+     *
+     * @experimental 暂未实现，将在未来版本中添加
+     */
+    stopAutoPlay(): void;
+}> {
+}
+/**
+ * Properties for <carousel-slider> Custom Element
+所有属性都支持 HTML 属性方式设置（kebab-case）
+和 JavaScript 属性方式设置（camelCase）
+@example
+// HTML 方式
+<carousel-slider autoplay="true" autoplay-interval="4"></carousel-slider>
+@example
+// JavaScript 方式
+carousel.autoplay = true;
+carousel.autoplayInterval = 4;
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<CarouselSliderElement>(null);
+ *
+ * <CarouselSlider
+ *   ref={ref}
+ *   // Add props here
+ * >
+ *   Content
+ * </CarouselSlider>
+ *
+ * // Call methods on the element
+ * ref.current?.finishRefresh('success');
+ * ```
+ */
+declare const CarouselSlider: React.ForwardRefExoticComponent<CarouselSliderProps & {
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+} & React.RefAttributes<CarouselSliderElement>>;
+
+declare enum CarouselPageChangedReason {
+    timed = "timed",
+    manual = "manual",
+    controller = "controller"
+}
+declare enum CenterPageEnlargeStrategy {
+    scale = "scale",
+    height = "height",
+    zoom = "zoom"
+}
+declare enum Axis {
+    horizontal = "Axis.horizontal",
+    vertical = "Axis.vertical"
+}
+declare enum Curve {
+    ease = "Curves.ease",
+    easeIn = "Curves.easeIn",
+    easeOut = "Curves.easeOut",
+    easeInOut = "Curves.easeInOut",
+    fastOutSlowIn = "Curves.fastOutSlowIn",
+    linear = "Curves.linear"
+}
+
+export { Axis, CarouselPageChangedReason, CarouselSlider, type CarouselSliderElement, CenterPageEnlargeStrategy, Curve };