news/app/components/Carousel.tsx

// 引入 React 核心库
import * as React from "react";

// 引入 Embla Carousel 的自动播放插件
import Autoplay from "embla-carousel-autoplay";

// 引入自定义 UI 组件：Card 和 CardContent（通常用于内容容器）
import { Card, CardContent } from "@/ui/card";

// 引入自定义轮播组件及其子组件和类型定义
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  type CarouselApi, // Embla 轮播实例的类型定义
} from "@/ui/carousel";

// 定义轮播图使用的图片资源路径数组
const imageUrls = [
  "/images/carousel-1.jpg",
  "/images/carousel-2.jpg",
  "/images/carousel-3.jpg",
  "/images/carousel-4.jpg",
  "/images/carousel-5.jpg",
  "/images/carousel-6.jpg",
];

// 定义组件接收的 props 接口，提供类型安全
export interface CarouselDemoProps {
  // 分页指示器位置：'left' 表示左下角，'right' 表示右下角，默认为 'right'
  paginationPosition?: "left" | "right";

  // 分页指示器样式：'dot' 为圆形小点，'bar' 为横向小条，默认为 'dot'
  paginationStyle?: "dot" | "bar";
}

// 导出 CarouselDemo 组件，接收两个可选 props，并设置默认值
export function CarouselDemo({
  paginationPosition = "right", // 默认右下角
  paginationStyle = "dot", // 默认圆形指示器
}: CarouselDemoProps) {
  //  轮播实例的引用 当前激活的幻灯片索引 总共的幻灯片数量 图片总数
  const [api, setApi] = React.useState<CarouselApi>();
  const [current, setCurrent] = React.useState(0);
  const [count, setCount] = React.useState(0);
  const totalSlides = imageUrls.length;

  // 监听 api ，初始化轮播状态并绑定 select 事件 获取幻灯片总数 设置当前选中的 snap 索引 用户手动滑动或自动播放时触发 更新当前激活项
  React.useEffect(() => {
    if (!api) return;
    setCount(api.scrollSnapList().length);
    setCurrent(api.selectedScrollSnap());
    api.on("select", () => {
      setCurrent(api.selectedScrollSnap());
    });
  }, [api]); // 仅当 api 发生变化时重新执行

  // 渲染组件
  return (
    // 外层容器：相对定位，占满父容器宽高
    <div className="relative w-full h-full">
      {/* 轮播主容器 */}
      <Carousel
        opts={{
          loop: true,
        }}
        plugins={[
          Autoplay({
            delay: 3000,
            stopOnInteraction: false,
          }),
        ]}
        setApi={setApi} // 保存
        className="w-full"
      >
        {/* 
        移除默认内边距
        */}
        <CarouselContent className=" w-full -ml-0 h-full">
          {/* 遍历图片数组，为每张图创建一个轮播项 */}
          {imageUrls.map((src, index) => (
            <CarouselItem key={index} className="w-full  pl-0">
              {/* 内部包裹层：无内边距，占满
              移除默认间距 
              自动填充容器，保持比例裁剪*/}
              <div className={`p-0 w-full `}>
                <CardContent className=" p-0 w-full  m-0">
                  <div className="relative w-full aspect-video ">
                    <img
                      src={src}
                      alt={`Slide ${index + 1}`} // 无障碍访问描述
                      className="absolute inset-0 w-full h-full object-fill" // 使用 object-fill 拉伸填充
                      loading="lazy" // 懒加载优化性能
                    />
                  </div>
                </CardContent>
              </div>
            </CarouselItem>
          ))}
        </CarouselContent>

        {/* 上一张按钮（左箭头） */}
        {/* <CarouselPrevious className="absolute left-2 top-1/2 -translate-y-1/2 z-10" /> */}

        {/* 下一张按钮（右箭头） */}
        {/* <CarouselNext className="absolute right-2 top-1/2 -translate-y-1/2 z-10" /> */}
      </Carousel>

      {/* 分页指示器容器：绝对定位在底部 */}
      <div
        className={`absolute bottom-4 ${
          paginationPosition === "left" ? "left-4" : "right-4" // 根据 prop 控制左右位置
        } flex gap-2 z-10`} // 水平排列，间距 0.5rem，置于轮播图上方
      >
        {/* 动态生成指示器按钮 */}
        {Array.from({ length: count }).map((_, index) => (
          <button
            key={index}
            onClick={() => api?.scrollTo(index)} // 点击跳转到对应幻灯片
            className={`transition-colors ${
              // 根据 paginationStyle 决定形状
              paginationStyle === "dot"
                ? "h-2 w-2 rounded-full" // 圆形：宽高相等 + 全圆角
                : "h-1 w-6 rounded" // 块状
            } ${
              index === current
                ? "bg-white" // 当前项为纯白色
                : "bg-white/50" // 非当前项为半透明白色
            }`}
            aria-label={`Go to slide ${index + 1}`} // 无障碍支持
          />
        ))}
      </div>
    </div>
  );
}