preload-screen

一个极简单易用的 页面加载动画插件 ，在 React / Vue 原生项目中使用。
支持 自动模式 （在 监听该元素内是否挂载子元素后 自动消失）和 手动模式 （自行控制消失时机）。

✨ 特性

• 🚀 零依赖，直接引入即可使用
• 🎨 可自定义文案、颜色
• ⚙️ 可配置动画类型
• ⚡ 支持自动模式 / 手动模式
• 🛡️ 最少显示时间，避免闪屏
• 🔧 可作为独立插件封装发布

📦 安装

npm install preload-screen --save

或

yarn add preload-screen

或

pnpm add preload-screen

🔨 使用方法

1. 在入口文件中引入插件

  // main.ts / main.js / main.tsx / main.jsx

  import { initPreloadScreen } from "preload-screen"; 
  const loader = initPreloadScreen({
    mode: "auto",
    minShow: 300,
    fadeOut: 500,
    text: "Loading...",
    color: "#1890ff",
    animeStyle: '3dBox',
    debug: true,
  })

引入后会自动插入一个全屏 Loading 动画。

---

2. 模式选择

手动模式 (推荐)

适合 React / Vue 等框架，需要等待应用挂载完成后再移除 Loading。

import { initPreloadScreen } from "preload-screen"; 
const loader = initPreloadScreen({
  // ...配置项...
});

// 手动关闭加载方式
loader.hide();

在应用完成初始化后手动触发：

  // main.ts (React 示例)

  import { StrictMode } from 'react'
  import { createRoot } from 'react-dom/client'
  import './index.css'
  import App from './App.tsx'
  // 以上引入皆为React示例项目，与插件无关

  import { initPreloadScreen } from "preload-screen"; 
  const loader = initPreloadScreen({
    mode: "manual",
    text: "Loading...",
    color: "#1890ff",
  });

  (async function () {
    setTimeout(() => {
      // 手动触发 hide 事件关闭Loading,
      loader.hide();
    }, 5000);
    createRoot(document.getElementById('root')!).render(
      <StrictMode>
        <App />
      </StrictMode>,
    )
  })()

自动模式 (默认)

需传入elId 配置项，即承载框架渲染内容的根节点元素的 id 值，通过 mutationObserver 监听该元素内是否挂载子元素，当监听到有实际内容后自动关闭 Loading。

若不传入elId 时，首先会检测是否存在 #root(React) #app(Vue),若不存在，将会使用 document.body 监听。

// main.ts (React 示例)
import "preload-screen";

⚙️ 配置项

参数	类型	默认值	说明
elId	string	-	承载框架渲染内容的根节点元素的 id 值
mode	string	auto	模式选择，可选值：auto / manual
text	string	Loading...	Loading 文案
color	string	#1890ff	环形加载动画的边框颜色
minShow	number	300	最少显示时间 (ms)，避免闪屏
fadeOut	number	500	Loading 消失动画时长 (ms)
animeStyle	string	spin	动画样式，可选值 spin / 3dBox / petal
maxAttempts	number	100	查找根节点元素时最大尝试次数，避免死循环
checkInterval	number	50	尝试查找根节点元素时间隔时间 (ms)
logo	string	-	logo 图片路径
logoConfig	object 或 string	-	下方 logo 配置项

---

logo 配置项：

logoConfig 配置项	类型	默认值	说明
logoConfig	string	-	可直接以logoConfig为属性，传入图片路径
width	number	100	图片宽度
height	number	100	图片高度
rounded	number	0	图片圆角
progress	object	-	进度条配置项
progress.mode	string	default	进度条模式，可选值 bar / rainbow
progress.stroke	number	4	进度条宽度
progress.color	string	#1890ff	进度条颜色
progress.isShowText	boolean	false	是否展示进度数值
progress.textColor	string	#666	进度数值颜色
progress.textSize	number	14	进度数值文字大小

---

🖐 手动 API

即使在 manual 模式之外，也可以随时手动触发：

  // 1.使用window上挂载的关闭事件，立即移除预加载动画
  window.dispatchEvent(new CustomEvent('app-ready'));
  window.preloadHide();

📄 License

MIT © 2025

v1.2.1 - 2025-09-28 更新日志

✨ Added 新增功能

新增 logoConfig 配置项，展示为：图片+进度条样式
可传入图片路径，以自己项目 logo 为 Loading 文案 支持配置图片、图片大小、是否圆角、进度条展示、进度条颜色、进度数值展示、进度数值颜色、进度数值字体大小

---

新增 progress.mode 配置项，展示为：进度条样式 可选择 default / bar / rainbow 三种模式，默认为 default