spriteparticle.js 模块使用说明

马黑黑 · 发表于 2025-6-12 21:15

请马上登录，朋友们都在花潮里等着你哦：）

您需要登录才可以下载或查看，没有账号？立即注册

x

本帖最后由马黑黑于 2025-6-12 21:16 编辑

spriteparticle.js 是使用 ES6 标准、基于 ThreeJS 核心库编写的JS模块，专为音画帖打造粒子系统及提供音、视频联动管控功能，模块内部使用 Sprite 精灵制作粒子、Sphere 球形几何体制作播放器。以下是使用说明：

一、导入 spriteparticle 模块

分两种情况进行导入：

其一：简单导入，适用于帖子使用模块默认配置和自定义配置——

import { LZ } from 'https://638183.freep.cn/638183/web/ku/spriteparticle.js';

可以将 spriteparticle.js 保存为自己的文档（存为本地测试需要开启虚拟服务器且文档放在合法目录内），若此，导入地址跟着改变即可。

其二：全部导入，适用于在帖子中需要绘制其它 ThreeJS 图像的情形——

import { THREE, scene, camera, renderer, clock, LZ } from 'https://638183.freep.cn/638183/web/ku/spriteparticle.js';

scene 是场景，camera 是相机，renderer 是渲染器，clock 是时钟。这些都是绘制 ThreeJS 图像的基本变量，是绘制3d图像不可或缺的。自行绘制的 ThreeJS 图像可以自行设置动画和动画管理机制。

二、使用模块

导入的 { LZ } 是一个函数，它至少需要一个参数，就是帖子的id标识，即装载粒子和播放器的父元素。假设父元素 id="papa"，那么——

LZ(papa);

注意 papa 标识不要引号。这将在 id="papa" 的标签里运行精灵粒子系统，以默认的配置方式。自然，总要有自己的配置，若此，LZ() 函数需要第二个参数，即配置参数，可以命名一个变量用以装载配置：

// config 变量 ：配置精灵和播放器
const config = {
	// 1. 精灵
	sprite: {
		number: 200, // 粒子数量（正整数）
		scale: 0.4, // 原始缩放（正数浮点数）
		// 纹理贴图（要求是同源或支持跨域数据解析的图片）
		pic: 'https://638183.freep.cn/638183/small/hdxk.png',
		rotation: [30, 30, 30] // 精灵组在xyz轴上自转速度的除数（大于0的正整数）
	},
	// 2. 播放器
	mesh: {
		// 纹理贴图（要求是同源或支持跨域数据解析的图片）
		pic: 'https://638183.freep.cn/638183/small/2025/fl101.png', 
		color: 0x00ffee, // 叠加到贴图颜色的颜色
		transparent: true, // 开启透明（false为不开启）
		position: [0, 0, 0], // 播放器位置（正负浮点数）
		// 初始自转xyz轴上的角度（正负浮点数或 Math.PI / N 的表达式）
		rotate: [0, 0, 0],
		// 播放器在xyz轴上旋转速度的乘数（正负浮点数）
		rotation: [0.5, -0.5, 0]
	}
};
// 加入第二个参数
LZ(papa, config);

如果需要在帖子中绘制另外的 ThreeJS 图形，在运行 LZ() 函数后，使用标准的 ThreeJS 代码规范即可实现，例如，绘制一个矩形——

const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshNormalMaterial();
const cube = new THREE.Mesh(geometry, material);
cube.rotateX(Math.PI / 4);
cube.position.set(0, -2.5, 2);
scene.add(cube);

三、其它配置

模块提供有全屏切换功能，通过按钮操作，按钮 id="btnFs"，自设有基本样式，但需要在帖子CSS代码至少自定义位置、文本颜色等，可以这样——

/* 全屏按钮CSS代码 */
#btnFs { left: 48%; bottom: 20px; color: #eee; }

此外，模块支持对 video 视频的管理，视频标签需要放在帖子内。

而最重要的是 audio 音频，没有它，精灵粒子系统将不会运行。音频标签可以放在帖子内外，模块只认第一个出现的 audio 标签。

【附】应用代码示例

<style>
	#tz { margin: 30px 0; left: 50%; transform: translateX(-50%);  width: clamp(600px, 90vw, 1400px); height: auto; aspect-ratio: 16/9; background: url('https://638183.freep.cn/638183/t24/w4/hero.webp') no-repeat center/cover; box-shadow: 2px 2px 8px #000; display: grid; place-items: center; z-index: 1; position: relative; }
	#btnFs { bottom: 20px; color: #eee; }
	#tz > canvas { position: absolute; left: 0; top: 0; right: 0; bottom: 0; display: block; }
</style>

<div id="tz"></div>
<audio id="aud" src="https://music.163.com/song/media/outer/url?id=36586597" autoplay loop></audio>

<script type="module">
	import { THREE, scene, camera, renderer, clock, LZ } from 'https://638183.freep.cn/638183/web/ku/spriteparticle.js';

	const config = {
		sprite: {
			number: 200,
			scale: 0.4,
			pic: 'https://638183.freep.cn/638183/small/hdxk.png',
			rotation: [30, 30, 30]
		},
		mesh: {
			pic: 'https://638183.freep.cn/638183/small/2025/fl101.png',
			color: 0x00ffee,
			transparent: true,
			position: [0, 2, 0],
			rotate: [0, 0, -Math.PI / 2],
			rotation: [0.5, -0.5, 0]
		}
	};

	LZ(tz, config);

	const geometry = new THREE.BoxGeometry();
	const material = new THREE.MeshNormalMaterial();
	const cube = new THREE.Mesh(geometry, material);
	cube.rotateX(Math.PI / 4);
	cube.position.set(0, -2.5, 2.05);
	scene.add(cube);
</script>