轮播图核心在于结构可控、切换可编程、样式可复用；需用显式语义化html结构（如.carousel/.carousel-track/figure）、transform: translatex()替代left/margin实现gpu加速平滑切换，统一索引逻辑管理自动与手动交互，并兼容pointer/touch事件确保移动端拖拽准确响应。

轮播图不是靠写一堆 <img> 标签堆出来的，核心在于结构可控、切换可编程、样式可复用——否则改个动画时长都得重写 JS。

轮播图的 HTML 结构必须支持 JS 动态控制

很多人一上来就写 <div class="carousel"> <img><img><img> </div>，结果发现 JS 想定位当前项、计算索引、预加载下一张时全靠 querySelectorAll('img') 硬数，极易出错。正确结构要显式标记“容器”“列表”“单个幻灯片”：

• <div class="carousel"> 是外层容器，只管尺寸和溢出隐藏 <li><code><div class="carousel-track"> 是滑动轨道，<code>display: flex 或 position: relative，所有 <figure></figure> 或 <li> 作为子项水平排列
• 每张图用 <figure></figure> 包裹，避免语义丢失；不要直接把 <img> 塞进 <div> <p>这样 JS 才能安全调用 <code>track.children[index] 或 track.querySelectorAll('figure')，不依赖 class 名或 DOM 层级变化。

  用 CSS transform 实现切换，别碰 left/top 或 margin

  用 left 或 margin-left 移动轮播项会导致强制重排（reflow），动画卡顿，且无法利用 GPU 加速。必须用 transform: translateX()：

  • 每个 <figure></figure> 默认 transform: translateX(100%)（即右移一屏），当前项设为 translateX(0)，上一张为 translateX(-100%)
  • 切换时只更新 carousel-track 的 transform，或给每个 <figure></figure> 单独加 class 控制位移（更利于 CSS 过渡）
  • 务必加上 transition: transform 0.3s ease-in-out，且只对 transform 设过渡，别写 all 0.3s

  否则 Chrome DevTools 的 Rendering 面板里会看到频繁的 Layout 和 Paint，尤其在低端设备上明显掉帧。

  自动播放 + 手动切换必须共用同一套索引逻辑

  常见错误是：自动播放用 setInterval 改 currentIndex，点击按钮又单独写一套 goTo(index)，两套逻辑不同步，导致点一下跳两张、暂停后继续播错图。

  

  Doc To HTML

  使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。

  下载
  • 统一维护一个 currentIndex 变量，所有操作（自动、点箭头、点指示器、键盘左右键）都调用同一个 goTo(newIndex) 函数
  • goTo() 内部负责边界处理（如循环播放时 newIndex = (newIndex + count) % count）、DOM 更新（添加/移除 active class）、触发 transform 变更
  • 自动播放用 setTimeout 而非 setInterval，每次切换完成后才设下一次定时器，避免快速点击导致定时器堆积

  否则用户连点三次右箭头，后台可能已触发五次 setInterval 回调，最终停在完全不可预测的位置。

  移动端触摸拖拽不能只靠 mouse 事件

  只监听 mousedown/mousemove 在 iPhone / Android 上根本不会触发。必须同时支持 pointer 和 touch 事件：

  • 用 pointerdown 替代 mousedown，它兼容鼠标、触屏、笔输入
  • 记录起始 clientX，在 pointermove 中计算偏移，动态更新 transform: translateX() 实现拖拽感
  • 在 pointerup 后判断拖拽距离：若 Math.abs(deltaX) > 50px，则执行切换；否则回弹到原位置（用 transition + transform）
  • 记得加 touch-action: pan-y 到轮播容器，防止竖向滚动被禁用

  否则 iOS 用户一划就触发页面整体滚动，轮播图纹丝不动，还以为功能坏了。

  轮播图最难的部分从来不是“怎么让它动起来”，而是“怎么让它在任意时刻被中断、跳转、缩放、切页后仍保持状态一致”。结构、索引、事件三者耦合越紧，后期加需求（比如懒加载、视频暂停、无障碍焦点管理）就越容易崩。