Laya.Stage 类说明文档

目录

  1. 概述
  2. 继承关系
  3. 常量定义
  4. 核心属性
  5. 屏幕适配
  6. 帧率控制
  7. 事件
  8. 使用示例
  9. 最佳实践

概述

Stage 是 LayaAir 引擎中显示列表的根节点，所有显示对象都显示在舞台之上。通过 Laya.stage 单例访问。

核心特点

  • 显示列表的根节点，继承自 Laya.Sprite
  • 单例模式，通过 Laya.stage 访问
  • 提供多种屏幕适配模式
  • 提供多种帧率模式，可优化性能和功耗
  • 管理舞台焦点、可见性、全屏状态

继承关系

EventDispatcher
      └── Node
            └── Sprite
                  └── Stage

常量定义

缩放模式常量 (scaleMode)

常量 值 说明
SCALE_NOSCALE “noscale” 不缩放，保持设计尺寸
SCALE_EXACTFIT “exactfit” 全屏不等比缩放（可能变形）
SCALE_SHOWALL “showall” 最小比例缩放，完整显示内容
SCALE_NOBORDER “noborder” 最大比例缩放，填满屏幕
SCALE_FULL “full” stage宽高等于屏幕宽高
SCALE_FIXED_WIDTH “fixedwidth” 宽度固定，高度自适应
SCALE_FIXED_HEIGHT “fixedheight” 高度固定，宽度自适应
SCALE_FIXED_AUTO “fixedauto” 根据宽高比自动选择fixedwidth或fixedheight

屏幕方向常量 (screenMode)

常量 值 说明
SCREEN_NONE “none” 不更改屏幕方向
SCREEN_HORIZONTAL “horizontal” 自动横屏
SCREEN_VERTICAL “vertical” 自动竖屏

水平对齐常量 (alignH)

常量 值 说明
ALIGN_LEFT “left” 居左对齐
ALIGN_CENTER “center” 居中对齐
ALIGN_RIGHT “right” 居右对齐

垂直对齐常量 (alignV)

常量 值 说明
ALIGN_TOP “top” 居顶部对齐
ALIGN_MIDDLE “middle” 居中对齐
ALIGN_BOTTOM “bottom” 居底部对齐

帧率模式常量 (frameRate)

常量 值 说明
FRAME_FAST “fast” 快速模式，以最大帧率运行
FRAME_SLOW “slow” 慢速模式，帧率为快速模式的一半
FRAME_MOUSE “mouse” 鼠标模式，根据2秒内是否有鼠标移动自动切换
FRAME_SLEEP “sleep” 睡眠模式，1帧/秒

核心属性

尺寸相关

属性 类型 只读 说明
width number 是 舞台宽度
height number 是 舞台高度
designWidth number 否 设计宽度（初始化时设置）
designHeight number 否 设计高度（初始化时设置）
clientScaleX number 是 X轴缩放系数
clientScaleY number 是 Y轴缩放系数

适配相关

属性 类型 只读 说明
scaleMode string 否 缩放模式，默认"noscale"
screenMode string 否 屏幕方向，默认"none"
alignH string 否 水平对齐方式，默认"left"
alignV string 否 垂直对齐方式，默认"top"

性能相关

属性 类型 只读 说明
frameRate string 否 帧率模式
renderingEnabled boolean 否 是否启用渲染

状态相关

属性 类型 只读 说明
bgColor string 否 舞台背景颜色，默认黑色
isFocused boolean 是 舞台是否获得焦点
isVisibility boolean 是 舞台是否可见（未进入后台）
fullScreenEnabled boolean 否 是否开启全屏

鼠标位置

属性 类型 只读 说明
mouseX number 是 鼠标在Stage上的X轴坐标
mouseY number 是 鼠标在Stage上的Y轴坐标

其他

属性 类型 只读 说明
focus Laya.Node 是 当前焦点对象，影响键盘事件分发
canvasRotation boolean 否 画布是否翻转
canvasDegree number 否 画布旋转角度

屏幕适配

设置设计尺寸

// 初始化时设置设计尺寸
Laya.init(750, 1334);

// 动态更改屏幕大小
Laya.stage.setScreenSize(screenWidth: number, screenHeight: number);

缩放模式选择

// 不缩放（默认）
Laya.stage.scaleMode = Laya.Stage.SCALE_NOSCALE;

// 全屏不等比缩放，可能变形
Laya.stage.scaleMode = Laya.Stage.SCALE_EXACTFIT;

// 最小比例缩放，完整显示，可能有黑边
Laya.stage.scaleMode = Laya.Stage.SCALE_SHOWALL;

// 最大比例缩放，填满屏幕，可能裁剪
Laya.stage.scaleMode = Laya.Stage.SCALE_NOBORDER;

// 宽度固定，高度自适应
Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_WIDTH;

// 高度固定，宽度自适应
Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_HEIGHT;

// 自动选择固定宽高
Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_AUTO;

// stage宽高等于屏幕宽高
Laya.stage.scaleMode = Laya.Stage.SCALE_FULL;

对齐方式设置

// 水平对齐
Laya.stage.alignH = Laya.Stage.ALIGN_LEFT;    // 居左
Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;  // 居中
Laya.stage.alignH = Laya.Stage.ALIGN_RIGHT;   // 居右

// 垂直对齐
Laya.stage.alignV = Laya.Stage.ALIGN_TOP;     // 居顶
Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;  // 居中
Laya.stage.alignV = Laya.Stage.ALIGN_BOTTOM;  // 居底

屏幕方向设置

// 不更改屏幕方向
Laya.stage.screenMode = Laya.Stage.SCREEN_NONE;

// 自动横屏
Laya.stage.screenMode = Laya.Stage.SCREEN_HORIZONTAL;

// 自动竖屏
Laya.stage.screenMode = Laya.Stage.SCREEN_VERTICAL;

适配组合示例

// 初始化
class Main {
    constructor() {
        Laya.init(750, 1334);

        // 设置适配模式：固定高度，宽度自适应
        Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_HEIGHT;

        // 设置垂直居中、水平居中
        Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;
        Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;

        // 设置背景颜色
        Laya.stage.bgColor = "#232628";
    }
}

帧率控制

帧率模式设置

// 快速模式（默认），60帧
Laya.stage.frameRate = Laya.Stage.FRAME_FAST;

// 慢速模式，30帧
Laya.stage.frameRate = Laya.Stage.FRAME_SLOW;

// 鼠标模式，2秒内无鼠标操作自动降为30帧
Laya.stage.frameRate = Laya.Stage.FRAME_MOUSE;

// 睡眠模式，1帧/秒
Laya.stage.frameRate = Laya.Stage.FRAME_SLEEP;

渲染控制

// 停止渲染（保持最后一帧），降低CPU消耗
Laya.stage.renderingEnabled = false;

// 恢复渲染
Laya.stage.renderingEnabled = true;

获取帧时间

// 获取距当前帧开始后经过的时间（毫秒）
let time = Laya.stage.getTimeFromFrameStart();

事件

舞台事件列表

事件 说明
Event.RESIZE 舞台尺寸改变时触发
Event.FOCUS 舞台获得焦点时触发
Event.BLUR 舞台失去焦点时触发
Event.FOCUS_CHANGE 焦点状态改变时触发
Event.VISIBILITY_CHANGE 可见性改变时触发（切换前后台）
Event.FULL_SCREEN_CHANGE 全屏状态改变时触发

事件监听示例

// 监听舞台尺寸改变
Laya.stage.on(Laya.Event.RESIZE, this, onResize);

function onResize(): void {
   console.log("舞台尺寸:", Laya.stage.width, Laya.stage.height);
}

// 监听焦点变化
Laya.stage.on(Laya.Event.FOCUS, this, () => console.log("获得焦点"));
Laya.stage.on(Laya.Event.BLUR, this, () => console.log("失去焦点"));

// 监听可见性变化
Laya.stage.on(Laya.Event.VISIBILITY_CHANGE, this, onVisibilityChange);

function onVisibilityChange(): void {
   if (Laya.stage.isVisibility) {
      console.log("进入前台");
      Laya.stage.frameRate = Laya.Stage.FRAME_FAST;
   } else {
      console.log("进入后台");
      Laya.stage.frameRate = Laya.Stage.FRAME_SLOW;
   }
}

使用示例

基础初始化

class GameMain {
    constructor() {
        // 初始化引擎，设置设计尺寸
        Laya.init(1334, 750);

        // 设置屏幕适配模式
        this.setupScreen();

        // 设置背景颜色
        Laya.stage.bgColor = "#1e1e1e";
    }

    private setupScreen(): void {
        // 横屏游戏：固定高度，宽度自适应
        Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_HEIGHT;
        Laya.stage.screenMode = Laya.Stage.SCREEN_HORIZONTAL;

        // 居中对齐
        Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;
        Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;
    }
}

动态调整适配

// 根据屏幕比例动态选择适配模式
function adaptiveScreen(): void {
    const screenRatio = Laya.Browser.clientWidth / Laya.Browser.clientHeight;
    const designRatio = 1334 / 750;

    if (screenRatio > designRatio) {
        // 屏幕较宽，固定高度
        Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_HEIGHT;
    } else {
        // 屏幕较窄，固定宽度
        Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_WIDTH;
    }
}

获取鼠标位置

// 监听鼠标移动
Laya.stage.on(Laya.Event.MOUSE_MOVE, this, this.onMouseMove);

function onMouseMove(): void {
    const x = Laya.stage.mouseX;
    const y = Laya.stage.mouseY;
    console.log(`鼠标位置: (${x}, ${y})`);

    // 获取相对于特定节点的鼠标位置
    const localPos = sprite.globalToLocal(new Laya.Point(x, y));
    console.log(`相对位置: (${localPos.x}, ${localPos.y})`);
}

全屏控制

// 请求进入全屏
function enterFullscreen(): void {
    Laya.stage.fullScreenEnabled = true;
}

// 退出全屏
function exitFullscreen(): void {
    Laya.stage.exitFullscreen();
}

// 监听全屏状态变化
Laya.stage.on(Laya.Event.FULL_SCREEN_CHANGE, this, () => {
    console.log("全屏状态已改变");
});

性能优化

class PerformanceManager {
    constructor() {
        this.setupPerformance();
    }

    private setupPerformance(): void {
        // 前后台自动切换帧率
        Laya.stage.on(Laya.Event.VISIBILITY_CHANGE, this, this.onVisibilityChange);

        // 鼠标模式自动节能
        Laya.stage.frameRate = Laya.Stage.FRAME_MOUSE;
    }

    private onVisibilityChange(): void {
        if (Laya.stage.isVisibility) {
            // 前台：高帧率
            Laya.stage.frameRate = Laya.Stage.FRAME_FAST;
            Laya.stage.renderingEnabled = true;
        } else {
            // 后台：低帧率，停止渲染
            Laya.stage.frameRate = Laya.Stage.FRAME_SLOW;
            Laya.stage.renderingEnabled = false;
        }
    }
}

最佳实践

1. 横屏游戏适配

// 横屏游戏推荐配置
Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_HEIGHT;
Laya.stage.screenMode = Laya.Stage.SCREEN_HORIZONTAL;
Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;
Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;

2. 竖屏游戏适配

// 竖屏游戏推荐配置
Laya.stage.scaleMode = Laya.Stage.SCALE_FIXED_WIDTH;
Laya.stage.screenMode = Laya.Stage.SCREEN_VERTICAL;
Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;
Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;

3. UI 界面适配

// UI界面推荐：showall模式，确保内容完整显示
Laya.stage.scaleMode = Laya.Stage.SCALE_SHOWALL;
Laya.stage.alignH = Laya.Stage.ALIGN_CENTER;
Laya.stage.alignV = Laya.Stage.ALIGN_MIDDLE;

4. 前后台性能优化

Laya.stage.on(Laya.Event.VISIBILITY_CHANGE, this, () => {
    if (Laya.stage.isVisibility) {
        // 进入前台
        Laya.stage.renderingEnabled = true;
        Laya.stage.frameRate = Laya.Stage.FRAME_FAST;
        Laya.timer.resume();
    } else {
        // 进入后台
        Laya.stage.renderingEnabled = false;
        Laya.stage.frameRate = Laya.Stage.FRAME_SLOW;
        Laya.timer.pause();
    }
});

5. 动态帧率调整

class FrameRateController {
    private busy = false;

    setBusy(value: boolean): void {
        this.busy = value;
        Laya.stage.frameRate = value ?
            Laya.Stage.FRAME_FAST :
            Laya.Stage.FRAME_MOUSE;
    }

    // 在战斗或繁忙场景中调用
    enterBattle(): void {
        this.setBusy(true);
    }

    // 在空闲场景中调用
    enterIdle(): void {
        this.setBusy(false);
    }
}

注意事项

  1. 单例访问：Stage 只有一个实例，通过 Laya.stage 访问，不要手动创建

  2. 设计尺寸：设计尺寸应与美术资源尺寸保持一致，常见尺寸：

    • 竖屏：750×1334、720×1280
    • 横屏：1334×750、1280×720

  3. 适配模式选择：

    • 需要完整显示内容用 SCALE_SHOWALL
    • 需要填满屏幕用 SCALE_NOBORDER
    • 横屏游戏推荐 SCALE_FIXED_HEIGHT
    • 竖屏游戏推荐 SCALE_FIXED_WIDTH

  4. 性能优化：

    • 使用 FRAME_MOUSE 可自动节能
    • 后台时设置 renderingEnabled = false
    • 根据场景复杂度动态调整帧率

  5. 事件监听清理：注意在场景切换时清理 Stage 上的事件监听

# 游戏引擎 # 游戏程序 # typescript
Logo
2048 AI社区

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

更多推荐

cover

【2025最新】基于SpringBoot+Vue的小徐影城管理系统管理系统源码+MyBatis+MySQL

avatar 2048 AI社区
cover

本地部署 ChatGLM2-6B【保姆级教程】：从零搭建你的中英双语大模型对话助手

avatar 2048 AI社区
cover

Java Web 甘肃非物质文化网站系统源码-SpringBoot2+Vue3+MyBatis-Plus+MySQL8.0【含文档】

avatar 2048 AI社区