Creator 2.x 升级 3.x 基础 API 差异总结

时间：2023-01-11 17:15:06

上一篇我们介绍了 Cocos Creator 2.x 项目升级 3.x 的大流程。

但最后一步，还需要手动将之前 2.x 写的函数注释一处处的放开。

并将 2.x 的代码写法改成 3.x 的，下面我们就来看一下有那些差异。

1. 模块引入

在 Creator 3.x 中废弃了 cc.Node、cc.Sprite 这种全局形式的 API 调用。

取而代之的是，先要在脚本顶部 import 模块，代码如下：

//从 cc 模块中解构出 Node、Sprite 变量
import { Node, Sprite } from 'cc'

好在 VSCode 编辑器，它会自动帮助我们添加 import 模块。
Creator 2.x 升级 3.x 基础 API 差异总结

但你需要先在 3.x 引擎主菜单 开发者→Export.d.ts 安装 VSCode 提示文件，看下图：

Creator 2.x 升级 3.x 基础 API 差异总结

2. Node 基础属性变化

Creator 3.x 中 Node 的属性变的极其的简洁了，只剩下 position、rotation、scale 这三个属性被保留。

Creator 2.x 升级 3.x 基础 API 差异总结

而且它们都变成了 Vec3 类型，看下面使用方法。

设置节点位置

//Creator 2.x
this.node.position = v2(100, 100)
this.node.x = 100;  //3.x中不可用
this.node.y = 100;  //3.x中不可用

//Creator 3.x 中不能使用x、y、z分量设置节点位置
//需要使用 position 属性或 setPosition 方法
this.node.position = v3(100, 100, 100);
//注意需要同时设置 xyz 三个分量
this.node.setPosition(100, 100, 100);

设置节点缩放

//Creator 2.x
this.node.scale = 1.5;

//Creator 3.x 
//注意 scale 不在是一个 number 而是 Vec3
this.node.scale = v3(1.5, 1.5, 1.5);
//注意 需要同时设置 xyz 三个分量
this.node.setScale(1,1,1);

节点在二维上的旋转

//Creator 2.x rotation 属性在 2.3.x 之后是使用 angle 属性
this.node.angle = 1.5;

//Creator 3.x
//节点的 rotation 属性其实是一个 Quat 类型
//2D节点在属性检查器中的 rotation 
//对应的是节点的 angle 属性
this.node.angle = 10
//也可以使用 eulerAngles 来设置，注意它是设置的Z轴的旋转
this.node.eulerAngels = v3(0, 0, 10);

3. 节点颜色与透明

我们在 3.x 场景中添加一个 2D 精灵，你可以看到，节点的颜色与透明，已经分离到别的组件上了。

Creator 2.x 升级 3.x 基础 API 差异总结

  1. opacity 属性移到 cc.UIOpacity 组件
  2. color 属性移到 cc.Sprite 组件
  3. size、anchor point 属性移到 cc.UITransform 组件

Creator 2.x 升级 3.x 基础 API 差异总结

因此之前的 node.opacity、node.scale、node.color、node.width，这些接口都不能使用了，取而代之的是下面这些样的接口方法。

设置节点透明度

//Creator 2.x
this.node.opacity = 200;

//Creator 3.x
this.node.getComponent(UIOpacity).opacity = 200;

设置节点颜色

//Creator 2.x 
this.node.color = cc.Color.RED;

//Creator 3.x
this.node.getComponent(Sprite).color = Color.RED;

设置节点大小

//Creator 2.x
this.node.setContentSize(100, 100);

//Creator 3.x 
let transform = this.node.getComponent(UITransform);
//使用方法设置节点大小
transform.setContentSize(100, 100)
//也可以使用contentSize属性
transform.contentSize = Size(100, 100);
//还可以使用width、height属性
transform.width = 100;
transform.height = 100;

虽然 3.x 中 Node 的 position、scale、rotation 属性还在，但代码接口也有所变化，我们来看下他们的区别。

节点坐标转换

还有，在 2D 中常用的节点坐标转换

  • Node.convertToNodeSpaceAR
  • Node.convertToWorldSpaceAR
  • Node.getBoundingBox

这些接口移到了 UITransform 组件对象上了，看下面代码：

//Creator 2.x 
let p = this.node.convertToNodeSpaceAR(eventTouch.location)；

//Creator 3.x
let transform = this.node.getComponent(UITransform);
let location = eventTouch.location;
//注意 3.x 中convertToNodeSpaceAR的参数为 Vec3 类型
//但 location 为 Vec2 类型
let p = transform.convertToNodeSpaceAR(v3(location.x, location.y));

节点层级

在 2.x 中 Node.zIndex 是用来控制节点显示层级，数值越大在最底层。

而在 3.x 中 Node.zIndex 接口已被废弃，需要使用 Node.setSiblingIndex() 方法，与 2.x 是相反的，数值最小的在最底层。

4. Tween 动画

在 Creator 2.x 中 Tween 动画主要是控制节点的位移、旋转、缩放、透明度、颜色等属性。

移植到 Creator 3.x 后要注意的是：

  1. 有些属性已经不在 Node 对象上了，需要获取相关组件来控制
  2. 位移、旋转、缩放属性使用 Vec3 类型而非 Vec2，不然会出现一些意想不到的问题。

例如：

...
let node = item.node;
tween(node)
  .to(0.1, { scale: v2(1.1, 1.1) }) //放大
  .to(0.1, { scale: v2(1, 1)})      //还原，这里会出错！
  .start();

上面运行效果也都正常，但是会导致一些交互事件失效，比如：按钮无法响应点击事件。需要改成下面这样：

...
let node = item.node;
tween(node)
  .to(0.1, { scale: v3(1.1, 1.1) }) //放大
  .to(0.1, { scale: v3(1, 1)})      //还原
  .start();

需要将 scale 属性的值从 Vec2 改成 Vect3 就正常了。

5. 编辑器加载资源

项目中，有时我们会用到编辑器内资源加载，什么意思呢？

就是说希望在编辑器状态，就能看一些界面效果，而不用跑H5预览。

而且使用到的图片资源，并不是在编辑器中手动拖放的，而是用代码加载。

Creator 2.x 升级 3.x 基础 API 差异总结

上图中，通过 GameBoard 组件的 Level 属性切换关卡编号，可看直接看到场景变化。

不会的同学可能会问，这是怎么做到的呢？

** 1. 为组件脚本添加 executeInEditMode 装饰器 **

import { _decorator } from 'cc';
const {ccclass, executeInEditMode} = _decorator;

@ccclass('GameBoard')
@executeInEditMode //添加编辑器模式执行
export default class GameBoard extends Component {
  onLoad() {
    //代码将在编辑器状态执行
  }
  start() {
    //代码将在编辑器状态执行
  }
  update() {
    //代码将在编辑器状态执行
  }
}

注意，在编辑器中执行代码可能会出现一些副作用，比如对象未初化、update被频繁调起。

在 2.x 这时你可以使用 CC_EDITOR 变量做检查，代码如下：

//Creator 2.x 使用 CC_EDIDTO 全局变量检查
update() {
  if (CC_EDITOR) {
    return；
  }
  ...
}

3.x 中已经不存在全局 CC_EDITOR，而是在 cc/env 模块，代码如下：

//Creator 3.x 使用 EDITOR 变量检查
import { EDITOR } from 'cc/env';
...
update() {
  if (EDITOR) {
    return；
  }
  ...
}

** 2. 编辑器中加载资源 **

//Creator 2.4.x 加载图集中的图片
//注意'path'为resouces目录文件路径
cc.resources.load(path, SpriteAtlas, (err, res) => {
  let sprite = this.getComponent(Sprite);
  sprite.spriteFrame = res.getSpriteFrame(this.imageName);
});

在 3.x 中 Bundle 目录下的资源，不能在编辑器状态下被加载。

因此需要将文件移出 resouces 目录，并使用 assetManager.loadAny 这个万能加载 API，代码如下：

//Creator 3.x 加载图集中的图片
assetManager.loadAny({uuid:'xxx', type: SpriteAtlas}, (err, res) => {
  let sprite = this.getComponent(Sprite);
  sprite.spriteFrame = res.getSpriteFrame(this.imageName);
})

在我的测试中使用 assetManager.loadAny({{uuid:...}})这种接口形式加载成功。

如何获得资源UUID，看下图：
Creator 2.x 升级 3.x 基础 API 差异总结

以上是都是我在升级 2.x 项目到 3.x 时遇到的 API 接口差异情况，在此做个记录，也希望能对你有所帮助。

更多精彩请关注Creator星球游戏开发社区

标签：

相关文章