React项目集成OwlCarousel报错：Cannot read properties of undefined(reading 'fn')

问题描述 #

在React项目中集成OwlCarousel时遇到以下错误：

"Cannot read properties of undefined (reading 'fn')"

相关代码如下：

App.js #

import React from "react";
import OwlCarousel from "./OwlCarousel";

const App = () => {
  return (
    <div className="App">
      <OwlCarousel />
    </div>
  );
};

export default App;

OwlCarousel.js #

import React, { useEffect } from "react";
import "owl.carousel/dist/assets/owl.carousel.css";
import "owl.carousel/dist/assets/owl.theme.default.css";
import $ from "jquery";
import "owl.carousel";

const OwlCarousel = () => {
  useEffect(() => {
    $(".owl-carousel").owlCarousel({
      items: 3,
      loop: true,
      margin: 10,
      autoplay: true,
      autoplayTimeout: 2000,
      autoplayHoverPause: true
    });
  }, []);

  return (
    <div className="owl-carousel">
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 1" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 2" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 3" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 4" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 5" />
      </div>
    </div>
  );
};

export default OwlCarousel;

错误原因 #

这个错误的核心是OwlCarousel依赖全局的jQuery/$对象，但在ES模块环境中，直接导入的jquery不会自动挂载到全局window对象上，导致OwlCarousel无法找到$.fn来注册自身的方法，最终调用owlCarousel()时触发undefined错误。

解决方案 #

方案1：修正导入方式并使用React Ref获取DOM元素 #

修改OwlCarousel.js，确保OwlCarousel能正确依附于导入的jQuery，同时用useRef替代类名选择器，更符合React的DOM操作规范：

import React, { useEffect, useRef } from "react";
import "owl.carousel/dist/assets/owl.carousel.css";
import "owl.carousel/dist/assets/owl.theme.default.css";
import $ from "jquery";
// 导入OwlCarousel的具体dist文件，确保它挂载到导入的jQuery上
import "owl.carousel/dist/owl.carousel";

const OwlCarousel = () => {
  const carouselRef = useRef(null);

  useEffect(() => {
    const $carousel = $(carouselRef.current);
    // 初始化轮播
    $carousel.owlCarousel({
      items: 3,
      loop: true,
      margin: 10,
      autoplay: true,
      autoplayTimeout: 2000,
      autoplayHoverPause: true
    });

    // 组件卸载时清理轮播实例，避免内存泄漏
    return () => {
      $carousel.trigger("destroy.owl.carousel");
    };
  }, []);

  return (
    <div ref={carouselRef} className="owl-carousel">
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 1" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 2" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 3" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 4" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 5" />
      </div>
    </div>
  );
};

export default OwlCarousel;

方案2：使用React封装的OwlCarousel组件 #

如果不想手动处理jQuery和原生OwlCarousel的兼容问题，可以使用专门为React封装的组件，安装后直接使用React组件语法即可：

1. 安装依赖：

npm install react-owl-carousel

2. 使用示例：

import React from "react";
import OwlCarousel from "react-owl-carousel";
import "owl.carousel/dist/assets/owl.carousel.css";
import "owl.carousel/dist/assets/owl.theme.default.css";

const MyCarousel = () => {
  return (
    <OwlCarousel
      items={3}
      loop={true}
      margin={10}
      autoplay={true}
      autoplayTimeout={2000}
      autoplayHoverPause={true}
    >
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 1" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 2" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 3" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 4" />
      </div>
      <div className="item">
        <img src="https://via.placeholder.com/200" alt="Item 5" />
      </div>
    </OwlCarousel>
  );
};

export default MyCarousel;

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