在Next.js项目中正确使用ldrs加载动画组件

2025-07-05 10:09:59作者：齐添朝

Modern, tree-shakeable loader & spinner web components. Made with CSS, HTML and SVG. https://uiball.com/ldrs

项目地址：https://gitcode.com/gh_mirrors/ld/ldrs

ldrs是一个基于Web Components的轻量级加载动画库，提供了多种精美的加载动画效果。然而，许多开发者在Next.js项目中集成ldrs时遇到了ReferenceError: HTMLElement is not defined的错误。本文将深入分析问题原因并提供解决方案。

问题根源分析

这个错误通常发生在Next.js的服务器端渲染(SSR)环境中。ldrs库基于Web Components技术构建，而Web Components依赖于浏览器环境中的HTMLElement类。在服务器端渲染时，Node.js环境中没有HTMLElement的定义，因此会抛出这个错误。

解决方案

方案一：动态导入组件

最推荐的解决方案是使用Next.js的动态导入功能，确保组件只在客户端加载：

import { useEffect } from 'react'

export default function Loader() {
  useEffect(() => {
    async function getLoader() {
      const { spiral } = await import('ldrs')
      spiral.register()
    }
    getLoader()
  }, [])
  return <l-spiral color="coral"></l-spiral>
}

这种方法利用了React的useEffect钩子和动态import()，确保Web Components的注册只在客户端进行。

方案二：使用'use client'指令

如果你使用的是Next.js 13+的应用路由(App Router)，可以在组件顶部添加'use client'指令：

'use client'
import { useEffect } from 'react'
import { lineSpinner } from 'ldrs'

const Loader = () => {
  useEffect(() => {
    lineSpinner.register()
  }, [])

  return <l-line-spinner size="50" stroke="3" speed="1" color="#DDDED8"></l-line-spinner>
}

方案三：全局注册组件

对于频繁使用的加载动画，可以在布局文件中全局注册：

// app/layout.js
import { lineSpinner } from 'ldrs'

lineSpinner.register()

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
      </body>
    </html>
  )
}

Web Components在Next.js中的特殊考量

ldrs选择使用Web Components实现有其优势：

框架无关性：可以在React、Vue、Svelte等多种前端框架中使用
封装性：样式和行为完全封装在组件内部
标准化：遵循W3C标准，具有更好的长期兼容性

然而，这也带来了SSR环境下的兼容性问题。理解这一点有助于开发者更好地在各种场景下使用ldrs库。

最佳实践建议

对于简单的项目，推荐使用动态导入方案
对于复杂项目，考虑在布局文件中统一注册常用加载器
如果只需要少量加载动画，也可以直接复制HTML和CSS代码，避免引入整个库
关注ldrs的未来更新，官方可能会提供更便捷的React封装组件

通过以上方法，开发者可以顺利在Next.js项目中使用ldrs的各种精美加载动画，同时避免SSR环境下的兼容性问题。

Modern, tree-shakeable loader & spinner web components. Made with CSS, HTML and SVG. https://uiball.com/ldrs

项目地址：https://gitcode.com/gh_mirrors/ld/ldrs

登录后查看全文

项目优选

收起

deepin linux kernel

OpenHarmony documentation | OpenHarmony开发者文档

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解

flutter_flutter

喝着茶写代码！最易用的自托管一站式代码托管平台，包含Git托管，代码审查，团队协作，软件包和CI/CD。

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

无需学习 Kubernetes 的容器平台，在 Kubernetes 上构建、部署、组装和管理应用，无需 K8s 专业知识，全流程图形化管理

🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端