微信小程序3D项目创建

微信小程序 3D：原生框架与 H5 套壳的深度解析

在微信小程序生态中，开发者面临着两种主流的 3D 实现路径：基于原生框架的 XR-Frame 与基于 H5 技术栈的套壳方案。理解两者的核心差异，对于选择最适合项目需求的技术方案至关重要。

原生 XR-Frame：性能与深度的融合

微信小程序官方推出的 XR-Frame，是专为小程序环境量身打造的 XR/3D 应用解决方案。它并非简单的 H5 封装，而是基于混合方案实现，旨在提供接近原生应用的性能体验。XR-Frame 的优势在于：

性能逼近原生：通过底层优化，XR-Frame 能够更高效地利用设备硬件资源，减少渲染延迟，提供流畅的 3D 交互体验。这对于对性能要求较高的复杂 3D 场景尤为关键。
深度集成：XR-Frame 与微信小程序生态系统深度融合，能够无缝调用小程序 API，实现更丰富的功能，例如与微信支付、用户数据、设备传感器等进行高效互动。
易用性与扩展性：XR-Frame 遵循小程序开发标准，降低了开发者的学习门槛。同时，其模块化的设计也提供了良好的扩展性，方便开发者根据需求定制功能。
官方支持与维护：作为官方解决方案，XR-Frame 享有持续的更新和维护，能够及时适配微信小程序的新特性和底层优化，确保技术的稳定性和前瞻性。

H5 3D 框架套壳：灵活性与兼容性的权衡

H5 3D 框架套壳方案，顾名思义，是将成熟的 Web 3D 库（如 Three.js、Babylon.js 等）打包进小程序 WebView 中运行。这种方案的特点在于：

开发灵活性：开发者可以沿用 Web 前端的开发习惯和工具链，将现有的 Web 3D 项目快速迁移到小程序中，降低了跨平台开发的成本。
丰富的生态：Web 3D 社区拥有庞大且活跃的生态系统，提供了海量的模型、材质、工具和教程，为开发者提供了丰富的资源支持。
跨平台兼容性：一套代码可以在 Web、H5 小程序等多个平台运行，提高了代码复用率。

然而，H5 套壳方案也存在一些局限性：

性能瓶颈：H5 3D 内容运行在 WebView 中，性能受限于 WebView 的渲染能力和 JavaScript 的执行效率，通常难以达到原生级别的流畅度。对于复杂场景，可能会出现卡顿或帧率下降。
集成度受限：与小程序原生 API 的交互需要通过 JSBridge 进行，这可能引入额外的通信开销和复杂性，限制了某些高级功能的实现。
包体大小：引入完整的 Web 3D 库可能会显著增加小程序包体大小，影响用户下载和启动体验。

如何选择？

追求极致性能与深度集成：如果你的小程序 3D 项目对性能要求极高，需要与小程序原生功能紧密结合，或者希望利用微信的 XR 能力（如 AR），那么 XR-Frame 无疑是更优的选择。
注重开发效率与 Web 生态：如果你的团队更熟悉 Web 3D 开发，拥有大量现成的 Web 3D 资产，或者项目对性能要求相对宽松，H5 3D 框架套壳方案能让你更快地将内容呈现在小程序中。

总而言之，XR-Frame 代表了微信小程序 3D 发展的未来方向，提供了更深度的集成和更优异的性能；而 H5 套壳方案则以其灵活性和兼容性，为快速原型开发和 Web 内容迁移提供了便利。开发者应根据项目的具体需求、性能目标和团队技术栈，做出明智的抉择。

微信小程序 3D 项目创建

本章将引导你从零开始，搭建一个基础的 3D 场景。

第一幕：微信小程序创建

首先，确保你的开发环境已准备就绪。

下载与安装：前往微信小程序官方网站，下载并安装最新版的微信开发者工具。它是你探索小程序世界的罗盘。
新建项目：启动开发者工具，选择“小程序”项目类型。填写项目名称，选择一个合适的本地存储路径。在模板选择上，为了保持纯粹，我们选择“JavaScript 基础模板”或“不使用模板”，以便从最干净的环境开始构建。

项目配置

为 XR-Frame 的集成做准备，我们需要对项目进行一些必要的配置。

project.config.json 配置：

在项目的根目录下找到 project.config.json 文件。为了让 XR-Frame 的资源加载更加顺畅，我们需要在 setting 字段中添加或修改以下配置：
1
2
3
4
5
6
7
8
{
// ... existing code ...
"setting": {
// ... existing code ...
"ignoreDevUnusedFiles": false,
"ignoreUploadUnusedFiles": false
}
}
这两行配置确保了开发者工具在开发和上传时不会忽略 XR-Frame 可能动态加载的资源文件。
app.json 配置：

app.json 是小程序的全局配置文件。为了启用 XR-Frame 的按需加载能力，我们需要在其中加入 lazyCodeLoading 配置。这能有效减小小程序首次启动的开销。
1
2
3
4
{
// ... existing code ...
"lazyCodeLoading": "requiredComponents"
}

XR-Frame 组件的创建

现在，是时候将 XR-Frame 的核心组件引入我们的舞台了。我们将创建一个自定义组件来承载 3D 场景。

创建组件目录：

在 components 目录下（如果不存在，请创建），新建一个名为 xr-scene-component 的文件夹。在该文件夹内，创建三个文件：xr-scene-component.json、xr-scene-component.wxml 和 xr-scene-component.js。
xr-scene-component.json：组件的身份证明：

在这个文件中，我们声明这是一个使用 XR-Frame 渲染器的组件。
1
2
3
4
5
{
"component": true,
"usingComponents": {},
"renderer": "xr-frame"
}
xr-scene-component.wxml：场景的骨架：

在这里，我们定义 XR-Frame 场景的根元素 <xr-scene>，并加入一个相机 <xr-camera>，它是我们观察 3D 世界的眼睛。
1
2
3
4
5
6
7
8
9
10
<xr-scene>
<xr-camera
id="camera"
node-id="camera"
position="0 1.6 3"
target="0 0 0"
background="0.2 0.4 0.6 1"
camera-orbit-control
></xr-camera>
</xr-scene>
- position：相机在 3D 空间中的位置。
- target：相机看向的目标点。
- background：场景的背景颜色，这里设置为一种宁静的蓝色调。
- camera-orbit-control：一个便捷的属性，允许我们通过手势自由旋转和缩放相机，便于调试和预览。
xr-scene-component.js：组件的生命周期：

虽然目前我们不需要复杂的逻辑，但组件的 JS 文件是其生命周期的管理者。
1
2
3
4
5
Component({
properties: {},
data: {},
methods: {}
})

场景呈现与球形 Mesh 的显示

现在，我们将这个承载 3D 场景的组件放置到小程序的页面中，并让一个红色的球体在其中闪耀。

页面引入组件：

打开 pages/index/index.json（或其他你希望展示 3D 场景的页面 json 文件），引入我们刚刚创建的 XR-Frame 组件。
1
2
3
4
5
{
"usingComponents": {
"xr-scene-component": "/components/xr-scene-component/xr-scene-component"
}
}
页面布局：

在 pages/index/index.wxml 中，添加 <xr-scene-component> 标签，并为其设置合适的尺寸。
1
2
3
<view class="container">
<xr-scene-component width="750rpx" height="500rpx"></xr-scene-component>
</view>
为了让场景有足够的显示区域，你可能还需要在 pages/index/index.wxss 中为 container 设置样式。

点亮场景：光源的引入：

3D 世界需要光才能被看见。在 xr-scene-component.wxml 的 <xr-scene> 内部，添加光源。

<xr-scene>
  <xr-camera
    id="camera"
    node-id="camera"
    position="0 1.6 3"
    target="0 0 0"
    background="0.2 0.4 0.6 1"
    camera-orbit-control
  ></xr-camera>

  <!-- 环境光：为场景提供基础照明 -->
  <xr-light type="ambient" color="1 1 1" intensity="0.5"></xr-light>
  <!-- 主平行光：模拟太阳光，提供方向性照明和阴影 -->
  <xr-light type="directional" color="1 1 1" intensity="1" direction="1 -1 1"></xr-light>
</xr-scene>

ambient 环境光：均匀照亮整个场景，使所有物体可见。
directional 平行光：模拟远距离光源（如太阳），具有方向性，常用于产生阴影。

球形 Mesh 的创建：

在光源之后，我们将在场景中放置一个红色的球体。在 xr-scene-component.wxml 的 <xr-scene> 内部，添加以下代码：

<xr-scene>
  <!-- ... existing camera and lights ... -->

  <!-- 一个红色的球体 -->
  <xr-mesh
    node-id="sphere"
    geometry="sphere"
    material="standard"
    uniforms="u_baseColorFactor: 1 0 0 1"
    position="0 0 0"
    scale="0.5 0.5 0.5"
  ></xr-mesh>
</xr-scene>

xr-mesh：XR-Frame 中的 3D 网格对象。
geometry="sphere"：指定使用内置的球体几何体。
material="standard"：使用标准材质，它支持光照和 PBR 效果。
uniforms="u_baseColorFactor: 1 0 0 1"：设置材质的基础颜色为红色（RGBa）。
position：球体在场景中的位置。
scale：球体的大小。

运行与预览

保存所有文件，微信开发者工具会自动编译并刷新。