【Laya】Browser 使用说明

Laya.Browser API 文档

概述

Laya.Browser 是浏览器代理类,封装了浏览器及原生JavaScript提供的一些功能,也包括小游戏等运行环境的信息。通过这个类,开发者可以方便地获取设备信息、浏览器信息、屏幕尺寸等,并进行跨平台开发。


一、属性

1.1 设备和平台检测属性

属性名 类型 只读 描述
userAgent string ✓ 浏览器代理信息
onMobile boolean ✓ 当前环境是否为移动设备(iOS和Android)
onIOS boolean ✓ 当前环境是否在iOS设备内
onMac boolean ✓ 当前环境是否在Mac设备内
onIPhone boolean ✓ 当前环境是否在iPhone内
onIPad boolean ✓ 当前环境是否在iPad内
onAndroid boolean ✓ 当前环境是否在Android设备内
onOpenHarmonyOS boolean ✓ 当前环境是否在OpenHarmonyOS设备内
onWP boolean ✓ 当前环境是否在Windows Phone设备内
onQQBrowser boolean ✓ 当前环境是否在QQ浏览器内
onMQQBrowser boolean ✓ 当前环境是否在移动QQ或QQ浏览器内
onSafari boolean ✓ 当前环境是否在Safari内
onChrome boolean ✓ 当前环境是否在Chrome内
onIE boolean ✓ 当前环境是否在IE浏览器内
onWeiXin boolean ✓ 当前环境是否在微信内
onPC boolean ✓ 当前环境是否为PC
onWXMiniGame boolean ✓ 当前环境是否是微信小游戏
onBDMiniGame boolean ✓ 当前环境是否是百度小游戏
onKGMiniGame boolean ✓ 当前环境是否是小米小游戏
onQGMiniGame boolean ✓ 当前环境是否是OPPO小游戏
onVVMiniGame boolean ✓ 当前环境是否是vivo小游戏
onAlipayMiniGame boolean ✓ 当前环境是否是支付宝小游戏
onQQMiniGame boolean ✓ 当前环境是否是手机QQ小游戏
onBLMiniGame boolean ✓ 当前环境是否是BILIBILI小游戏
onTTMiniGame boolean ✓ 当前环境是否是抖音小游戏
onHWMiniGame boolean ✓ 当前环境是否是华为快游戏
onTBMiniGame boolean ✓ 当前环境是否是淘宝小游戏
onFirefox boolean ✓ 当前环境是否是Firefox浏览器
onEdge boolean ✓ 当前环境是否是Edge浏览器
onLayaRuntime boolean ✓ 当前环境是否运行在LayaAir Native Runtime
onDevTools boolean ✓ 当前环境是否运行在开发工具中

1.2 平台常量

常量名 值 描述
Laya.Browser.PLATFORM_PC 0 PC平台
Laya.Browser.PLATFORM_ANDROID 1 Android平台
Laya.Browser.PLATFORM_IOS 2 iOS平台

1.3 其他属性

属性名 类型 只读 描述
platform number ✓ 真实平台类型(通过UserAgent判断)
platformName string ✓ 平台的可读名称
isTouchDevice boolean ✓ 环境是否支持触摸输入
isIOSHighPerformanceMode boolean ✓ 环境是否支持iOS设备的高性能模式
isIOSHighPerformanceModePlus boolean ✓ 环境是否支持iOS设备的高性能+模式
isDomSupported boolean ✓ 环境是否支持DOM
systemVersion string ✓ 系统版本
SDKVersion string ✓ 平台SDK版本
mainCanvas HTMLCanvas ✓ 全局画布
canvas HTMLCanvas ✓ 全局离屏画布(用于测量文本和获取图像数据)
context CanvasRenderingContext2D ✓ 全局离屏画布上绘图的环境
bundles Map<string, any> ✓ 已载入的脚本集
window Window & typeof globalThis ✓ 原生window对象引用
document Document ✓ 原生document对象引用

二、方法

2.1 屏幕和尺寸相关

clientWidth
typescript 复制代码
static get clientWidth(): number

浏览器窗口的可视宽度。

返回值: 可视区域的宽度(像素)

typescript 复制代码
const width = Laya.Browser.clientWidth;
console.log("可视宽度:", width);
clientHeight
typescript 复制代码
static get clientHeight(): number

浏览器窗口的可视高度。

返回值: 可视区域的高度(像素)

typescript 复制代码
const height = Laya.Browser.clientHeight;
console.log("可视高度:", height);
width
typescript 复制代码
static get width(): number

浏览器窗口的物理宽度,考虑了设备像素比。

返回值: 物理宽度(像素)

typescript 复制代码
const physicalWidth = Laya.Browser.width;
console.log("物理宽度:", physicalWidth);
height
typescript 复制代码
static get height(): number

浏览器窗口的物理高度,考虑了设备像素比。

返回值: 物理高度(像素)

typescript 复制代码
const physicalHeight = Laya.Browser.height;
console.log("物理高度:", physicalHeight);
pixelRatio
typescript 复制代码
static get pixelRatio(): number

当前环境的设备像素比(DPR)。

返回值: 设备像素比(通常为1、2、3等)

typescript 复制代码
const dpr = Laya.Browser.pixelRatio;
console.log("设备像素比:", dpr);

2.2 DOM操作

createElement
typescript 复制代码
static createElement<K extends keyof HTMLElementTagNameMap>(tagName: K): HTMLElementTagNameMap[K]

创建指定类型的浏览器原生节点。

参数:

  • tagName: 要创建的节点类型

返回值: 创建的节点对象

typescript 复制代码
// 创建div元素
const div = Laya.Browser.createElement('div');
div.style.position = 'absolute';
div.style.width = '100px';
div.style.height = '100px';
div.style.backgroundColor = 'red';
Laya.Browser.document.body.appendChild(div);

// 创建iframe
const iframe = Laya.Browser.createElement('iframe');
iframe.style.position = 'absolute';
iframe.style.zIndex = "100";
iframe.src = 'http://ask.layaair.com/';
Laya.Browser.document.body.appendChild(iframe);

2.3 浏览器功能

now
typescript 复制代码
static now(): number

获取浏览器当前时间戳,单位为毫秒。等同于 performance.now()。

返回值: 时间戳(毫秒)

typescript 复制代码
const timestamp = Laya.Browser.now();
console.log("当前时间戳:", timestamp);
getQueryString
typescript 复制代码
static getQueryString(name: string): string

获取URL参数的值。

参数:

  • name: 参数名称

返回值: 参数值

typescript 复制代码
// URL: http://example.com/?name=John&age=25
const name = Laya.Browser.getQueryString('name');
const age = Laya.Browser.getQueryString('age');
console.log("姓名:", name);  // 输出: John
console.log("年龄:", age);   // 输出: 25
loadLib
typescript 复制代码
static loadLib(src: string, async?: boolean): Promise<void>

从指定源动态加载JavaScript库。

参数:

  • src: JavaScript库的URL
  • async: 是否异步加载(可选,默认为false)

返回值: Promise对象

typescript 复制代码
// 异步加载脚本
Laya.Browser.loadLib('https://cdn.example.com/library.js', true)
    .then(() => {
        console.log('脚本加载完成');
    })
    .catch(err => {
        console.error('脚本加载失败:', err);
    });

// 同步加载脚本
Laya.Browser.loadLib('https://cdn.example.com/library.js');

2.4 容器控制

container
typescript 复制代码
static get container(): HTMLElement

用来存放画布元素的容器。

返回值: 容器元素

typescript 复制代码
// 隐藏画布容器
Laya.Browser.container.style.display = 'none';

// 修改容器样式
Laya.Browser.container.style.backgroundColor = '#f0f0f0';

三、使用示例

3.1 屏幕适配

typescript 复制代码
// 获取屏幕信息
const screenWidth = Laya.Browser.clientWidth;
const screenHeight = Laya.Browser.clientHeight;
const physicalWidth = Laya.Browser.width;
const physicalHeight = Laya.Browser.height;
const dpr = Laya.Browser.pixelRatio;

console.log('逻辑分辨率:', screenWidth, 'x', screenHeight);
console.log('物理分辨率:', physicalWidth, 'x', physicalHeight);
console.log('设备像素比:', dpr);

// 根据设备像素比进行适配
if (dpr > 1) {
    console.log('检测到高DPI设备,已启用高清适配');
}

3.2 平台检测

typescript 复制代码
// 判断平台类型
function detectPlatform(): void {
    if (Laya.Browser.onMobile) {
        console.log('当前是移动设备');
        if (Laya.Browser.onIOS) {
            console.log('iOS设备');
            if (Laya.Browser.onIPhone) {
                console.log('iPhone');
            } else if (Laya.Browser.onIPad) {
                console.log('iPad');
            }
        } else if (Laya.Browser.onAndroid) {
            console.log('Android设备');
        }
    } else if (Laya.Browser.onPC) {
        console.log('PC设备');

        if (Laya.Browser.onChrome) {
            console.log('Chrome浏览器');
        } else if (Laya.Browser.onFirefox) {
            console.log('Firefox浏览器');
        } else if (Laya.Browser.onSafari) {
            console.log('Safari浏览器');
        }
    }
}

// 判断小游戏平台
function detectMiniGame(): void {
    if (Laya.Browser.onWXMiniGame) {
        console.log('微信小游戏环境');
        // 微信小游戏特定代码
    } else if (Laya.Browser.onTTMiniGame) {
        console.log('抖音小游戏环境');
        // 抖音小游戏特定代码
    } else if (Laya.Browser.onKGMiniGame) {
        console.log('小米小游戏环境');
        // 小米小游戏特定代码
    }
}

detectPlatform();
detectMiniGame();

3.3 创建自定义对话框

typescript 复制代码
function createCustomDialog(title: string, content: string): HTMLElement {
    // 创建对话框容器
    const dialog = Laya.Browser.createElement('div');
    dialog.style.position = 'fixed';
    dialog.style.left = '50%';
    dialog.style.top = '50%';
    dialog.style.transform = 'translate(-50%, -50%)';
    dialog.style.padding = '20px';
    dialog.style.backgroundColor = 'white';
    dialog.style.borderRadius = '8px';
    dialog.style.boxShadow = '0 4px 6px rgba(0, 0, 0, 0.1)';
    dialog.style.zIndex = '1000';

    // 创建标题
    const titleElement = Laya.Browser.createElement('h3');
    titleElement.textContent = title;
    titleElement.style.margin = '0 0 10px 0';
    dialog.appendChild(titleElement);

    // 创建内容
    const contentElement = Laya.Browser.createElement('p');
    contentElement.textContent = content;
    contentElement.style.margin = '0 0 20px 0';
    dialog.appendChild(contentElement);

    // 创建按钮
    const button = Laya.Browser.createElement('button');
    button.textContent = '确定';
    button.style.padding = '8px 16px';
    button.style.border = 'none';
    button.style.borderRadius = '4px';
    button.style.backgroundColor = '#007AFF';
    button.style.color = 'white';
    button.style.cursor = 'pointer';

    button.onclick = () => {
        Laya.Browser.document.body.removeChild(dialog);
    };

    dialog.appendChild(button);

    // 添加到页面
    Laya.Browser.document.body.appendChild(dialog);

    return dialog;
}

// 使用示例
createCustomDialog('提示', '这是一个自定义对话框!');

3.4 全屏控制

typescript 复制代码
const FullscreenUtil = {
    // 进入全屏
    enter(): void {
        const elem = Laya.Browser.container;
        if (elem.requestFullscreen) {
            elem.requestFullscreen();
        } else if ((elem as any).webkitRequestFullscreen) {
            (elem as any).webkitRequestFullscreen();
        } else if ((elem as any).msRequestFullscreen) {
            (elem as any).msRequestFullscreen();
        }
    },

    // 退出全屏
    exit(): void {
        if (document.exitFullscreen) {
            document.exitFullscreen();
        } else if ((document as any).webkitExitFullscreen) {
            (document as any).webkitExitFullscreen();
        } else if ((document as any).msExitFullscreen) {
            (document as any).msExitFullscreen();
        }
    },

    // 判断是否全屏
    isFullscreen(): boolean {
        return !!(
            document.fullscreenElement ||
            (document as any).webkitFullscreenElement ||
            (document as any).msFullscreenElement
        );
    },

    // 监听全屏变化
    onChange(callback: () => void): void {
        document.addEventListener('fullscreenchange', callback);
        document.addEventListener('webkitfullscreenchange', callback);
        document.addEventListener('msfullscreenchange', callback);
    }
};

// 使用示例
FullscreenUtil.onChange(() => {
    console.log('全屏状态改变:', FullscreenUtil.isFullscreen());
});

四、平台兼容性

4.1 浏览器兼容性

浏览器 版本支持 备注
Chrome 60+ 完全支持
Firefox 55+ 完全支持
Safari 12+ 完全支持
Edge 79+ 完全支持
IE 11 部分支持,推荐升级

4.2 小游戏平台支持

平台 支持状态
微信小游戏 完全支持
抖音小游戏 完全支持
小米小游戏 完全支持
OPPO小游戏 完全支持
vivo小游戏 完全支持
百度小游戏 完全支持
支付宝小游戏 完全支持
手机QQ小游戏 完全支持
华为快游戏 完全支持
淘宝小游戏 完全支持
BILIBILI小游戏 完全支持

4.3 注意事项

  1. DOM操作限制: 小游戏环境中,某些DOM操作可能受到限制
  2. 性能考虑: 频繁调用某些API可能影响性能,建议合理使用缓存
  3. 触摸事件: 移动端要注意触摸事件的兼容性处理
  4. 屏幕适配: 不同设备的屏幕尺寸和像素比差异较大,需要做好适配

五、最佳实践

  1. 使用 Laya. 前缀 : 始终使用 Laya.Browser 访问API,确保命名空间规范
  2. 平台检测: 在关键功能前进行平台检测,确保代码在目标平台正常运行
  3. 性能优化: 缓存频繁使用的属性值,避免重复计算
  4. 错误处理: 对可能失败的API调用进行错误处理
  5. 版本适配: 关注不同平台的版本差异,做好兼容性处理
相关推荐
濮水大叔2 天前
Cabloy/Zova 与 Next.js 的 SSR 水合差异
前端·typescript·next.js
深兰科技2 天前
走出进博展馆寻AI方案,巴西政商联合体参访深兰科技洽商中巴产业数字化合作
人工智能·typescript·深兰科技·中巴产业数字化·巴西政商联合体·ai方案·进博会
zdr尽职尽责3 天前
Unity 3C 动画系统:从「蜘蛛网」到可维护的动画架构
unity·架构·游戏引擎
FungLeo3 天前
成为全栈·Vue 管理后台篇·Biome、类型检查、构建和API 代理如何组成质量门禁
前端·javascript·vue.js·typescript·vite·前端工程化·biome
国家一级摸鱼选手3 天前
[Unity]几何碰撞检测:SAT 分离轴定理详解(从数学原理到 C# 实现)
unity·c#·游戏引擎·分离轴定理(sat)·多边形相交
泯泷4 天前
改一个字,整段都红了?——中文内容差异对比的算法与协议设计
前端·javascript·typescript
4cos904 天前
pi学习笔记-AgentLoop
typescript
暴走约伯5 天前
【VFX工具链源码拆解 09】终极工业化闭环:基于 ID 规则驱动的全自动场景建档、骨骼挂载与男转女场景迁移
unity·c#·游戏引擎·材质
afumu5 天前
让本机 Agent 指挥浏览器里的多个网页 AI:一套 127.0.0.1 控制协议的设计取舍
chrome·typescript
濮水大叔6 天前
Cabloy/Vona 为什么不需要 NestJS 的 Dynamic Module
typescript·node.js·nestjs