Cocos Creator 常用 API 学习文档

面向 Cocos Creator（偏 2.x 风格）整理常用 API，按“用途 → 参数 → 返回值 → 示例代码”组织，示例均为可独立参考的代码段。

1. 脚本与组件体系

1.1 cc.Class(options)

用途：定义一个组件脚本类。

参数

• options: Object
• options.extends: Function：常用 cc.Component
• options.properties?: Object：可序列化属性
• 生命周期方法：onLoad/start/update/onDestroy 等

返回值

• Function：类构造函数

示例

// 定义一个简单的移动组件
cc.Class({
  // 继承自 cc.Component，这是所有 Cocos Creator 组件的基类
  extends: cc.Component,
  
  // properties 中定义的属性会在编辑器中显示为可配置项
  properties: {
    // 移动速度，可以在编辑器中调整
    speed: 100
  },
  
  // onLoad 在组件首次激活时调用，比 start 更早
  onLoad () {
    // 初始化计时器
    this.elapsed = 0
  },
  
  // update 每帧调用，dt 是距离上一帧的时间（秒）
  update (dt) {
    // 累计时间
    this.elapsed += dt
    // 根据速度和时间计算移动距离
    this.node.x += this.speed * dt
  }
})

1.2 cc.Component 生命周期

用途：组件基类，核心入口是生命周期函数。

参数

• update(dt:number)：dt 为秒

返回值

• 无

示例

// 演示组件生命周期的使用
cc.Class({
  extends: cc.Component,
  
  // onLoad：组件首次激活时调用，适合做初始化
  onLoad () {
    // 设置节点初始透明度为完全透明
    this.node.opacity = 0
    console.log('组件已加载，节点透明度设置为0')
  },
  
  // start：组件第一次激活后调用，在 onLoad 之后
  start () {
    // 设置节点透明度为完全不透明
    this.node.opacity = 255
    console.log('组件已启动，节点透明度设置为255')
  },
  
  // onDestroy：组件销毁时调用，适合做清理工作
  onDestroy () {
    // 取消所有定时器，避免内存泄漏
    this.unscheduleAllCallbacks()
    console.log('组件已销毁，清理定时器')
  }
})

1.3 this.schedule / this.scheduleOnce / this.unschedule

用途：组件级定时器（基于 Scheduler）。

参数

• schedule(callback:Function, interval?:number, repeat?:number, delay?:number)
• scheduleOnce(callback:Function, delay?:number)
• unschedule(callback:Function)
• unscheduleAllCallbacks()

返回值

• 无

示例

// 演示定时器的使用
cc.Class({
  extends: cc.Component,
  
  onLoad () {
    // scheduleOnce：延迟1秒后执行一次 spawnEnemy 方法
    this.scheduleOnce(this.spawnEnemy.bind(this), 1)
    
    // schedule：每0.5秒执行一次 tick 方法，无限重复
    this.schedule(this.tick.bind(this), 0.5)
    
    console.log('定时器已设置：1秒后生成敌人，每0.5秒旋转节点')
  },
  
  // 定时器回调函数：每0.5秒旋转节点10度
  tick () {
    this.node.angle += 10
    console.log('节点旋转，当前角度：' + this.node.angle)
  },
  
  // 一次性定时器回调：生成敌人
  spawnEnemy () {
    this.node.scale = 1.2
    console.log('敌人已生成，节点缩放为1.2倍')
  }
})

2. 场景管理（cc.director）

2.1 cc.director.loadScene(sceneName[, onLaunched])

用途：切换场景。

参数

• sceneName: string
• onLaunched?: Function

返回值

• 无

示例

// 切换到 Home 场景，并在切换完成后执行回调
cc.director.loadScene('Home', function () {
  // 场景加载完成后的回调函数
  cc.log('Home 场景已加载完成')
  console.log('可以在这里执行场景初始化后的逻辑')
})

// 也可以不传回调函数，直接切换场景
// cc.director.loadScene('Home')

2.2 cc.director.preloadScene(sceneName, onProgress, onLoaded)

用途：预加载场景（适合做加载进度）。

参数

• sceneName: string
• onProgress?: (completed:number, total:number, item:any) => void
• onLoaded?: (err:Error|null, scene:any) => void

返回值

• 无

示例

// 预加载 Game 场景，显示加载进度
cc.director.preloadScene(
  'Game',
  // 进度回调函数：显示加载进度
  function (completed, total) {
    // 计算加载进度百分比
    var p = total === 0 ? 1 : completed / total
    
    // 显示加载进度
    cc.log('场景加载进度：', p * 100 + '%')
    console.log('已加载：' + completed + '/' + total + ' 个资源')
    
    // 可以在这里更新进度条UI
    // this.updateProgressBar(p)
  },
  // 加载完成回调函数
  function (err) {
    if (!err) {
      // 预加载成功，切换到 Game 场景
      cc.log('Game 场景预加载完成，开始切换场景')
      cc.director.loadScene('Game')
    } else {
      // 预加载失败，处理错误
      console.error('场景预加载失败：', err)
    }
  }
)

2.3 cc.director.getScene()

用途：获取当前运行的场景根节点。

返回值

• cc.Scene

示例

// 获取当前场景的根节点
var scene = cc.director.getScene()

// 创建一个新的弹出窗口节点
var node = new cc.Node('Popup')

// 将新节点添加到场景中
scene.addChild(node)

// 设置弹出窗口的位置和大小
node.setPosition(cc.v2(0, 0))
node.width = 200
node.height = 100

console.log('已创建弹出窗口并添加到当前场景')

2.4 cc.director.pause() / cc.director.resume()

用途：暂停/恢复导演（影响 scheduler/actions/animations 等）。

返回值

• 无

示例

// 暂停游戏（暂停所有定时器、动画、物理等）
cc.director.pause()
console.log('游戏已暂停')

// 1秒后恢复游戏
setTimeout(function () {
  cc.director.resume()
  console.log('游戏已恢复')
}, 1000)

// 实际应用场景：显示暂停菜单时暂停游戏
// function showPauseMenu() {
//   cc.director.pause()
//   this.pauseMenu.active = true
// }
// 
// function hidePauseMenu() {
//   cc.director.resume()
//   this.pauseMenu.active = false
// }

3. 节点（cc.Node）与组件（getComponent/addComponent）

3.1 node.getChildByName(name)

用途：查找直接子节点。

参数

• name: string

返回值

• cc.Node | null

示例

// 查找名为 'Button' 的直接子节点
var btn = this.node.getChildByName('Button')

// 检查是否找到按钮节点
if (btn) {
  // 如果找到按钮，将其设置为激活状态
  btn.active = true
  console.log('找到按钮节点，已激活')
} else {
  // 如果没有找到按钮，输出警告
  console.warn('未找到名为 Button 的子节点')
}

// 实际应用：在UI界面中查找特定控件
// var scoreLabel = this.node.getChildByName('ScoreLabel')
// if (scoreLabel) {
//   var labelComp = scoreLabel.getComponent(cc.Label)
//   if (labelComp) {
//     labelComp.string = '分数：100'
//   }
// }

3.2 node.addChild(child[, zIndex])

用途：挂载子节点。

参数

• child: cc.Node
• zIndex?: number

返回值

• 无

示例

// 创建一个新的子节点
var child = new cc.Node('Child')

// 设置子节点的渲染层级（zIndex越大，显示越靠前）
child.zIndex = 10

// 将子节点添加到当前节点下
this.node.addChild(child)

// 设置子节点的位置和大小
child.setPosition(cc.v2(100, 50))
child.width = 80
child.height = 60

console.log('已创建子节点并添加到父节点，zIndex：' + child.zIndex)

// 实际应用：动态创建游戏对象
// var bullet = new cc.Node('Bullet')
// bullet.zIndex = 5  // 子弹在背景之上，但在UI之下
// this.node.addChild(bullet)
// bullet.setPosition(this.node.position)

3.3 node.removeFromParent([cleanup]) / node.destroy()

用途：移除或销毁节点。

参数

• cleanup?: boolean

返回值

• 无

示例

// 从父节点中移除当前节点，并清理所有动作和事件监听器
this.node.removeFromParent(true)
console.log('节点已从父节点移除')

// 完全销毁节点（释放内存）
this.node.destroy()
console.log('节点已销毁')

// 实际应用：子弹击中目标后销毁
// function onBulletHit() {
//   // 先移除节点
//   this.node.removeFromParent(true)
//   
//   // 然后销毁节点
//   this.node.destroy()
// }

// 注意：removeFromParent(true) 会清理节点的动作和事件
// removeFromParent(false) 则只移除节点，不清理动作和事件

3.4 node.getComponent(typeOrName) / node.addComponent(typeOrName)

用途：获取/添加组件。

参数

• typeOrName: Function | string

返回值

• getComponent -> Component | null
• addComponent -> Component

示例

// 获取节点上的 Label 组件
var label = this.node.getComponent(cc.Label)

// 检查是否获取到 Label 组件
if (label) {
  // 如果存在 Label 组件，设置文本内容
  label.string = 'Hello'
  console.log('已设置 Label 文本为：Hello')
} else {
  console.warn('节点上没有 Label 组件')
}

// 获取或添加 Graphics 组件（如果不存在则添加）
var graphics = this.node.getComponent(cc.Graphics) || this.node.addComponent(cc.Graphics)

// 使用 Graphics 组件清空绘制内容
graphics.clear()
console.log('已获取或添加 Graphics 组件，并清空绘制')

// 实际应用：动态添加组件
// var rigidbody = this.node.getComponent(cc.RigidBody)
// if (!rigidbody) {
//   rigidbody = this.node.addComponent(cc.RigidBody)
//   rigidbody.type = cc.RigidBodyType.Dynamic
// }

3.5 cc.find(path[, root])

用途：按路径查找节点。

参数

• path: string
• root?: cc.Node

返回值

• cc.Node | null

示例

// 按路径查找节点（从场景根节点开始查找）
var node = cc.find('Canvas/Panel/Close')

// 检查是否找到节点
if (node) {
  // 如果找到节点，将其设置为激活状态
  node.active = true
  console.log('找到关闭按钮节点，已激活')
} else {
  console.warn('未找到路径为 Canvas/Panel/Close 的节点')
}

// 也可以指定查找的根节点
// var rootNode = cc.director.getScene()
// var specificNode = cc.find('UI/Popup', rootNode)

// 实际应用：查找UI控件
// var scoreText = cc.find('Canvas/HUD/ScoreText')
// if (scoreText) {
//   var label = scoreText.getComponent(cc.Label)
//   if (label) {
//     label.string = '1000'
//   }
// }

// 注意：路径使用斜杠分隔，类似于文件路径
// 查找效率比 getChildByName 低，但可以查找任意层级的节点

4. 事件系统（输入与节点事件）

4.1 node.on / node.off / node.once

用途：监听/移除节点事件。

参数

• on(type:string, callback:Function, target?:any)
• off(type?:string, callback?:Function, target?:any)
• once(type:string, callback:Function, target?:any)

返回值

• 无

示例

// 定义事件处理函数
var handler = function () {
  cc.log('节点被点击了')
  console.log('可以在这里处理点击逻辑')
}

// 监听节点的触摸结束事件
this.node.on(cc.Node.EventType.TOUCH_END, handler, this)
console.log('已注册触摸结束事件监听器')

// 移除事件监听器（通常在 onDestroy 中调用）
this.node.off(cc.Node.EventType.TOUCH_END, handler, this)
console.log('已移除触摸结束事件监听器')

// 使用 once 监听一次性事件（触发后自动移除）
this.node.once(cc.Node.EventType.TOUCH_START, function() {
  console.log('第一次触摸开始，此监听器只会触发一次')
}, this)

// 实际应用：按钮点击事件
// this.buttonNode.on(cc.Node.EventType.TOUCH_END, function() {
//   this.onButtonClick()
// }, this)

4.2 触摸事件常用接口

用途：读取触摸点信息。

常用方法

• event.getLocation() -> cc.Vec2：获取触摸点的世界坐标
• event.getDelta() -> cc.Vec2：获取触摸点的移动增量

示例

// 监听节点的触摸移动事件
this.node.on(cc.Node.EventType.TOUCH_MOVE, function (event) {
  // 获取触摸点的世界坐标（相对于屏幕左下角）
  var p = event.getLocation()
  
  // 获取触摸点的移动增量（相对于上一帧的位移）
  var d = event.getDelta()
  
  // 输出坐标和移动信息
  cc.log('触摸点坐标：(' + p.x + ', ' + p.y + ')')
  cc.log('移动增量：(' + d.x + ', ' + d.y + ')')
  
  // 实际应用：拖动节点
  // this.node.x += d.x
  // this.node.y += d.y
  
  // 实际应用：限制拖动范围
  // var newX = this.node.x + d.x
  // var newY = this.node.y + d.y
  // this.node.x = cc.misc.clampf(newX, 0, cc.winSize.width)
  // this.node.y = cc.misc.clampf(newY, 0, cc.winSize.height)
})

console.log('已注册触摸移动事件监听器')

4.3 cc.systemEvent（键盘/重力等）

用途：全局事件监听（平台支持时）。

示例

// 监听全局键盘按下事件
cc.systemEvent.on(cc.SystemEvent.EventType.KEY_DOWN, function (event) {
  // 输出按下的键码
  cc.log('键盘按下，键码：', event.keyCode)
  
  // 根据键码执行不同操作
  switch (event.keyCode) {
    case cc.macro.KEY.space:
      console.log('空格键被按下')
      // this.jump()
      break
    case cc.macro.KEY.a:
      console.log('A键被按下')
      // this.moveLeft()
      break
    case cc.macro.KEY.d:
      console.log('D键被按下')
      // this.moveRight()
      break
    case cc.macro.KEY.escape:
      console.log('ESC键被按下，显示暂停菜单')
      // this.showPauseMenu()
      break
  }
})

// 监听键盘释放事件
cc.systemEvent.on(cc.SystemEvent.EventType.KEY_UP, function (event) {
  cc.log('键盘释放，键码：', event.keyCode)
})

// 监听设备方向变化（移动设备）
cc.systemEvent.on(cc.SystemEvent.EventType.DEVICEMOTION, function (event) {
  // 获取加速度数据
  var acc = event.acc
  console.log('设备加速度：x=' + acc.x + ', y=' + acc.y + ', z=' + acc.z)
  
  // 实际应用：根据加速度控制游戏角色移动
  // this.node.x += acc.x * 10
})

console.log('已注册全局事件监听器')

5. 资源加载（2.x 常见：cc.loader）

5.1 cc.loader.loadRes(url, type, onComplete)

用途：按路径加载资源（常用于 SpriteFrame/Prefab/Json 等）。

参数

• url: string
• type?: Function
• onComplete: (err:Error|null, asset:any) => void

返回值

• 无

示例

// 加载 resources 文件夹下的 ui/icon 图片资源
cc.loader.loadRes('ui/icon', cc.SpriteFrame, function (err, sf) {
  // 检查是否加载成功
  if (!err) {
    // 获取节点上的 Sprite 组件
    var sp = this.node.getComponent(cc.Sprite)
    
    // 检查是否存在 Sprite 组件
    if (sp) {
      // 设置 Sprite 的图片
      sp.spriteFrame = sf
      console.log('图标资源加载成功并设置到 Sprite 组件')
    } else {
      console.warn('节点上没有 Sprite 组件')
    }
  } else {
    // 加载失败，输出错误信息
    console.error('资源加载失败：', err)
    
    // 实际应用：可以设置默认图片或重试加载
    // this.loadDefaultIcon()
  }
}.bind(this))

// 加载 Prefab 资源
// cc.loader.loadRes('prefabs/enemy', cc.Prefab, function (err, prefab) {
//   if (!err) {
//     var enemy = cc.instantiate(prefab)
//     this.node.addChild(enemy)
//   }
// }.bind(this))

// 加载 JSON 配置文件
// cc.loader.loadRes('config/level1', function (err, config) {
//   if (!err) {
//     this.levelConfig = config
//   }
// }.bind(this))

console.log('开始加载资源：ui/icon')

5.2 cc.loader.load(obj, onComplete)

用途：按 URL 加载（可用于远程图片等）。

参数

• obj: { url: string, type?: string }
• onComplete: (err:Error|null, res:any) => void

返回值

• 无

示例

// 从远程URL加载图片资源
cc.loader.load({ 
  url: 'https://example.com/a.png', 
  type: 'png' 
}, function (err, tex) {
  // 检查是否加载成功
  if (!err) {
    // 创建 SpriteFrame 对象
    var sf = new cc.SpriteFrame(tex)
    
    // 获取节点上的 Sprite 组件
    var sp = this.node.getComponent(cc.Sprite)
    
    // 检查是否存在 Sprite 组件
    if (sp) {
      // 设置 Sprite 的图片
      sp.spriteFrame = sf
      console.log('远程图片加载成功并设置到 Sprite 组件')
    } else {
      console.warn('节点上没有 Sprite 组件')
    }
  } else {
    // 加载失败，输出错误信息
    console.error('远程资源加载失败：', err)
    
    // 实际应用：可以设置默认图片或显示错误提示
    // this.showLoadError()
  }
}.bind(this))

// 加载远程 JSON 数据
// cc.loader.load({
//   url: 'https://api.example.com/game/config',
//   type: 'json'
// }, function (err, data) {
//   if (!err) {
//     this.gameConfig = data
//     console.log('游戏配置加载成功')
//   }
// }.bind(this))

// 注意：跨域加载需要服务器支持 CORS
// 对于小游戏平台，可能需要使用平台特定的网络API

console.log('开始加载远程资源：' + 'https://example.com/a.png')

6. 实例化与对象池

6.1 cc.instantiate(original)

用途：从 Prefab/Node 生成实例。

参数

• original: cc.Prefab | cc.Node

返回值

• cc.Node

示例

cc.loader.loadRes('prefabs/Toast', cc.Prefab, function (err, prefab) {
  if (!err) {
    var node = cc.instantiate(prefab)
    cc.director.getScene().addChild(node)
  }
})

6.2 cc.NodePool

用途：复用节点，减少频繁创建/销毁。

常用方法

• pool.get() -> cc.Node
• pool.put(node:cc.Node) -> void
• pool.size() -> number

示例

var pool = new cc.NodePool()

function spawn (prefab) {
  return pool.size() > 0 ? pool.get() : cc.instantiate(prefab)
}

function recycle (node) {
  pool.put(node)
}

7. Tween 深入（cc.tween / cc.Tween）

7.1 基础链式：delay / to / by / call / start

用途：做 UI/角色的过渡动画。

参数与返回值

• cc.tween(target) -> cc.Tween
• delay(seconds:number) -> cc.Tween
• to(seconds:number, props:Object, opts?:Object) -> cc.Tween
• by(seconds:number, props:Object, opts?:Object) -> cc.Tween
• call(cb:Function) -> cc.Tween
• start() -> void

示例

cc.tween(this.node)
  .delay(0.2)
  .to(0.3, { scale: 1.1 })
  .to(0.2, { scale: 1.0 })
  .call(function () {
    cc.log('done')
  })
  .start()

7.2 easing（缓动曲线）

用途：让动画更自然。

参数

• opts.easing: string：如 linear/sineIn/sineOut/backOut/quadInOut 等

示例

cc.tween(this.node)
  .to(0.5, { y: 200 }, { easing: 'backOut' })
  .start()

7.3 repeat / repeatForever

用途：循环播放动画。

示例

var once = cc.tween().to(0.2, { opacity: 80 }).to(0.2, { opacity: 255 })
cc.tween(this.node).repeatForever(once).start()

7.4 sequence 与 parallel（串行/并行）

用途：复杂动画组合。

示例

var move = cc.tween().to(0.3, { x: 200 })
var fade = cc.tween().to(0.3, { opacity: 0 })
cc.tween(this.node)
  .parallel(move, fade)
  .to(0.2, { scale: 0.8 })
  .start()

7.5 停止 Tween：stop / stopAllByTarget

用途：切场景或重复触发前清理旧动画，避免叠加。

示例

cc.Tween.stopAllByTarget(this.node)
cc.tween(this.node).to(0.2, { scale: 1 }).start()

7.6 常见易错点与建议

• 同一节点重复 start() 新 tween，最好先 cc.Tween.stopAllByTarget(node)
• Tween 回调里引用已销毁节点时，先判断 cc.isValid(node)
• UI 弹窗推荐：入场 tween + BlockInputEvents 防穿透 + 退场 tween

示例

var node = this.node
cc.Tween.stopAllByTarget(node)
cc.tween(node)
  .to(0.15, { scale: 1.05 })
  .to(0.1, { scale: 1.0 })
  .start()

8. UI 常用组件补充

8.1 cc.Label / cc.RichText

用途：文字显示（普通/富文本）。

示例

var label = this.node.getComponent(cc.Label)
if (label) label.string = 'Score: 100'

8.2 cc.Button / cc.Toggle / cc.Slider / cc.EditBox

用途：常见交互控件。

示例

var btn = this.node.getComponent(cc.Button)
if (btn) btn.interactable = false

8.3 cc.ScrollView / cc.Layout / cc.Widget

用途：滚动、布局、对齐适配。

示例

var widget = this.node.getComponent(cc.Widget)
if (widget) {
  widget.top = 0
  widget.bottom = 0
  widget.updateAlignment()
}

9. 数学与坐标（cc.v2 / cc.v3 / cc.misc）

9.1 cc.v2 / cc.v3 与常用向量操作

示例

var a = cc.v2(10, 0)
var b = cc.v2(10, 10)
var dir = b.sub(a).normalize()
var next = a.add(dir.mul(5))

9.2 角度/弧度互转

示例

var rad = cc.misc.degreesToRadians(90)
var deg = cc.misc.radiansToDegrees(Math.PI)
cc.log(rad, deg)

9.3 坐标转换（AR）

示例

var world = this.node.convertToWorldSpaceAR(cc.v2(0, 0))
var local = this.node.parent.convertToNodeSpaceAR(world)
cc.log(world, local)

10. 动作系统（旧 Action）与 Tween 的区别

10.1 node.runAction(action)

用途：2.x 常见的 Action 动画系统（与 Tween 并存）。

示例

var a = cc.moveTo(0.3, cc.v2(200, 0))
var b = cc.fadeOut(0.3)
this.node.runAction(cc.spawn(a, b))

10.2 如何选择

• 只要项目已大量使用 Tween：优先 Tween（可读性高、组合方便）
• 旧项目大量 runAction：维持一致性也可以
• 关键点：避免同一属性被 Tween 与 Action 同时驱动

11. 物理系统（简要）

11.1 碰撞回调（onBeginContact/onEndContact）

示例

cc.Class({
  extends: cc.Component,
  onBeginContact: function (contact, selfCollider, otherCollider) {
    this.node.opacity = 200
  },
  onEndContact: function () {
    this.node.opacity = 255
  }
})

12. 存储与系统（cc.sys / cc.game / cc.macro）

12.1 cc.sys.localStorage

示例

cc.sys.localStorage.setItem('volume', '0.5')
var v = cc.sys.localStorage.getItem('volume')
cc.log(v)

12.2 cc.game.setFrameRate / cc.game.addPersistRootNode

示例

cc.game.setFrameRate(60)
cc.game.addPersistRootNode(this.node)

12.3 cc.macro 常用项

示例

cc.macro.ENABLE_MULTI_TOUCH = false