LayaAir 新手必知功能指南

本文档整理了LayaAir引擎新手开发必须掌握的核心API，主要内容包括：引擎初始化 - 通过Laya.init()初始化引擎，可配置画布参数和帧率等基础设置显示列表架构 - 详细介绍Node节点基类、Sprite精灵和Stage舞台的常用属性和方法，包括节点管理、变换控制、显示属性等事件系统 - 事件监听(on/once)和移除(off)的基本用法其他核心模块 - 简要提及资源加载、动画

孟无岐

727人浏览 · 2026-01-14 22:32:45

孟无岐 · 2026-01-14 22:32:45 发布

LayaAir 新手必知功能指南

本文档基于 LayaAir.d.ts 类型定义文件整理，汇总新手开发时必须了解的核心 API。

1. 全局入口 (Laya 类)

类型定义位置: LayaAir.d.ts:34-144

引擎初始化

// 基础初始化
Laya.init(width: number, height: number): Promise<void>

// 使用配置对象初始化
Laya.init(stageConfig?: Laya.IStageConfig): Promise<void>

全局对象访问

Laya.stage         // 舞台对象（根容器）
Laya.timer         // 游戏主时钟（管理场景、动画、缓动等）
Laya.loader        // 加载管理器
Laya.systemTimer   // 系统时钟管理器（引擎内部使用）
Laya.physicsTimer  // 物理时钟管理器

Config 配置（需在 init 前设置）

类型定义位置: LayaAir.d.ts:207-335

配置项	类型	说明
`isAntialias`	boolean	画布是否抗锯齿，只对 2D(WebGL) 有效
`useWebGL2`	boolean	是否使用 WebGL2
`FPS`	number	帧率限制
`useRetinalCanvas`	boolean	是否使用视网膜模式（更精细显示）
`defaultFontSize`	number	默认文本大小，默认 12
`defaultFont`	string	默认文本字体，默认 Arial
`isAlpha`	boolean	画布是否透明
`fixedFrames`	boolean	是否使用固定帧率渲染

引擎生命周期回调

// 在引擎初始化前执行（可修改 stageConfig）
Laya.addBeforeInitCallback(callback: (stageConfig) => void)

// 在引擎初始化后执行
Laya.addAfterInitCallback(callback: () => void)

// 模块初始化注册
Laya.addInitCallback(callback: () => void)

2. 显示列表架构

Node - 节点基类

类型定义位置: LayaAir.d.ts:28423-29196

Node 是所有显示对象的基类，继承自 EventDispatcher。

节点管理

// 添加子节点
addChild<T>(node: T): T
addChildren(...args: Node[]): void           // 批量添加
addChildAt<T>(node: T, index: number): T    // 插入到指定位置

// 移除子节点
removeChild(node: Node): Node
removeChildAt(index: number): Node
removeChildren(): void                       // 移除所有子节点
destroyChildren(): void                      // 销毁所有子节点

// 获取子节点
getChildAt<T>(index: number): T                          // 按索引获取
getChildByName<T>(name: string): T                      // 按名称获取
getChildByPath<T>(path: string): T                      // 按路径获取（如 "A.B.C"）
findChild<T>(name: string): T                          // 递归查找（不含 Prefab 内部）

// 子节点索引操作
getChildIndex(node: Node): number              // 获取索引
setChildIndex(node: Node, index: number): Node  // 设置索引

节点属性

name: string           // 节点名称
tag: string           // 节点标签
url: string           // 资源 URL
destroyed: boolean    // 是否已销毁
is3D: boolean         // 是否是 3D 节点
hideFlags: number     // 隐藏标志

生命周期

destroy(destroyChild?: boolean): void    // 销毁节点
onDestroy(): void                        // 销毁回调（虚方法，可重写）

Sprite - 2D精灵

类型定义位置: LayaAir.d.ts:30760-31805

Sprite 是基本的显示图形节点，继承自 Node。

位置与尺寸

// 坐标（相对于父容器）
x: number
y: number

// 尺寸（像素）
width: number
height: number
displayWidth: number    // 显示宽度（包含缩放）
displayHeight: number   // 显示高度（包含缩放）

变换属性

// 缩放（负值可实现翻转效果）
scaleX: number    // X 轴缩放，默认 1
scaleY: number    // Y 轴缩放，默认 1

// 旋转
rotation: number  // 旋转角度（度）

// 倾斜
skewX: number     // 水平倾斜角度
skewY: number     // 垂直倾斜角度

// 锚点（轴心点）
pivotX: number    // X 轴心点
pivotY: number    // Y 轴心点

显示控制

visible: boolean          // 是否可见
alpha: number            // 透明度 (0-1)
blendMode: BlendMode     // 混合模式
graphics: Graphics       // 绘图对象
texture: Texture         // 纹理

交互属性

mouseThrough: boolean    // 鼠标事件是否穿透
hitTestPrior: boolean    // 点击检测优先级（true: 优先检测本对象，false: 优先检测子对象）

渲染相关

// 缓存
cacheAs: string          // 缓存类型
cacheAsBitmap: boolean   // 是否缓存为位图

// 遮罩
mask: Sprite             // 遮罩对象

// 滚动视窗
scrollRect: Rectangle    // 滚动区域

// 层级
zOrder: number           // Z 轴排序，数值越大越靠前

Stage - 舞台

类型定义位置: LayaAir.d.ts:32038-32426

Stage 是根容器，继承自 Sprite。

// 设计尺寸
designWidth: number     // 设计宽度
designHeight: number    // 设计高度

// 屏幕适配
scaleMode: string       // 缩放模式
screenMode: string      // 屏幕方向（横屏/竖屏）
alignV: string          // 垂直对齐
alignH: string          // 水平对齐

// 帧率
frameRate: number       // 帧率设置

// 场景管理
setScene(scene: Scene): void    // 设置当前场景

Scene - 2D场景

类型定义位置: LayaAir.d.ts:29507+

// 场景加载
Scene.load(url: string, complete: Handler): void

// 关闭当前场景
Scene.close(type: string): void

3. 事件系统

EventDispatcher - 事件派发器

类型定义位置: LayaAir.d.ts:33603-33730

所有可调度事件的类的基类。

监听事件

// 持续监听
on(type: string, listener: Function): EventDispatcher
on(type: string, caller: any, listener: Function, args?: any[]): EventDispatcher

// 监听一次
once(type: string, listener: Function): EventDispatcher
once(type: string, caller: any, listener: Function, args?: any[]): EventDispatcher

移除监听

// 移除指定监听
off(type: string, listener: Function): EventDispatcher
off(type: string, caller: any, listener?: Function): EventDispatcher

// 移除所有监听
offAll(type?: string): EventDispatcher
offAllCaller(caller: any): EventDispatcher

派发事件

// 派发事件
event(type: string, data?: any): boolean

// 检查监听
hasListener(type: string): boolean

事件冒泡

// 向父节点链冒泡事件
bubbleEvent(type: string, data?: any): void

InputManager - 输入管理器

类型定义位置: LayaAir.d.ts:33737-33919

鼠标/触摸

// 鼠标位置
static mouseX: number
static mouseY: number
static lastMouseTime: number

// 触摸相关
static multiTouchEnabled: boolean    // 是否开启多点触控
static mouseEventsEnabled: boolean   // 是否开启鼠标事件
static touches: ReadonlyArray<ITouchInfo>    // 当前触摸信息数组
static touchCount: number            // 当前触摸数量
static touchTarget: Node             // 当前触摸目标节点

// 获取触摸位置
static getTouchPos(touchId?: number): Readonly<Point>

// 取消点击
static cancelClick(touchId?: number): void

键盘

static keyEventsEnabled: boolean      // 是否开启键盘事件
static hasKeyDown(key: string | number): boolean  // 按键是否按下

Keyboard - 键盘类

类型定义位置: LayaAir.d.ts:33997+

// 鼠标按键
static CLICK: number
static MOUSE_DOWN: number
static MOUSE_UP: number
static MOUSE_MOVE: number

// 键盘按键
static KEY_DOWN: number
static KEY_UP: number
static KEY_PRESS: number

4. 资源加载

Loader - 加载器

类型定义位置: LayaAir.d.ts:47926+

加载类型

static readonly TEXT = "text"          // 文本类型
static readonly JSON = "json"          // JSON 类型
static readonly XML = "xml"            // XML 类型
static readonly PREFAB = "prefab"      // 预制体
static readonly IMAGE = "image"        // 图片
static readonly SOUND = "sound"        // 音频
static readonly ATLAS = "atlas"        // 图集
static readonly FONT = "font"          // 字体

加载方法

// 加载单个/多个资源
load(url: string | string[], complete?: Handler, progress?: Handler): void

// 创建资源（创建完成后缓存）
create(url: string, complete?: Handler): void

// 缓存相关
cacheRes(url: string, data: any): void           // 缓存资源
getRes(url: string): any                        // 获取缓存资源
getAtlas(url: string): Array<any>               // 获取图集
clearRes(url: string, forceDispose?: boolean): void  // 清除缓存
clearTextureRes(url: string): void              // 清除纹理缓存

Texture - 纹理

类型定义位置: LayaAir.d.ts:79718+

// 纹理属性
uv: ArrayLike<number>          // UV 信息
width: number                  // 纹理宽度
height: number                 // 纹理高度
sourceWidth: number            // 源宽度
sourceHeight: number           // 源高度
offsetX: number                // X 偏移
offsetY: number                // Y 偏移

// 加载纹理
static load(url: string): Texture

Texture2D - 2D纹理

类型定义位置: LayaAir.d.ts:80045+

// 从图片创建
static loadImage(url: string): Promise<Texture2D>

// 从颜色创建
static create(r: number, g: number, b: number, a: number): Texture2D

// 纹理数据
format: number                 // 纹理格式
mipmap: boolean                // 是否有 mipmap

5. 动画系统

Tween - 缓动动画

类型定义位置: LayaAir.d.ts:86692+

基本用法

// 从当前值过渡到目标值
static to(
    target: any,
    props: any,
    duration: number,
    ease?: Function,
    complete?: Function,
    delay?: number
): Tween

// 从目标值过渡到当前值
static from(
    target: any,
    props: any,
    duration: number,
    ease?: Function,
    complete?: Function,
    delay?: number
): Tween

清除动画

static clear(target: any): void        // 清除指定对象的所有动画
static clearAll(target: any): void     // 清除指定对象的所有缓动

Animation - 2D动画

类型定义位置: LayaAir.d.ts:24727+

// 播放控制
play(start?: number, loop?: boolean, name?: string): void
stop(): void

// 动画属性
source: string           // 动画数据源
interval: number         // 播放间隔（毫秒）

Animator2D - 2D动画控制器

类型定义位置: LayaAir.d.ts:3698+

// 动画状态
play(stateName: string, layerIndex?: number, normalizedTime?: number): void

// 速度控制
speed: number            // 播放速度

// 停止/暂停
stop(): void

6. 定时器

Timer - 时间管理器

类型定义位置: LayaAir.d.ts:98218+

帧循环

// 每隔指定帧数执行一次（持续执行）
frameLoop(delay: number, caller: any, method: Function, args?: any[], coverBefore?: boolean): void

// 延迟指定帧数后执行一次
frameOnce(delay: number, caller: any, method: Function, args?: any[], coverBefore?: boolean): void

时间循环（毫秒）

// 每隔指定毫秒数执行一次（持续执行）
loop(delay: number, caller: any, method: Function, args?: any[], coverBefore?: boolean, jumpFrame?: boolean): void

// 延迟指定毫秒数后执行一次
once(delay: number, caller: any, method: Function, args?: any[], coverBefore?: boolean): void

清除定时器

// 清除指定定时器
clear(caller: any, method: Function): void

// 清除 caller 的所有定时器
clearAll(caller: any): void

计时相关

// 获取当前时间（毫秒）
static currTimer: number

// 获取当前帧数
static currFrame: number

// 计算 delta 时间
static delta: number

7. 3D模块

Sprite3D - 3D精灵

类型定义位置: LayaAir.d.ts:15807+

变换

transform: Transform3D    // 3D 变换

// 位置
transform.position: Vector3

// 旋转
transform.rotation: Quaternion
transform.eulerAngles: Vector3

// 缩放
transform.scale: Vector3

实例化

// 克隆 3D 对象
clone(): Sprite3D
static instantiate(original: Sprite3D, parent?: Node, worldPositionStays?: boolean): Sprite3D

Scene3D - 3D场景

类型定义位置: LayaAir.d.ts:14964+

// 加载场景
static load(url: string): Promise<Scene3D>

// 场景属性
sceneRenderableManager: SceneRenderManager    // 渲染管理器

Camera - 摄像机

类型定义位置: LayaAir.d.ts:9608+

// 视角
fieldOfView: number     // 视野角度

// 裁剪面
nearPlane: number       // 近裁剪面
farPlane: number        // 远裁剪面

// 背景色
backgroundColor: Color

// 渲染目标
renderTarget: RenderTexture

// 渲染场景
render(scene: Scene3D): void

Material - 材质基类

类型定义位置: LayaAir.d.ts:10976+

// 着色器
shader: Shader3D

// 渲染模式
renderMode: number

// 材质属性
shaderData: ShaderData

8. 组件系统

Component - 组件基类

类型定义位置: LayaAir.d.ts:4880+

组件属性

owner: Node            // 所属节点
enabled: boolean       // 是否启用

生命周期

onEnable(): void       // 组件启用时调用
onDisable(): void      // 组件禁用时调用
onUpdate(): void       // 每帧更新
onLateUpdate(): void   // 每帧更新后调用
onDestroy(): void      // 组件销毁时调用

Script - 脚本组件

类型定义位置: LayaAir.d.ts:5554+

继承自 Component，用于编写自定义游戏逻辑脚本。

// 运行时相关
runEditor: number      // 编辑器运行

// 生命周期（继承自 Component）
onEnable(): void
onDisable(): void
onUpdate(): void
onDestroy(): void

Widget - UI适配组件

类型定义位置: LayaAir.d.ts:5761+

// 锚点
top: number
bottom: number
left: number
right: number

// 居中
centerX: number
centerY: number

// 缩放
scaleMode: string      // 缩放模式

9. 音频系统

SoundManager - 声音管理器

类型定义位置: LayaAir.d.ts:44379+

播放控制

// 播放音效
static playSound(
    url: string,
    loops?: number,
    complete?: Handler,
    soundClass?: Class,
    startTime?: number
): SoundChannel

// 播放音乐
static playMusic(url: string, loops?: number, complete?: Handler, soundClass?: Class): void

// 停止播放
static stopAll(): void              // 停止所有声音
static stopMusic(): void            // 停止音乐

音量控制

static musicVolume: number          // 音乐音量 (0-1)
static soundVolume: number          // 音效音量 (0-1)
static useAudioMusic: boolean       // 是否使用音频音乐
static playbackRate: number         // 播放速率

SoundChannel - 声音通道

类型定义位置: LayaAir.d.ts:44263+

// 播放控制
play(): void
stop(): void
pause(): void

// 属性
url: string                 // 声音地址
loops: number              // 循环次数
volume: number             // 音量
playbackRate: number       // 播放速率
position: number           // 当前播放位置（秒）
duration: number           // 总时长（秒）

10. 新手学习建议

学习顺序

基础概念
- 了解 LayaAir 引擎架构
- 理解显示列表（节点树）概念
- 掌握 TypeScript 基础语法
2D 开发基础
- Node → Sprite → Stage 的继承关系
- addChild / removeChild 父子节点管理
- 坐标系统与变换（x, y, scale, rotation）
事件机制
- on / off 事件监听
- event 事件派发
- 事件冒泡机制
资源管理
- Laya.loader.load 加载资源
- Texture 纹理使用
- 资源缓存与释放
动画与定时
- Tween 缓动动画
- Laya.timer 定时器
- 帧循环与时间循环的区别
3D 进阶
- Sprite3D 3D 精灵
- Scene3D 场景管理
- Camera 摄像机控制
- Material 材质系统
组件化开发
- Component 组件基类
- Script 脚本组件
- 组件生命周期

常见问题

为什么初始化后看不到内容？
- 检查 visible 是否为 true
- 确认已添加到显示列表 addChild
- 检查 alpha 透明度
- 确认坐标在屏幕范围内
如何适配不同屏幕？
- 设置 Laya.stage.designWidth / designHeight
- 选择合适的 scaleMode
- 使用 Widget 组件做 UI 适配
如何优化性能？
- 合理使用 cacheAsBitmap
- 及时 destroy 不用的对象
- 使用对象池减少 GC
- 控制同屏显示对象数量
事件监听没有响应？
- 检查 mouseEnabled 是否开启
- 确认对象在显示列表中
- 检查 hitTestPrior 设置
- 注意事件冒泡是否被阻止

本文档持续更新中，如有问题欢迎反馈。

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

2026年专业软件工程与企业架构的智能化演进

2048 AI社区

论文导读 | LLM4Graph

2048 AI社区

从工具到自主伙伴：AI Agent + Skills 架构全解析（2026主流技术趋势）

本文系统分析了AI智能体（AIAgent）与AI技能（AISkills）的技术演进与协同架构。AIAgent经历了从提示词驱动到自主闭环的三阶段发展，现已具备自主决策、任务分解等能力；AISkills则是标准化的专业能力模块。二者形成"大脑+技能库"的黄金组合，通过目标拆解、技能匹配、结果校验等流程协同工作，实现复杂任务的自主完成。这一架构将推动AI开发范式升级，带来效率跃迁和

2048 AI社区

所有评论(0)

查看更多评论

孟无岐

@weixin_73141239

已为社区贡献35条内容

LayaAir 新手必知功能指南

孟无岐

LayaAir 新手必知功能指南

目录

1. 全局入口 (Laya 类)

引擎初始化

全局对象访问

Config 配置（需在 init 前设置）

引擎生命周期回调

2. 显示列表架构

Node - 节点基类

节点管理

节点属性

生命周期

Sprite - 2D精灵

位置与尺寸

变换属性

显示控制

交互属性

渲染相关

Stage - 舞台

Scene - 2D场景

3. 事件系统

EventDispatcher - 事件派发器

监听事件

移除监听

派发事件

事件冒泡

InputManager - 输入管理器

鼠标/触摸

键盘

Keyboard - 键盘类

4. 资源加载

Loader - 加载器

加载类型

加载方法

Texture - 纹理

Texture2D - 2D纹理

5. 动画系统

Tween - 缓动动画

基本用法

清除动画

Animation - 2D动画

Animator2D - 2D动画控制器

6. 定时器

Timer - 时间管理器

帧循环

时间循环（毫秒）

清除定时器

计时相关

7. 3D模块

Sprite3D - 3D精灵

变换

实例化

Scene3D - 3D场景

Camera - 摄像机

Material - 材质基类

8. 组件系统

Component - 组件基类

组件属性

生命周期

Script - 脚本组件

Widget - UI适配组件

9. 音频系统

SoundManager - 声音管理器

播放控制

音量控制

SoundChannel - 声音通道

10. 新手学习建议

学习顺序

常见问题

所有评论(0)

孟无岐