如何在Builder.io的Qwik项目中正确使用SwiperJS？

问题根源 #

你当前代码直接在组件函数内初始化Swiper，此时组件DOM还未完成渲染，Swiper找不到目标.swiper元素，无法绑定轮播逻辑；同时全局类选择器也容易和页面其他组件产生冲突。

修复步骤 #

1. 引入Qwik DOM钩子：用useRef$获取当前组件的Swiper容器元素，用useVisibleTask$在DOM渲染并可见后执行初始化逻辑。
2. 替换全局选择器为Ref引用：确保Swiper只针对当前组件的容器实例，避免冲突。
3. 在正确时机初始化：useVisibleTask$会在组件DOM挂载完成后触发，此时能正确获取到DOM元素完成Swiper初始化。
4. 清理实例防泄漏：在组件销毁时销毁Swiper实例，避免内存泄漏。

修复后的代码 #

import { component$, useRef$, useVisibleTask$ } from '@builder.io/qwik'
import Swiper from 'swiper'
import 'swiper/css'
import 'swiper/css/pagination'
import 'swiper/css/navigation'
import 'swiper/css/scrollbar'

const Testimonials = component$(({ section }) => {
  // 创建Ref关联Swiper容器
  const swiperRef = useRef$<HTMLDivElement>()
  let swiperInstance: Swiper | undefined

  // DOM可见后初始化Swiper
  useVisibleTask$(({ cleanup }) => {
    if (swiperRef.current) {
      swiperInstance = new Swiper(swiperRef.current, {
        direction: 'vertical',
        loop: true,
        pagination: {
          el: '.swiper-pagination',
        },
        navigation: {
          nextEl: '.swiper-button-next',
          prevEl: '.swiper-button-prev',
        },
        scrollbar: {
          el: '.swiper-scrollbar',
        },
      })
    }

    // 组件销毁时清理Swiper实例
    cleanup(() => {
      swiperInstance?.destroy()
    })
  })

  return (
    <div className="testimonials py-20 mx-4 sm:mx-16 md:mx-8 lg:mx-10 xl:mx-20 ">
      <div className="max-w-screen-xl select-none cursor-grab mx-auto ">
        {/* 通过Ref关联Swiper容器 */}
        <div ref={swiperRef} class="swiper">
          <div class="swiper-wrapper">
            {section.items.map(item => (
              <div class="swiper-slide" key={item.id}>
                <div className="pb-10 rounded text-center bg-gray-50 pt-6">
                  <p className="p-4 pt-2 leading-7 pb-16 italic font-catamaran font-light tracking-wide">
                    {item.summary}
                  </p>
                  <img
                    className='w-24 h-24 rounded-full m-auto -mt-8 border-[5px] border-white border-b-cta-hover border-l-cta-hover'
                    src={item.imageUrl}
                    alt={`${item.title} ${item.subtitle}`}
                  />
                  <div className="font-black text-lg mt-6 text-slate-800">{item.title}</div>
                  <div className="text-sm mt-2 text-slate-600 ">{item.subtitle}</div>
                </div>
              </div>
            ))}
          </div>
          <div class="swiper-pagination"></div>
          <div class="swiper-button-prev"></div>
          <div class="swiper-button-next"></div>
          <div class="swiper-scrollbar"></div>
        </div>
      </div>
    </div>
  )
})

export default Testimonials

额外注意事项 #

• 必须导入Swiper对应模块的CSS（如分页、导航控件样式），否则控件会显示异常。
• 遍历列表时给swiper-slide添加唯一key，符合Qwik渲染优化要求。
• 如需响应式配置，可直接在Swiper参数中设置breakpoints属性，或在useVisibleTask$中监听窗口resize事件调整配置。

内容的提问来源于stack exchange，提问作者Big boy