tQuery 类名与数据操作：像 jQuery 一样管理 3D 对象-平芜编程栈

tQuery 类名与数据操作：像 jQuery 一样管理 3D 对象

【免费下载链接】tqueryextension system for three.js项目地址: https://gitcode.com/gh_mirrors/tq/tquery

如果你写过前端，一定对 jQuery 的.addClass()、.data()、链式调用念念不忘。tQuery正是把这种"以对象为中心的类名与数据操作"体验带进了three.js 世界：作为一套面向 three.js 的 extension system（扩展系统），它让你像操作 DOM 一样，用选择器、类名、数据挂载来管理 3D 场景中的每一个对象。无论你是 3D 新手还是老手，这篇文章都会带你快速掌握 tQuery 的类名与数据操作技巧。

一、tQuery 是什么？一个"jQuery 化"的 three.js 扩展系统

tQuery 的目标很简单：把 three.js 原本繁琐的面向对象调用，包装成接近 jQuery 的简洁 API。它保留了 three.js 的全部能力，同时提供了：

类似 jQuery 的选择器语法，例如.box、#player、[name=xxx]
类似 jQuery 的类名操作：addClass、removeClass、hasClass
类似 jQuery 的数据操作：data()、removeData()
可链式调用的方法，一行代码完成多个动作

它的核心实现分散在 tquery.core.js、tquery.node.js 和 tquery.object3d.js 中，理解这几个文件就能看懂整个设计思路。

二、快速上手：用选择器找到你的 3D 对象

在 tQuery 中，查找对象的方式和 jQuery 找 DOM 几乎一模一样。你可以在创建对象时给它打上标记，然后随时用选择器捞回来：

// 创建并标记对象 var cube = tQuery.createCube().addClass('enemy').addTo(world); var player = tQuery.createSphere().attr('name', 'hero').addTo(world); // 像 jQuery 一样选择 tQuery('.enemy'); // 按类名选择 tQuery('#player'); // 按 id 选择 tQuery('[name=hero]'); // 按属性选择

这套选择器逻辑位于 tquery.object3d.js 的_select与_selectItemMatch中，支持类名、id、[name=xxx]等多种匹配方式，还能用空格组合多级父子选择。

三、类名操作：addClass / removeClass / hasClass

这是 tQuery 最"jQuery 味"的功能之一。你可以给 3D 对象动态添加、移除、判断类名，非常适合做游戏中的状态管理：

var enemy = tQuery.createCube().addClass('enemy').addTo(world); // 判断是否具有某个类 if (enemy.hasClass('enemy')) { /* 是敌人 */ } // 动态切换状态 enemy.addClass('frozen'); // 冻结 enemy.removeClass('enemy'); // 不再是敌人

三个方法的实现见 tquery.object3d.js，底层用正则匹配类名串，逻辑清晰、开销极小。

四、数据操作：data() 与 removeData()

游戏开发中，经常需要给 3D 对象挂载血量、分数、碰撞状态等自定义数据。tQuery 提供了和 jQuery 完全同名的data()/removeData()：

var cube = tQuery.createCube().addTo(world); // 设置数据（默认要求键不存在，防止覆盖） cube.data('hp', 100); cube.data('score', 0, false); // 第三个参数 false 允许覆盖 // 读取数据 console.log(cube.data('hp')); // 100 // 判断数据是否存在、删除数据 tQuery.hasData(cube.get(0), 'hp'); // true cube.removeData('hp');

底层实现见 tquery.node.js 和 tquery.core.js：数据统一存放在对象的_tqData哈希表里，天然避免污染 three.js 原生对象。

五、属性操作：attr / name / id 的 Getter 与 Setter

除了类名和数据，tQuery 还把常用属性封装成了即取即用的方法：

var mesh = tQuery.createTorus().addTo(world); // 批量设置属性（可链式） mesh.attr({ visible: true, castShadow: true }); // 单独读写 mesh.name('bigTorus'); // 设置名字 mesh.name(); // 读取名字 mesh.id('torus01'); // 设置 id // 甚至支持 position / rotation / scale 的分量读写 mesh.positionX(2); // 等价于 position.x = 2

attr()的通用 getter/setter 机制定义在 tquery.core.js，配合 tquery.object3d.js 中声明的属性白名单，扩展新属性非常方便。

六、链式调用：一行代码构建完整场景

tQuery 的方法几乎都返回自身，支持无限链式调用。把上面的技巧串起来，你会发现搭建和管理 3D 场景从未如此流畅：

tQuery.createCube() .addClass('enemy') .attr({ visible: true, castShadow: true }) .data('hp', 100) .addTo(world) .positionX(5);

七、更进一步：用数据驱动游戏逻辑

类名与数据操作最有价值的场景，是让"状态"与"表现"解耦。比如敌人管理：

// 每帧遍历所有 enemy，按 hp 数据决定是否移除 tQuery('.enemy').each(function(obj3d){ var tObj = tQuery(obj3d); if (tObj.data('hp') <= 0) { tObj.detach(); // 移出场景 } });

结合 tQuery 的插件体系（如 tquery.keyboard.js、tquery.tween.js），你几乎不需要再手写繁琐的 three.js 原生代码。